You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by ze...@apache.org on 2026/07/14 15:58:30 UTC

(iceberg-go) branch main updated: feat(rest): implement scan planning client methods (#1324)

This is an automated email from the ASF dual-hosted git repository.

zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git


The following commit(s) were added to refs/heads/main by this push:
     new ee3687ce feat(rest): implement scan planning client methods (#1324)
ee3687ce is described below

commit ee3687ced24d194c566579fd3dcc8a574dadb4ac
Author: Revanth <re...@gmail.com>
AuthorDate: Tue Jul 14 10:58:24 2026 -0500

    feat(rest): implement scan planning client methods (#1324)
---
 catalog/rest/endpoints.go          |   5 +
 catalog/rest/rest.go               | 194 ++++++++--
 catalog/rest/rest_internal_test.go | 172 ++++++++-
 catalog/rest/scan_planning.go      | 405 +++++++++++++++++++--
 catalog/rest/scan_planning_test.go | 707 +++++++++++++++++++++++++++++++++++++
 5 files changed, 1419 insertions(+), 64 deletions(-)

diff --git a/catalog/rest/endpoints.go b/catalog/rest/endpoints.go
index 7cc2dcf2..a4e86811 100644
--- a/catalog/rest/endpoints.go
+++ b/catalog/rest/endpoints.go
@@ -105,6 +105,10 @@ var (
 	endpointRegisterTable    = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/register"}
 	endpointReportMetrics    = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics"}
 	endpointTableCredentials = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials"}
+	endpointPlanTableScan    = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan"}
+	endpointFetchPlanResult  = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}"}
+	endpointCancelPlanning   = endpoint{http.MethodDelete, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}"}
+	endpointFetchScanTasks   = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/tasks"}
 
 	endpointListViews    = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/views"}
 	endpointLoadView     = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/views/{view}"}
@@ -148,6 +152,7 @@ var allEndpoints = []endpoint{
 	endpointListTables, endpointLoadTable, endpointTableExists, endpointCreateTable,
 	endpointUpdateTable, endpointDeleteTable, endpointRenameTable, endpointRegisterTable,
 	endpointReportMetrics, endpointTableCredentials,
+	endpointPlanTableScan, endpointFetchPlanResult, endpointCancelPlanning, endpointFetchScanTasks,
 	endpointListViews, endpointLoadView, endpointViewExists, endpointCreateView,
 	endpointUpdateView, endpointDeleteView, endpointRenameView, endpointRegisterView,
 	endpointListFunctions, endpointLoadFunction,
diff --git a/catalog/rest/rest.go b/catalog/rest/rest.go
index 8e8fbda5..1a66fa3d 100644
--- a/catalog/rest/rest.go
+++ b/catalog/rest/rest.go
@@ -73,6 +73,12 @@ const (
 	bearerPrefix        = "Bearer"
 	keyPrefix           = "prefix"
 
+	// headerIcebergAccessDelegation requests server-side storage-credential
+	// vending. It is a session default (defaultAccessDelegation) and a
+	// per-request header on the scan-planning endpoints that vend credentials.
+	headerIcebergAccessDelegation = "X-Iceberg-Access-Delegation"
+	defaultAccessDelegation       = "vended-credentials"
+
 	keyNamespaceSeparator     = "namespace-separator"
 	defaultNamespaceSeparator = "%1F"
 
@@ -228,10 +234,17 @@ type sessionTransport struct {
 const emptyStringHash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
 
 func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+	// A session default is applied unless the request already carries that
+	// header (a per-request override of any default, not just Content-Type
+	// wins) or explicitly opted out of it via withSuppressedHeaders (carried on
+	// the context as an explicit set, never inferred from header values).
+	suppressed := suppressedHeadersFrom(r.Context())
 	for k, v := range s.defaultHeaders {
-		// Skip Content-Type if it's already set in the request
-		// to avoid duplicate headers (e.g., when using PostForm)
-		if http.CanonicalHeaderKey(k) == "Content-Type" && r.Header.Get("Content-Type") != "" {
+		ck := http.CanonicalHeaderKey(k)
+		if _, ok := r.Header[ck]; ok {
+			continue
+		}
+		if _, ok := suppressed[ck]; ok {
 			continue
 		}
 		for _, hdr := range v {
@@ -239,6 +252,12 @@ func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
 		}
 	}
 
+	// Ordering is load-bearing: authManager runs after the default-header loop
+	// and Set-overwrites, so the managed auth header always wins even though the
+	// loop above lets an arbitrary per-request header (withHeaders) override a
+	// session default of the same key. A caller cannot suppress or spoof the
+	// Authorization header by supplying its own. Do not reorder this before the
+	// default-header loop.
 	if s.authManager != nil && r.Context().Value(skipOAuth) == nil {
 		k, v, err := s.authManager.AuthHeader()
 		if err != nil {
@@ -293,16 +312,117 @@ func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
 	return s.RoundTripper.RoundTrip(r)
 }
 
-func do[T any](ctx context.Context, method string, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, allowNoContent bool) (ret T, err error) {
+// suppressHeadersKey carries the set of session-default header keys (canonical
+// form) that a request opted out of, so sessionTransport.RoundTrip can consult
+// an explicit set rather than inferring suppression from header values.
+type suppressHeadersKey struct{}
+
+// reqConfig holds the optional per-request knobs shared by do and doPost:
+// headers to set, session-default headers to suppress, a body error.type ->
+// error override, and whether an HTTP 204 is a valid empty result.
+type reqConfig struct {
+	headers           map[string]string
+	suppressHeaders   []string
+	errorTypeOverride map[string]error
+	allowNoContent    bool
+	requireBody       bool
+}
+
+type reqOption func(*reqConfig)
+
+// withHeaders sets per-request headers, merging with any already set so options
+// compose. A per-request header takes precedence over a session default because
+// sessionTransport.RoundTrip skips any default whose key is already present.
+func withHeaders(headers map[string]string) reqOption {
+	return func(c *reqConfig) {
+		if c.headers == nil {
+			c.headers = make(map[string]string, len(headers))
+		}
+		maps.Copy(c.headers, headers)
+	}
+}
+
+// withSuppressedHeaders prevents the named session-default headers from being
+// sent on this request. Names accumulate so options compose. Suppression is
+// carried through the request context (see RoundTrip), not encoded as a header
+// value, so req.Header only ever means "headers to send".
+func withSuppressedHeaders(names ...string) reqOption {
+	return func(c *reqConfig) { c.suppressHeaders = append(c.suppressHeaders, names...) }
+}
+
+// withErrorTypeOverride maps a non-200 response to a specific error by the REST
+// error.type in the response body. It takes precedence over the status-code
+// override so a shared status (e.g. a 404 that can be a missing plan, table, or
+// namespace) can split into distinct sentinels. Entries accumulate so options
+// compose; an unset or unmatched error.type falls through to the status-code
+// override.
+func withErrorTypeOverride(byType map[string]error) reqOption {
+	return func(c *reqConfig) {
+		if c.errorTypeOverride == nil {
+			c.errorTypeOverride = make(map[string]error, len(byType))
+		}
+		maps.Copy(c.errorTypeOverride, byType)
+	}
+}
+
+// allowNoContent treats an HTTP 204 No Content response as a valid empty result
+// rather than trying to decode a body.
+func allowNoContent() reqOption {
+	return func(c *reqConfig) { c.allowNoContent = true }
+}
+
+// requireBody rejects an HTTP 200 with an empty body rather than decoding it to
+// the zero result. Use it when a 200 must carry a payload, so a truncated or
+// proxy-stripped response cannot masquerade as a successful empty result (e.g.
+// fetchScanTasks returning "zero tasks" and silently dropping work).
+func requireBody() reqOption {
+	return func(c *reqConfig) { c.requireBody = true }
+}
+
+func newReqConfig(opts []reqOption) reqConfig {
+	var cfg reqConfig
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+
+	return cfg
+}
+
+// withSuppressedHeadersCtx returns ctx carrying the canonicalized suppression
+// set, or ctx unchanged when nothing is suppressed.
+func withSuppressedHeadersCtx(ctx context.Context, names []string) context.Context {
+	if len(names) == 0 {
+		return ctx
+	}
+
+	set := make(map[string]struct{}, len(names))
+	for _, n := range names {
+		set[http.CanonicalHeaderKey(n)] = struct{}{}
+	}
+
+	return context.WithValue(ctx, suppressHeadersKey{}, set)
+}
+
+func suppressedHeadersFrom(ctx context.Context) map[string]struct{} {
+	set, _ := ctx.Value(suppressHeadersKey{}).(map[string]struct{})
+
+	return set
+}
+
+func do[T any](ctx context.Context, method string, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+	cfg := newReqConfig(opts)
+
 	var (
 		req *http.Request
 		rsp *http.Response
 	)
 
 	uri := baseURI.JoinPath(path...).String()
+	ctx = withSuppressedHeadersCtx(ctx, cfg.suppressHeaders)
 	if req, err = http.NewRequestWithContext(ctx, method, uri, nil); err != nil {
 		return ret, err
 	}
+	setRequestHeaders(req, cfg.headers)
 
 	if rsp, err = cl.Do(req); err != nil {
 		return ret, err
@@ -312,12 +432,12 @@ func do[T any](ctx context.Context, method string, baseURI *url.URL, path []stri
 		_ = rsp.Body.Close()
 	}()
 
-	if allowNoContent && rsp.StatusCode == http.StatusNoContent {
+	if cfg.allowNoContent && rsp.StatusCode == http.StatusNoContent {
 		return ret, err
 	}
 
 	if rsp.StatusCode != http.StatusOK {
-		return ret, handleNon200(rsp, override)
+		return ret, handleNon200(rsp, override, cfg.errorTypeOverride)
 	}
 
 	if method == http.MethodHead || method == http.MethodDelete {
@@ -331,25 +451,23 @@ func do[T any](ctx context.Context, method string, baseURI *url.URL, path []stri
 	return ret, err
 }
 
-func doGet[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) (ret T, err error) {
-	return do[T](ctx, http.MethodGet, baseURI, path, cl, override, false)
+func doGet[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+	return do[T](ctx, http.MethodGet, baseURI, path, cl, override, opts...)
 }
 
-func doDelete[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) (ret T, err error) {
-	return do[T](ctx, http.MethodDelete, baseURI, path, cl, override, true)
+func doDelete[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+	return do[T](ctx, http.MethodDelete, baseURI, path, cl, override, append([]reqOption{allowNoContent()}, opts...)...)
 }
 
 func doHead(ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) error {
-	_, err := do[struct{}](ctx, http.MethodHead, baseURI, path, cl, override, true)
+	_, err := do[struct{}](ctx, http.MethodHead, baseURI, path, cl, override, allowNoContent())
 
 	return err
 }
 
-func doPost[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error) (ret Result, err error) {
-	return doPostAllowNoContent[Payload, Result](ctx, baseURI, path, payload, cl, override, false)
-}
+func doPost[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error, opts ...reqOption) (ret Result, err error) {
+	cfg := newReqConfig(opts)
 
-func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error, allowNoContent bool) (ret Result, err error) {
 	var (
 		req  *http.Request
 		rsp  *http.Response
@@ -362,10 +480,12 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
 		return ret, err
 	}
 
+	ctx = withSuppressedHeadersCtx(ctx, cfg.suppressHeaders)
 	req, err = http.NewRequestWithContext(ctx, http.MethodPost, uri, bytes.NewReader(data))
 	if err != nil {
 		return ret, err
 	}
+	setRequestHeaders(req, cfg.headers)
 
 	rsp, err = cl.Do(req)
 	if err != nil {
@@ -376,15 +496,19 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
 		_ = rsp.Body.Close()
 	}()
 
-	if allowNoContent && rsp.StatusCode == http.StatusNoContent {
+	if cfg.allowNoContent && rsp.StatusCode == http.StatusNoContent {
 		return ret, err
 	}
 
 	if rsp.StatusCode != http.StatusOK {
-		return ret, handleNon200(rsp, override)
+		return ret, handleNon200(rsp, override, cfg.errorTypeOverride)
 	}
 
 	if rsp.ContentLength == 0 {
+		if cfg.requireBody {
+			return ret, fmt.Errorf("%w: empty response body on %s %s", ErrRESTError, req.Method, req.URL.Path)
+		}
+
 		return ret, err
 	}
 
@@ -395,7 +519,13 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
 	return ret, err
 }
 
-func handleNon200(rsp *http.Response, override map[int]error) error {
+func setRequestHeaders(req *http.Request, headers map[string]string) {
+	for k, v := range headers {
+		req.Header.Set(k, v)
+	}
+}
+
+func handleNon200(rsp *http.Response, override map[int]error, typeOverride map[string]error) error {
 	var e errorResponse
 
 	// Only try to decode if there's a body (HEAD requests don't have one)
@@ -420,9 +550,23 @@ func handleNon200(rsp *http.Response, override map[int]error) error {
 		}
 	}
 
+	// The status-code override maps a status to a sentinel; a body error.type
+	// override refines it further (e.g. splitting a 404 into missing-plan vs.
+	// table vs. namespace). The type refinement only applies to a status the
+	// caller already mapped, because these error.type values are defined for
+	// specific statuses (404) in the REST spec: a 503 body carrying, say,
+	// NoSuchPlanIdException must still resolve to ErrServiceUnavailable rather
+	// than a 404 sentinel.
 	if override != nil {
-		if err, ok := override[rsp.StatusCode]; ok {
-			e.wrapping = err
+		if statusErr, ok := override[rsp.StatusCode]; ok {
+			if typeOverride != nil && e.Type != "" {
+				if typeErr, ok := typeOverride[e.Type]; ok {
+					e.wrapping = typeErr
+
+					return e
+				}
+			}
+			e.wrapping = statusErr
 
 			return e
 		}
@@ -768,7 +912,7 @@ func (r *Catalog) createSession(ctx context.Context, opts *options) (*http.Clien
 	session.defaultHeaders.Set("X-Client-Version", icebergRestSpecVersion)
 	session.defaultHeaders.Set("Content-Type", "application/json")
 	session.defaultHeaders.Set("User-Agent", "GoIceberg/"+iceberg.Version())
-	session.defaultHeaders.Set("X-Iceberg-Access-Delegation", "vended-credentials")
+	session.defaultHeaders.Set(headerIcebergAccessDelegation, defaultAccessDelegation)
 
 	for k, v := range opts.headers {
 		session.defaultHeaders.Set(k, v)
@@ -1259,7 +1403,7 @@ func (r *Catalog) CommitTransaction(ctx context.Context, commits []table.TableCo
 		return err
 	}
 
-	_, err = doPostAllowNoContent[payload, struct{}](
+	_, err = doPost[payload, struct{}](
 		ctx, r.baseURI, path,
 		payload{TableChanges: changes}, r.cl,
 		map[int]error{
@@ -1270,7 +1414,7 @@ func (r *Catalog) CommitTransaction(ctx context.Context, commits []table.TableCo
 			http.StatusServiceUnavailable:  ErrCommitStateUnknown,
 			http.StatusGatewayTimeout:      ErrCommitStateUnknown,
 		},
-		true,
+		allowNoContent(),
 	)
 
 	return err
@@ -1468,8 +1612,8 @@ func (r *Catalog) RenameTable(ctx context.Context, from, to table.Identifier) (*
 		return nil, err
 	}
 
-	_, err = doPostAllowNoContent[payload, any](ctx, r.baseURI, path, payload{Source: src, Destination: dst}, r.cl,
-		map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, true)
+	_, err = doPost[payload, any](ctx, r.baseURI, path, payload{Source: src, Destination: dst}, r.cl,
+		map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, allowNoContent())
 	if err != nil {
 		return nil, err
 	}
diff --git a/catalog/rest/rest_internal_test.go b/catalog/rest/rest_internal_test.go
index 24782cb4..18992eec 100644
--- a/catalog/rest/rest_internal_test.go
+++ b/catalog/rest/rest_internal_test.go
@@ -913,6 +913,111 @@ func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
 	return f(r)
 }
 
+func TestRoundTripDefaultHeaderHandling(t *testing.T) {
+	t.Parallel()
+
+	newSession := func(captured *http.Header) *sessionTransport {
+		s := &sessionTransport{
+			RoundTripper: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+				*captured = r.Header.Clone()
+
+				return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+			}),
+			defaultHeaders: http.Header{},
+		}
+		s.defaultHeaders.Set(headerIcebergAccessDelegation, defaultAccessDelegation)
+
+		return s
+	}
+
+	t.Run("applies default when absent", func(t *testing.T) {
+		t.Parallel()
+
+		var got http.Header
+		req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+		require.NoError(t, err)
+		_, err = newSession(&got).RoundTrip(req)
+		require.NoError(t, err)
+		assert.Equal(t, []string{defaultAccessDelegation}, got.Values(headerIcebergAccessDelegation))
+	})
+
+	t.Run("per-request value overrides default without duplicating", func(t *testing.T) {
+		t.Parallel()
+
+		var got http.Header
+		req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+		require.NoError(t, err)
+		req.Header.Set(headerIcebergAccessDelegation, "remote-signing")
+		_, err = newSession(&got).RoundTrip(req)
+		require.NoError(t, err)
+		assert.Equal(t, []string{"remote-signing"}, got.Values(headerIcebergAccessDelegation))
+	})
+
+	t.Run("context suppression drops the default", func(t *testing.T) {
+		t.Parallel()
+
+		var got http.Header
+		ctx := withSuppressedHeadersCtx(context.Background(), []string{headerIcebergAccessDelegation})
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://example.com", nil)
+		require.NoError(t, err)
+		_, err = newSession(&got).RoundTrip(req)
+		require.NoError(t, err)
+		assert.Empty(t, got.Values(headerIcebergAccessDelegation))
+	})
+}
+
+// staticAuthManager is a test AuthManager returning a fixed authorization header.
+type staticAuthManager struct {
+	key, value string
+}
+
+func (s staticAuthManager) AuthHeader() (string, string, error) { return s.key, s.value, nil }
+
+func TestRoundTripAuthManagerWinsOverPerRequestHeader(t *testing.T) {
+	t.Parallel()
+
+	// The generalized per-request override lets withHeaders replace a session
+	// default of the same key, but the managed Authorization header must still
+	// win: authManager runs after the default-header loop and Set-overwrites, so
+	// a caller cannot suppress or spoof it via withHeaders. This pins that
+	// ordering, which is load-bearing but otherwise implicit.
+	var got http.Header
+	s := &sessionTransport{
+		RoundTripper: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+			got = r.Header.Clone()
+
+			return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+		}),
+		defaultHeaders: http.Header{},
+		authManager:    staticAuthManager{key: "Authorization", value: "Bearer managed-token"},
+	}
+
+	req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+	require.NoError(t, err)
+	req.Header.Set("Authorization", "Bearer caller-supplied")
+
+	_, err = s.RoundTrip(req)
+	require.NoError(t, err)
+	assert.Equal(t, []string{"Bearer managed-token"}, got.Values("Authorization"))
+}
+
+func TestReqOptionsCompose(t *testing.T) {
+	t.Parallel()
+
+	cfg := newReqConfig([]reqOption{
+		withHeaders(map[string]string{"X-First": "one"}),
+		withHeaders(map[string]string{"X-Second": "two"}),
+		withSuppressedHeaders("X-First"),
+		withSuppressedHeaders("X-Second", "X-Third"),
+	})
+
+	assert.Equal(t, map[string]string{
+		"X-First":  "one",
+		"X-Second": "two",
+	}, cfg.headers)
+	assert.Equal(t, []string{"X-First", "X-Second", "X-Third"}, cfg.suppressHeaders)
+}
+
 type closeTrackingReadCloser struct {
 	*bytes.Reader
 	closeErr error
@@ -1214,22 +1319,22 @@ func TestResponseBodyLeak(t *testing.T) {
 		baseURI, err := url.Parse(srv.URL)
 		require.NoError(t, err)
 
-		_, err = do[struct{}](context.Background(), http.MethodGet, baseURI, []string{"test"}, client, nil, false)
+		_, err = do[struct{}](context.Background(), http.MethodGet, baseURI, []string{"test"}, client, nil)
 		require.Error(t, err)
 
 		assert.True(t, tracker.body.closed,
 			"response body should be closed on non-200 status")
 	})
 
-	t.Run("doPostAllowNoContent", func(t *testing.T) {
+	t.Run("doPost", func(t *testing.T) {
 		tracker := &trackingTransport{transport: http.DefaultTransport}
 		client := &http.Client{Transport: tracker}
 
 		baseURI, err := url.Parse(srv.URL)
 		require.NoError(t, err)
 
-		_, err = doPostAllowNoContent[map[string]string, struct{}](
-			context.Background(), baseURI, []string{"test"}, map[string]string{"key": "value"}, client, nil, false)
+		_, err = doPost[map[string]string, struct{}](
+			context.Background(), baseURI, []string{"test"}, map[string]string{"key": "value"}, client, nil, allowNoContent())
 		require.Error(t, err)
 
 		assert.True(t, tracker.body.closed,
@@ -1244,7 +1349,7 @@ func TestHandleNon200_DecodeFlatMessagePreservesSentinel(t *testing.T) {
 		Body:          io.NopCloser(bytes.NewBufferString(`{"message":"flat error"}`)),
 	}
 
-	err := handleNon200(rsp, nil)
+	err := handleNon200(rsp, nil, nil)
 	require.Error(t, err)
 	require.Equal(t, "flat error", err.Error())
 	require.True(t, errors.Is(err, ErrBadRequest))
@@ -1257,7 +1362,7 @@ func TestHandleNon200_DecodeCanonicalErrorRendersExpectedMessage(t *testing.T) {
 		Body:          io.NopCloser(bytes.NewBufferString(`{"error":{"message":"nested error","type":"ValidationException"}}`)),
 	}
 
-	err := handleNon200(rsp, nil)
+	err := handleNon200(rsp, nil, nil)
 	require.Error(t, err)
 	require.Equal(t, "ValidationException: nested error", err.Error())
 	require.True(t, errors.Is(err, ErrForbidden))
@@ -1270,13 +1375,66 @@ func TestHandleNon200_EmptyBodyFallback(t *testing.T) {
 		Body:          http.NoBody,
 	}
 
-	err := handleNon200(rsp, nil)
+	err := handleNon200(rsp, nil, nil)
 	require.Error(t, err)
 	require.True(t, errors.Is(err, ErrBadRequest))
 	require.Equal(t, ErrBadRequest.Error(), err.Error())
 	require.NotEqual(t, ": ", err.Error())
 }
 
+func TestHandleNon200_ErrorTypeOverride(t *testing.T) {
+	t.Parallel()
+
+	sentinelByType := errors.New("mapped by type")
+	sentinelByStatus := errors.New("mapped by status")
+	typeOverride := map[string]error{"NoSuchThingException": sentinelByType}
+	statusOverride := map[int]error{http.StatusNotFound: sentinelByStatus}
+
+	newRsp := func(status int, body string) *http.Response {
+		return &http.Response{
+			StatusCode:    status,
+			ContentLength: int64(len(body)),
+			Body:          io.NopCloser(bytes.NewBufferString(body)),
+		}
+	}
+
+	t.Run("error.type override wins over status override", func(t *testing.T) {
+		t.Parallel()
+
+		err := handleNon200(newRsp(http.StatusNotFound, `{"error":{"type":"NoSuchThingException","message":"gone"}}`), statusOverride, typeOverride)
+		require.ErrorIs(t, err, sentinelByType)
+		assert.NotErrorIs(t, err, sentinelByStatus)
+	})
+
+	t.Run("unmatched error.type falls through to status override", func(t *testing.T) {
+		t.Parallel()
+
+		err := handleNon200(newRsp(http.StatusNotFound, `{"error":{"type":"SomethingElse","message":"gone"}}`), statusOverride, typeOverride)
+		require.ErrorIs(t, err, sentinelByStatus)
+		assert.NotErrorIs(t, err, sentinelByType)
+	})
+
+	t.Run("empty body falls through to status override", func(t *testing.T) {
+		t.Parallel()
+
+		rsp := &http.Response{StatusCode: http.StatusNotFound, ContentLength: 0, Body: http.NoBody}
+		err := handleNon200(rsp, statusOverride, typeOverride)
+		require.ErrorIs(t, err, sentinelByStatus)
+		assert.NotErrorIs(t, err, sentinelByType)
+	})
+
+	t.Run("type override ignored on an unmapped status", func(t *testing.T) {
+		t.Parallel()
+
+		// The error.type values are defined for 404 in the spec; a 503 carrying
+		// one must resolve on status (ErrServiceUnavailable), not a 404 sentinel.
+		err := handleNon200(newRsp(http.StatusServiceUnavailable, `{"error":{"type":"NoSuchThingException","message":"down"}}`), statusOverride, typeOverride)
+		require.ErrorIs(t, err, ErrServiceUnavailable)
+		assert.NotErrorIs(t, err, sentinelByType)
+		assert.NotErrorIs(t, err, sentinelByStatus)
+	})
+}
+
 func TestErrorResponse_ErrorFormattingTypeAndMessage(t *testing.T) {
 	err := errorResponse{Type: "ValidationException", Message: "bad request"}
 	require.Equal(t, "ValidationException: bad request", err.Error())
diff --git a/catalog/rest/scan_planning.go b/catalog/rest/scan_planning.go
index 062567f3..582dd58d 100644
--- a/catalog/rest/scan_planning.go
+++ b/catalog/rest/scan_planning.go
@@ -15,13 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
-// This file is a PROPOSED public API surface for REST server-side scan
-// planning (apache/iceberg-go#1178). The method bodies are intentionally
-// unimplemented stubs (returning ErrNotImplemented) so the REST surface can be
-// reviewed as Go — with one exception: PlanTableScanResponse.UnmarshalJSON
-// validates the status/plan-id union (with tests), added per review.
-// Endpoint capability discovery (Endpoint, SupportsEndpoint) lands separately
-// in the Phase 0 PR and is intentionally not redeclared here.
+// This file contains the REST server-side scan planning client surface for
+// apache/iceberg-go#1178. Low-level client methods and endpoint capability
+// checks are implemented here; higher-level orchestration, scanner delegation,
+// expression wrappers, and scan-task content decoding land in follow-up phases.
 
 package rest
 
@@ -29,44 +26,152 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
 	"time"
 
 	"github.com/apache/iceberg-go"
+	"github.com/apache/iceberg-go/catalog"
 	"github.com/apache/iceberg-go/table"
+	"github.com/google/uuid"
 )
 
 // Compile-time proof that the REST catalog satisfies the table planner seam.
 var _ table.ScanPlanner = (*Catalog)(nil)
 
-// ErrPlanExpired is returned when polling a plan-id the server no longer knows
-// about (HTTP 404 while polling), distinct from a table-not-found 404.
+// ErrPlanExpired is returned when polling a plan that the server no longer
+// knows about: a fetchPlanningResult 404 whose error.type is exactly
+// NoSuchPlanIdException. It is distinct from a table/namespace-gone 404
+// (catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace) so the polling layer can
+// tell retry-with-a-new-plan from abort. A bare or unrecognized 404 stays an
+// ambiguous ErrRESTError rather than being guessed as an expiry.
 var ErrPlanExpired = fmt.Errorf("%w: scan plan expired", ErrRESTError)
 
-// --- Capability gating (Open Question 2) ------------------------------------
+// ErrNoSuchPlanTask is returned when fetchScanTasks is called with a plan-task
+// handle the server no longer knows about: a 404 whose error.type is
+// NoSuchPlanTaskException. It is distinct from a table/namespace-gone 404 so a
+// caller fanning out over plan-task handles can tell an expired handle from the
+// table having vanished.
+var ErrNoSuchPlanTask = fmt.Errorf("%w: scan plan task not found", ErrRESTError)
+
+// ErrPlanFailed is returned by PlanTableScan and FetchPlanningResult when the
+// server reports a failed plan. The returned error is a *PlanFailedError, so the
+// structured PlanningError detail is reachable via errors.As.
+var ErrPlanFailed = fmt.Errorf("%w: scan plan failed", ErrRESTError)
+
+// ErrPlanCancelled is returned by FetchPlanningResult when polling a plan that
+// was cancelled (by this client or another). Like a failed plan it is terminal,
+// so it surfaces as an error rather than a (resp, nil) the if-err idiom skips.
+var ErrPlanCancelled = fmt.Errorf("%w: scan plan cancelled", ErrRESTError)
+
+// REST error.type values the scan-planning 404 responses carry. The spec models
+// a 404 on these endpoints as one of several distinct not-found conditions;
+// each maps to its own sentinel so the polling/fanout layer can tell a
+// retry-able expiry from a table/namespace-gone abort. Only these recognized
+// types get a specific sentinel; a bare or unrecognized 404 provides no basis to
+// choose one over another and stays an ambiguous ErrRESTError (the status-code
+// fallback). The strings are the ErrorModel `type` values from the REST OpenAPI
+// spec (the exception class simple names Java's RESTCatalog raises).
+const (
+	errTypeNoSuchPlanID    = "NoSuchPlanIdException"
+	errTypeNoSuchPlanTask  = "NoSuchPlanTaskException"
+	errTypeNoSuchTable     = "NoSuchTableException"
+	errTypeNoSuchNamespace = "NoSuchNamespaceException"
+)
+
+// planTableScanErrorTypes splits a POST .../plan 404 by error.type: the plan
+// endpoint takes an identifier but no plan-id, so a recognized 404 is a missing
+// table or namespace. An unrecognized 404 stays ErrRESTError.
+var planTableScanErrorTypes = map[string]error{
+	errTypeNoSuchTable:     catalog.ErrNoSuchTable,
+	errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// fetchPlanningResultErrorTypes splits a GET .../plan/{plan-id} 404: a forgotten
+// plan-id is retry-with-a-new-plan (ErrPlanExpired), while a gone table or
+// namespace is an abort. An unrecognized 404 stays ErrRESTError.
+var fetchPlanningResultErrorTypes = map[string]error{
+	errTypeNoSuchPlanID:    ErrPlanExpired,
+	errTypeNoSuchTable:     catalog.ErrNoSuchTable,
+	errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// fetchScanTasksErrorTypes splits a POST .../tasks 404: an expired plan-task
+// handle (ErrNoSuchPlanTask) is distinct from a gone table or namespace. An
+// unrecognized 404 stays ErrRESTError.
+var fetchScanTasksErrorTypes = map[string]error{
+	errTypeNoSuchPlanTask:  ErrNoSuchPlanTask,
+	errTypeNoSuchTable:     catalog.ErrNoSuchTable,
+	errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// PlanFailedError carries the server's structured PlanningError detail for a
+// failed plan. It satisfies errors.Is(err, ErrPlanFailed) so callers can branch
+// on the failure with the if-err idiom while still reaching the detail via
+// errors.As.
+type PlanFailedError struct {
+	Detail *PlanningError
+}
+
+func (e *PlanFailedError) Error() string {
+	if e.Detail != nil && e.Detail.Message != "" {
+		return ErrPlanFailed.Error() + ": " + e.Detail.Message
+	}
+
+	return ErrPlanFailed.Error()
+}
+
+func (e *PlanFailedError) Unwrap() error { return ErrPlanFailed }
+
+// headerIdempotencyKey is the per-request idempotency key on the plan and tasks
+// POSTs. The access-delegation header name lives in rest.go because it is also
+// a session default.
+const headerIdempotencyKey = "Idempotency-Key"
+
+// --- Capability gating -------------------------------------------------------
 //
-// A single capability check is too coarse: requiring all four endpoints falls
-// back to local against sync-only servers, while requiring only the plan
-// endpoint false-positives, because planTableScan can return `submitted` or
-// `plan-tasks` that need the poll/fetch endpoints. The split below lets `auto`
-// use a sync-only server while reserving the async/fanout path for servers
-// that advertise everything.
+// Capability is split into two predicates. SupportsPlanTableScan is the narrow
+// "server can plan inline" check (plan endpoint only). SupportsFullRemoteScanPlanning
+// is the endpoint-level "server advertises all four endpoints" check: an
+// end-to-end plan can come back `submitted` or with `plan-tasks` that need the
+// poll/cancel/fetch endpoints to finish, and auto mode has no second chance to
+// fall back to local once it commits to remote, so a plan-only server must not
+// count as end-to-end capable.
+//
+// SupportsRemoteScanPlanning is the table.ScanPlanner-facing predicate that
+// table.Scan's auto mode routes on. It is deliberately gated to false while
+// PlanFiles is an unimplemented stub: routing on endpoint capability alone would
+// send an auto-mode scan into PlanFiles and surface ErrNotImplemented instead of
+// falling back to local planning. It flips on with the PlanFiles phase.
 
 // SupportsPlanTableScan reports whether the server advertised the synchronous
 // plan endpoint.
 func (r *Catalog) SupportsPlanTableScan() bool {
-	return false
+	return r.endpoints.contains(endpointPlanTableScan)
 }
 
 // SupportsFullRemoteScanPlanning reports whether the server advertised all four
-// scan-planning endpoints (plan, fetch-result, cancel, fetch-tasks).
+// scan-planning endpoints (plan, fetch-result, cancel, fetch-tasks), i.e. it can
+// drive the async/fanout path, not just sync inline planning.
 func (r *Catalog) SupportsFullRemoteScanPlanning() bool {
-	return false
+	return r.SupportsPlanTableScan() &&
+		r.endpoints.contains(endpointFetchPlanResult) &&
+		r.endpoints.contains(endpointCancelPlanning) &&
+		r.endpoints.contains(endpointFetchScanTasks)
 }
 
 // --- table.ScanPlanner implementation ---------------------------------------
 
 // SupportsRemoteScanPlanning reports whether this catalog can complete a remote
-// plan end-to-end; backed by the split capability checks above.
+// plan end-to-end. table.Scan's auto mode routes on it, calling PlanFiles when it
+// is true, so it must stay false until PlanFiles is implemented — otherwise an
+// auto-mode scan against a server advertising all four endpoints would fail with
+// ErrNotImplemented instead of falling back to local planning.
+//
+// TODO(#1178): return SupportsFullRemoteScanPlanning() once PlanFiles is wired
+// end-to-end. Until then, callers probing endpoint capability should use
+// SupportsFullRemoteScanPlanning / SupportsPlanTableScan directly.
 func (r *Catalog) SupportsRemoteScanPlanning() bool {
 	return false
 }
@@ -79,30 +184,145 @@ func (r *Catalog) PlanFiles(ctx context.Context, req table.ScanPlanningRequest)
 
 // --- Low-level client methods -----------------------------------------------
 
-// PlanTableScan submits a scan plan. The result is either completed inline,
-// submitted (returns a plan-id to poll), or failed.
+// PlanTableScan submits a scan plan. A completed or submitted plan returns
+// (resp, nil); callers branch on resp.Status for the plan-id (completed) vs
+// poll (submitted) distinction. A failed plan returns a zero response and a
+// non-nil *PlanFailedError (errors.Is(err, ErrPlanFailed)) so the if-err idiom
+// does not mistake a failure for success; the server detail rides on the error.
+// Any other status — including the empty status of a 200 with no body, which
+// bypasses the response UnmarshalJSON validation — returns an ErrRESTError so a
+// malformed response cannot masquerade as an empty completed plan.
 func (r *Catalog) PlanTableScan(ctx context.Context, ident table.Identifier, req PlanTableScanRequest) (PlanTableScanResponse, error) {
-	return PlanTableScanResponse{}, fmt.Errorf("%w: plan table scan", iceberg.ErrNotImplemented)
+	if err := r.endpoints.check(endpointPlanTableScan); err != nil {
+		return PlanTableScanResponse{}, err
+	}
+
+	path, err := r.scanPlanningPath(endpointPlanTableScan, ident)
+	if err != nil {
+		return PlanTableScanResponse{}, err
+	}
+
+	headers, err := scanPlanningHeaders(req.IdempotencyKey, req.AccessDelegation, true)
+	if err != nil {
+		return PlanTableScanResponse{}, err
+	}
+
+	resp, err := doPost[PlanTableScanRequest, PlanTableScanResponse](
+		ctx, r.baseURI, path, req, r.cl,
+		map[int]error{http.StatusNotFound: ErrRESTError},
+		withHeaders(headers), withErrorTypeOverride(planTableScanErrorTypes))
+	if err != nil {
+		return PlanTableScanResponse{}, err
+	}
+	switch resp.Status {
+	case PlanStatusCompleted, PlanStatusSubmitted:
+		return resp, nil
+	case PlanStatusFailed:
+		return PlanTableScanResponse{}, &PlanFailedError{Detail: resp.Error}
+	default:
+		return PlanTableScanResponse{}, fmt.Errorf(
+			"%w: planTableScan response has invalid status %q", ErrRESTError, resp.Status)
+	}
 }
 
 // FetchPlanningResult polls a previously submitted plan. opts.AccessDelegation
 // is sent as the X-Iceberg-Access-Delegation header so an async poll can still
 // receive plan-scoped storage credentials: the spec defines data-access on this
 // endpoint, and the completed-async result is where those credentials are vended.
+//
+// completed and submitted return (resp, nil) and callers branch on resp.Status
+// (done vs poll again). The terminal failure states surface as errors so an
+// if-err poll loop cannot mistake them for an empty scan: failed returns a
+// *PlanFailedError (errors.Is(err, ErrPlanFailed)) and cancelled returns
+// ErrPlanCancelled. A 404 is split by the response error.type: a forgotten
+// plan-id (NoSuchPlanIdException) is ErrPlanExpired, while a gone table or
+// namespace is catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace, so the poller
+// can tell retry-with-a-new-plan from abort. A bare or unrecognized 404 stays an
+// ambiguous ErrRESTError rather than being guessed as an expiry.
 func (r *Catalog) FetchPlanningResult(ctx context.Context, ident table.Identifier, planID string, opts FetchPlanningResultOptions) (FetchPlanningResultResponse, error) {
-	return FetchPlanningResultResponse{}, fmt.Errorf("%w: fetch planning result", iceberg.ErrNotImplemented)
+	if err := r.endpoints.check(endpointFetchPlanResult); err != nil {
+		return FetchPlanningResultResponse{}, err
+	}
+
+	path, err := r.scanPlanningPath(endpointFetchPlanResult, ident, planID)
+	if err != nil {
+		return FetchPlanningResultResponse{}, err
+	}
+
+	headers, err := scanPlanningHeaders(nil, opts.AccessDelegation, false)
+	if err != nil {
+		return FetchPlanningResultResponse{}, err
+	}
+
+	resp, err := doGet[FetchPlanningResultResponse](
+		ctx, r.baseURI, path, r.cl,
+		map[int]error{http.StatusNotFound: ErrRESTError},
+		withHeaders(headers), withErrorTypeOverride(fetchPlanningResultErrorTypes))
+	if err != nil {
+		return FetchPlanningResultResponse{}, err
+	}
+	switch resp.Status {
+	case PlanStatusFailed:
+		return FetchPlanningResultResponse{}, &PlanFailedError{Detail: resp.Error}
+	case PlanStatusCancelled:
+		return FetchPlanningResultResponse{}, ErrPlanCancelled
+	}
+
+	return resp, nil
 }
 
 // CancelPlanning cancels a server-side plan. Callers should cancel on context
-// cancellation using a detached context with a short timeout.
+// cancellation using a detached context with a short timeout. The spec supports
+// idempotency and access-delegation headers on cancel; this low-level method
+// deliberately defers those until a cancel options type is added, and suppresses
+// the session-default access-delegation header (cancel vends no credentials). A
+// 404 (already-expired or unknown plan) is not special-cased: cancel is
+// best-effort, so the generic REST error is acceptable.
 func (r *Catalog) CancelPlanning(ctx context.Context, ident table.Identifier, planID string) error {
-	return fmt.Errorf("%w: cancel planning", iceberg.ErrNotImplemented)
+	if err := r.endpoints.check(endpointCancelPlanning); err != nil {
+		return err
+	}
+
+	path, err := r.scanPlanningPath(endpointCancelPlanning, ident, planID)
+	if err != nil {
+		return err
+	}
+
+	_, err = doDelete[struct{}](
+		ctx, r.baseURI, path, r.cl, nil,
+		withSuppressedHeaders(headerIcebergAccessDelegation))
+
+	return err
 }
 
 // FetchScanTasks fetches the scan tasks for a plan-task handle returned by a
-// completed plan.
+// completed plan. A 404 is split by the response error.type: an expired
+// plan-task handle (NoSuchPlanTaskException) is ErrNoSuchPlanTask, while a gone
+// table or namespace is catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace, so
+// a caller fanning out over handles can tell a handle expiry from the table
+// vanishing. A bare or unrecognized 404 stays an ambiguous ErrRESTError. An
+// empty 200 body is rejected (requireBody) so a truncated response is not read
+// as a successfully completed empty task set.
 func (r *Catalog) FetchScanTasks(ctx context.Context, ident table.Identifier, req FetchScanTasksRequest) (FetchScanTasksResponse, error) {
-	return FetchScanTasksResponse{}, fmt.Errorf("%w: fetch scan tasks", iceberg.ErrNotImplemented)
+	if err := r.endpoints.check(endpointFetchScanTasks); err != nil {
+		return FetchScanTasksResponse{}, err
+	}
+
+	path, err := r.scanPlanningPath(endpointFetchScanTasks, ident)
+	if err != nil {
+		return FetchScanTasksResponse{}, err
+	}
+
+	headers, err := scanPlanningHeaders(req.IdempotencyKey, nil, true)
+	if err != nil {
+		return FetchScanTasksResponse{}, err
+	}
+
+	return doPost[FetchScanTasksRequest, FetchScanTasksResponse](
+		ctx, r.baseURI, path, req, r.cl,
+		map[int]error{http.StatusNotFound: ErrRESTError},
+		withHeaders(headers), withSuppressedHeaders(headerIcebergAccessDelegation),
+		withErrorTypeOverride(fetchScanTasksErrorTypes), requireBody())
 }
 
 // WaitForPlan polls a submitted plan to completion using jittered backoff,
@@ -113,6 +333,101 @@ func (r *Catalog) WaitForPlan(ctx context.Context, ident table.Identifier, planI
 	return CompletedPlanningResult{}, fmt.Errorf("%w: wait for plan", iceberg.ErrNotImplemented)
 }
 
+func (r *Catalog) scanPlanningPath(ep endpoint, ident table.Identifier, extra ...string) ([]string, error) {
+	ns, tbl, err := r.splitIdentForPath(ident)
+	if err != nil {
+		return nil, err
+	}
+
+	// extra carries opaque, server-issued path segments (the plan-id). The spec
+	// puts no character restriction on them, and baseURI.JoinPath path.Cleans its
+	// arguments — so an unescaped id containing '/' would split into segments and
+	// a '..'/'.' segment would resolve to a different endpoint (e.g. ".." on the
+	// plan path lands on .../tasks). Escape each as a single literal path segment.
+	params := make([]string, 0, 2+len(extra))
+	params = append(params, ns, tbl)
+	for _, seg := range extra {
+		params = append(params, escapeOpaquePathSegment(seg))
+	}
+
+	return ep.reqPath(params...)
+}
+
+// escapeOpaquePathSegment percent-encodes an opaque string so it survives
+// url.URL.JoinPath as a single literal path segment. url.PathEscape handles '/',
+// '%', spaces, etc., but leaves a pure-dot segment ("." or "..") unescaped, which
+// JoinPath's path.Clean would then resolve as a dot-segment; encode those dots so
+// the segment is preserved verbatim.
+func escapeOpaquePathSegment(s string) string {
+	switch escaped := url.PathEscape(s); escaped {
+	case ".":
+		return "%2E"
+	case "..":
+		return "%2E%2E"
+	default:
+		return escaped
+	}
+}
+
+func scanPlanningHeaders(idempotencyKey, accessDelegation *string, includeIdempotency bool) (map[string]string, error) {
+	headers := make(map[string]string, 2)
+	if includeIdempotency {
+		key, err := idempotencyHeaderValue(idempotencyKey)
+		if err != nil {
+			return nil, err
+		}
+		headers[headerIdempotencyKey] = key
+	}
+	if accessDelegation != nil {
+		headers[headerIcebergAccessDelegation] = *accessDelegation
+	}
+	if len(headers) == 0 {
+		return nil, nil
+	}
+
+	return headers, nil
+}
+
+func idempotencyHeaderValue(idempotencyKey *string) (string, error) {
+	if idempotencyKey == nil {
+		// Plan and task POSTs always send an idempotency key. The spec pins it
+		// to a UUIDv7 string (RFC 9562) so a server can key its dedup window off
+		// the embedded timestamp, matching Java's UUIDUtil.generateUuidV7(). A
+		// v4 key would be treated as undefined by such servers. There is no
+		// transport retry here, so nil means a fresh key for this call.
+		key, err := uuid.NewV7()
+		if err != nil {
+			return "", fmt.Errorf("generating idempotency key: %w", err)
+		}
+
+		return key.String(), nil
+	}
+
+	parsed, err := uuid.Parse(*idempotencyKey)
+	if err != nil {
+		return "", fmt.Errorf("%w: invalid idempotency key %q", iceberg.ErrInvalidArgument, *idempotencyKey)
+	}
+	// uuid.Parse is lenient (its docs say it should not be used for validation):
+	// it accepts the URN, brace, and un-hyphenated 32-char forms. The spec's
+	// header schema pins this to the 36-char canonical hyphenated form, so reject
+	// anything whose canonical rendering differs (case-insensitively) from the
+	// input rather than forward a nonconforming encoding.
+	if !strings.EqualFold(parsed.String(), *idempotencyKey) {
+		return "", fmt.Errorf("%w: idempotency key %q must be a canonical hyphenated UUID",
+			iceberg.ErrInvalidArgument, *idempotencyKey)
+	}
+	// The spec pins the header to UUIDv7, so reject other versions rather than
+	// forward a key a timestamp-keyed server would treat as undefined. RFC 9562
+	// UUIDv7 also uses the RFC 4122 variant, so require that too: a canonical
+	// string can carry the version-7 nibble while setting non-RFC variant bits.
+	if parsed.Version() != 7 || parsed.Variant() != uuid.RFC4122 {
+		return "", fmt.Errorf("%w: idempotency key %q must be an RFC 4122 UUIDv7 (got v%d, variant %v)",
+			iceberg.ErrInvalidArgument, *idempotencyKey, int(parsed.Version()), parsed.Variant())
+	}
+
+	return *idempotencyKey, nil
+}
+
 // --- Wire types (sketch) ----------------------------------------------------
 //
 // Content-file, delete-file, and residual decoding lands with the scan-task
@@ -180,8 +495,10 @@ type CompletedPlanningResult struct {
 // wire type and the seam stay in agreement.
 type PlanTableScanRequest struct {
 	// IdempotencyKey is sent as the Idempotency-Key header, not in the JSON body.
-	// If set, it must be a UUID string; nil lets the implementation choose a
-	// safe retry key.
+	// If set, it must be a UUIDv7 string (RFC 9562). If nil, a fresh UUIDv7 is
+	// generated per call and not returned, so passing nil and retrying on a
+	// transient error sends a different key each attempt and defeats server-side
+	// dedup: pass an explicit key to get idempotency across retries.
 	IdempotencyKey *string `json:"-"`
 	// AccessDelegation is sent as the X-Iceberg-Access-Delegation header, not
 	// in the JSON body. Nil uses the catalog default.
@@ -249,11 +566,35 @@ type FetchPlanningResultResponse struct {
 	StorageCredentials []StorageCredential `json:"storage-credentials,omitempty"`
 }
 
+func (r *FetchPlanningResultResponse) UnmarshalJSON(data []byte) error {
+	type fetchPlanningResultResponse FetchPlanningResultResponse
+	var resp fetchPlanningResultResponse
+	if err := json.Unmarshal(data, &resp); err != nil {
+		return err
+	}
+
+	switch resp.Status {
+	case PlanStatusCompleted, PlanStatusSubmitted, PlanStatusCancelled:
+	case PlanStatusFailed:
+		if resp.Error == nil {
+			return fmt.Errorf("%w: fetchPlanningResult failed response missing error", ErrRESTError)
+		}
+	default:
+		return fmt.Errorf("%w: fetchPlanningResult response has unknown status %q", ErrRESTError, resp.Status)
+	}
+
+	*r = FetchPlanningResultResponse(resp)
+
+	return nil
+}
+
 // FetchScanTasksRequest is the POST .../tasks request body.
 type FetchScanTasksRequest struct {
 	// IdempotencyKey is sent as the Idempotency-Key header, not in the JSON body.
-	// If set, it must be a UUID string; nil lets the implementation choose a
-	// safe retry key.
+	// If set, it must be a UUIDv7 string (RFC 9562). If nil, a fresh UUIDv7 is
+	// generated per call and not returned, so passing nil and retrying on a
+	// transient error sends a different key each attempt and defeats server-side
+	// dedup: pass an explicit key to get idempotency across retries.
 	IdempotencyKey *string `json:"-"`
 
 	PlanTask string `json:"plan-task"`
diff --git a/catalog/rest/scan_planning_test.go b/catalog/rest/scan_planning_test.go
index 56c990c0..fbddd9ec 100644
--- a/catalog/rest/scan_planning_test.go
+++ b/catalog/rest/scan_planning_test.go
@@ -18,13 +18,142 @@
 package rest
 
 import (
+	"context"
 	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
 	"testing"
 
+	"github.com/apache/iceberg-go"
+	"github.com/apache/iceberg-go/catalog"
+	"github.com/apache/iceberg-go/table"
+	"github.com/google/uuid"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
+func TestScanPlanningEndpointConstantsRenderExpectedPaths(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name   string
+		ep     endpoint
+		params []string
+		want   []string
+	}{
+		{
+			name:   "plan table scan",
+			ep:     endpointPlanTableScan,
+			params: []string{"db", "tbl"},
+			want:   []string{"namespaces", "db", "tables", "tbl", "plan"},
+		},
+		{
+			name:   "fetch planning result",
+			ep:     endpointFetchPlanResult,
+			params: []string{"db", "tbl", "plan-123"},
+			want:   []string{"namespaces", "db", "tables", "tbl", "plan", "plan-123"},
+		},
+		{
+			name:   "cancel planning",
+			ep:     endpointCancelPlanning,
+			params: []string{"db", "tbl", "plan-123"},
+			want:   []string{"namespaces", "db", "tables", "tbl", "plan", "plan-123"},
+		},
+		{
+			name:   "fetch scan tasks",
+			ep:     endpointFetchScanTasks,
+			params: []string{"db", "tbl"},
+			want:   []string{"namespaces", "db", "tables", "tbl", "tasks"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := tc.ep.reqPath(tc.params...)
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+func TestScanPlanningEscapesOpaquePlanID(t *testing.T) {
+	t.Parallel()
+
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, nil)
+
+	// baseURI.JoinPath path.Cleans its segments, so scanPlanningPath must escape
+	// an opaque plan-id containing '/', a dot segment, or traversal into a single
+	// literal segment; otherwise "a/b" splits and ".." / "../tasks" resolve to a
+	// different endpoint. Each must survive JoinPath as the final .../plan/ segment
+	// and round-trip.
+	for _, planID := range []string{"a/b", "../tasks", "a b", "a%2Fb", ".", "..", "plan-123"} {
+		path, err := cat.scanPlanningPath(endpointFetchPlanResult, table.Identifier{"db", "tbl"}, planID)
+		require.NoErrorf(t, err, "plan-id %q", planID)
+
+		seg := path[len(path)-1]
+		assert.NotContainsf(t, seg, "/", "plan-id %q split into multiple segments: %q", planID, seg)
+
+		decoded, err := url.PathUnescape(seg)
+		require.NoErrorf(t, err, "plan-id %q", planID)
+		assert.Equalf(t, planID, decoded, "plan-id %q did not round-trip", planID)
+
+		// The escaped segment must survive JoinPath's path.Clean as the last
+		// .../plan/ segment (no split, no traversal to a different endpoint).
+		escaped := cat.baseURI.JoinPath(path...).EscapedPath()
+		assert.Truef(t, strings.HasSuffix(escaped, "/plan/"+seg),
+			"plan-id %q was mangled by JoinPath: %s", planID, escaped)
+	}
+}
+
+func TestScanPlanningCapabilities(t *testing.T) {
+	t.Parallel()
+
+	t.Run("plan only", func(t *testing.T) {
+		t.Parallel()
+
+		// A plan-only server can plan inline, but a `submitted` reply could not
+		// be polled, so it is not full-remote capable. SupportsRemoteScanPlanning
+		// is false here too (gated off while PlanFiles is a stub).
+		cat := &Catalog{endpoints: newEndpointSet([]endpoint{endpointPlanTableScan})}
+		assert.True(t, cat.SupportsPlanTableScan())
+		assert.False(t, cat.SupportsFullRemoteScanPlanning())
+		assert.False(t, cat.SupportsRemoteScanPlanning())
+	})
+
+	t.Run("full remote planning", func(t *testing.T) {
+		t.Parallel()
+
+		cat := &Catalog{endpoints: newEndpointSet([]endpoint{
+			endpointPlanTableScan,
+			endpointFetchPlanResult,
+			endpointCancelPlanning,
+			endpointFetchScanTasks,
+		})}
+		assert.True(t, cat.SupportsPlanTableScan())
+		assert.True(t, cat.SupportsFullRemoteScanPlanning())
+		// SupportsRemoteScanPlanning stays false while PlanFiles is a stub, even
+		// when all four endpoints are advertised, so auto mode falls back to
+		// local instead of routing into ErrNotImplemented. Flips on with the
+		// PlanFiles phase.
+		assert.False(t, cat.SupportsRemoteScanPlanning())
+	})
+
+	t.Run("default fallback does not advertise scan planning", func(t *testing.T) {
+		t.Parallel()
+
+		cat := &Catalog{endpoints: newEndpointSet(defaultEndpoints)}
+		assert.False(t, cat.SupportsPlanTableScan())
+		assert.False(t, cat.SupportsFullRemoteScanPlanning())
+		assert.False(t, cat.SupportsRemoteScanPlanning())
+	})
+}
+
 func TestPlanTableScanResponseRequiresPlanIDForTrackedStatuses(t *testing.T) {
 	t.Parallel()
 
@@ -94,3 +223,581 @@ func TestPlanTableScanResponseRejectsUnknownStatus(t *testing.T) {
 	err := json.Unmarshal([]byte(`{"status":"bogus"}`), &resp)
 	require.ErrorIs(t, err, ErrRESTError)
 }
+
+func TestFetchPlanningResultResponseRejectsMalformedResponses(t *testing.T) {
+	t.Parallel()
+
+	t.Run("failed without error", func(t *testing.T) {
+		t.Parallel()
+
+		var resp FetchPlanningResultResponse
+		err := json.Unmarshal([]byte(`{"status":"failed"}`), &resp)
+		require.ErrorIs(t, err, ErrRESTError)
+	})
+
+	t.Run("unknown status", func(t *testing.T) {
+		t.Parallel()
+
+		var resp FetchPlanningResultResponse
+		err := json.Unmarshal([]byte(`{"status":"bogus"}`), &resp)
+		require.ErrorIs(t, err, ErrRESTError)
+	})
+}
+
+func TestPlanTableScanGeneratesIdempotencyKeyAndUsesDefaultAccessDelegation(t *testing.T) {
+	t.Parallel()
+
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+			got := req.Header.Get(headerIdempotencyKey)
+			require.NotEmpty(t, got)
+			parsed, err := uuid.Parse(got)
+			require.NoError(t, err)
+			// The spec pins the generated key to UUIDv7.
+			assert.Equal(t, 7, int(parsed.Version()))
+			assert.Equal(t, []string{defaultAccessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+			_, err = w.Write([]byte(`{"status":"completed","plan-id":"plan-1"}`))
+			require.NoError(t, err)
+		})
+	})
+
+	_, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+	require.NoError(t, err)
+}
+
+func TestPlanTableScanRejectsInvalidIdempotencyKey(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name string
+		key  string
+	}{
+		{"not a uuid", "not-a-uuid"},
+		// Valid UUID, but v1 not v7 — the spec pins the header to UUIDv7.
+		{"valid uuid wrong version", "11111111-1111-1111-1111-111111111111"},
+		// uuid.Parse accepts these non-canonical encodings of a valid v7 UUID,
+		// but the spec's header schema requires the 36-char hyphenated form.
+		{"unhyphenated v7", "0190b6c51c3d70008000000000000001"},
+		{"urn v7", "urn:uuid:0190b6c5-1c3d-7000-8000-000000000001"},
+		{"braced v7", "{0190b6c5-1c3d-7000-8000-000000000001}"},
+		// Canonical with the version-7 nibble but a non-RFC-4122 variant (the
+		// 4th group's leading nibble is 0 -> reserved/NCS, not 8-b).
+		{"v7 non-rfc variant", "0190b6c5-1c3d-7000-0000-000000000001"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			key := tc.key
+			cat := &Catalog{endpoints: newEndpointSet([]endpoint{endpointPlanTableScan})}
+
+			_, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+				IdempotencyKey: &key,
+			})
+			require.ErrorIs(t, err, iceberg.ErrInvalidArgument)
+		})
+	}
+}
+
+func TestPlanTableScanAcceptsUppercaseCanonicalIdempotencyKey(t *testing.T) {
+	t.Parallel()
+
+	// Canonical hyphenated form is required case-insensitively; an uppercase v7
+	// key is accepted and forwarded verbatim.
+	key := "0190B6C5-1C3D-7000-8000-000000000001"
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+			assert.Equal(t, key, req.Header.Get(headerIdempotencyKey))
+			_, err := w.Write([]byte(`{"status":"completed","plan-id":"plan-1"}`))
+			require.NoError(t, err)
+		})
+	})
+
+	_, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+		IdempotencyKey: &key,
+	})
+	require.NoError(t, err)
+}
+
+func TestPlanTableScanRequest(t *testing.T) {
+	t.Parallel()
+
+	cases := []struct {
+		name       string
+		response   string
+		wantStatus PlanStatus
+		wantPlanID *string
+		wantError  string
+	}{
+		{
+			name:       "completed",
+			response:   `{"status":"completed","plan-id":"plan-1","plan-tasks":["task-1"]}`,
+			wantStatus: PlanStatusCompleted,
+			wantPlanID: stringPtr("plan-1"),
+		},
+		{
+			name:       "submitted",
+			response:   `{"status":"submitted","plan-id":"plan-2"}`,
+			wantStatus: PlanStatusSubmitted,
+			wantPlanID: stringPtr("plan-2"),
+		},
+		{
+			name:       "failed",
+			response:   `{"status":"failed","error":{"message":"boom","type":"ServerError","code":500}}`,
+			wantStatus: PlanStatusFailed,
+			wantError:  "boom",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000001"
+			accessDelegation := "remote-signing"
+			snapshotID := int64(22)
+			cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+				mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+					require.Equal(t, http.MethodPost, req.Method)
+					assert.Equal(t, idempotencyKey, req.Header.Get(headerIdempotencyKey))
+					assert.Equal(t, []string{accessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+					body, err := io.ReadAll(req.Body)
+					require.NoError(t, err)
+					assert.JSONEq(t, `{
+						"snapshot-id": 22,
+						"select": ["id", "data"],
+						"filter": {"type": "always-true"}
+					}`, string(body))
+
+					_, err = w.Write([]byte(tc.response))
+					require.NoError(t, err)
+				})
+			})
+
+			resp, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+				IdempotencyKey:   &idempotencyKey,
+				AccessDelegation: &accessDelegation,
+				SnapshotID:       &snapshotID,
+				Select:           []string{"id", "data"},
+				Filter:           json.RawMessage(`{"type":"always-true"}`),
+			})
+			if tc.wantError != "" {
+				// A failed plan returns a *PlanFailedError and a zero resp; the
+				// detail rides on the error.
+				require.ErrorIs(t, err, ErrPlanFailed)
+				var pfe *PlanFailedError
+				require.ErrorAs(t, err, &pfe)
+				require.NotNil(t, pfe.Detail)
+				assert.Equal(t, tc.wantError, pfe.Detail.Message)
+				assert.Equal(t, PlanTableScanResponse{}, resp)
+
+				return
+			}
+
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantStatus, resp.Status)
+			if tc.wantPlanID != nil {
+				require.NotNil(t, resp.PlanID)
+				assert.Equal(t, *tc.wantPlanID, *resp.PlanID)
+			}
+		})
+	}
+}
+
+func TestPlanTableScanRejectsEmptyBody(t *testing.T) {
+	t.Parallel()
+
+	// A 200 with an empty body skips JSON decoding (doPost short-circuits on
+	// Content-Length 0), bypassing the response UnmarshalJSON validation. Without
+	// a status guard this would return a zero response with a nil PlanID as
+	// success; assert it is rejected instead.
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodPost, req.Method)
+			w.Header().Set("Content-Length", "0")
+			w.WriteHeader(http.StatusOK)
+		})
+	})
+
+	resp, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+	require.ErrorIs(t, err, ErrRESTError)
+	assert.Equal(t, PlanTableScanResponse{}, resp)
+}
+
+func TestFetchScanTasksRejectsEmptyBody(t *testing.T) {
+	t.Parallel()
+
+	// FetchScanTasks has no status discriminator, so an empty 200 (doPost
+	// short-circuits on Content-Length 0) would otherwise decode to a zero,
+	// task-less response and read as a successfully completed empty scan,
+	// silently dropping work. requireBody rejects it.
+	key := "0190b6c5-1c3d-7000-8000-000000000004"
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodPost, req.Method)
+			w.Header().Set("Content-Length", "0")
+			w.WriteHeader(http.StatusOK)
+		})
+	})
+
+	resp, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+		IdempotencyKey: &key,
+		PlanTask:       "task-1",
+	})
+	require.ErrorIs(t, err, ErrRESTError)
+	assert.Equal(t, FetchScanTasksResponse{}, resp)
+}
+
+func TestFetchPlanningResultRequest(t *testing.T) {
+	t.Parallel()
+
+	accessDelegation := "remote-signing"
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodGet, req.Method)
+			assert.Equal(t, []string{accessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+			_, err := w.Write([]byte(`{"status":"completed","plan-tasks":["task-1"]}`))
+			require.NoError(t, err)
+		})
+	})
+
+	resp, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{
+		AccessDelegation: &accessDelegation,
+	})
+	require.NoError(t, err)
+	assert.Equal(t, PlanStatusCompleted, resp.Status)
+	assert.Equal(t, []string{"task-1"}, resp.PlanTasks)
+}
+
+func TestFetchPlanningResultUsesDefaultAccessDelegation(t *testing.T) {
+	t.Parallel()
+
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodGet, req.Method)
+			assert.Equal(t, []string{defaultAccessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+			_, err := w.Write([]byte(`{"status":"submitted"}`))
+			require.NoError(t, err)
+		})
+	})
+
+	resp, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+	require.NoError(t, err)
+	assert.Equal(t, PlanStatusSubmitted, resp.Status)
+}
+
+func TestFetchPlanningResultMapsNotFound(t *testing.T) {
+	t.Parallel()
+
+	// The GET .../plan/{plan-id} 404 splits on error.type so the poller can tell
+	// retry-with-a-new-plan (expired plan-id) from abort (table/namespace gone).
+	// A bare or unrecognized 404 is ambiguous and stays ErrRESTError rather than
+	// being guessed as an expiry (which would make a poller retry a gone table).
+	cases := []struct {
+		name    string
+		errType string // empty => bare 404 with no body
+		wantErr error
+		notErr  error
+	}{
+		{"bare 404", "", ErrRESTError, ErrPlanExpired},
+		{"unrecognized type", "SomeFutureException", ErrRESTError, ErrPlanExpired},
+		{"no such plan-id", errTypeNoSuchPlanID, ErrPlanExpired, catalog.ErrNoSuchTable},
+		{"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, ErrPlanExpired},
+		{"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, ErrPlanExpired},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+				mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+					require.Equal(t, http.MethodGet, req.Method)
+					writeRESTNotFound(t, w, tc.errType)
+				})
+			})
+
+			_, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+			require.ErrorIs(t, err, tc.wantErr)
+			if tc.notErr != nil {
+				assert.NotErrorIs(t, err, tc.notErr)
+			}
+		})
+	}
+}
+
+func TestFetchScanTasksMapsNotFound(t *testing.T) {
+	t.Parallel()
+
+	// The POST .../tasks 404 splits on error.type so a fanout caller can tell an
+	// expired plan-task handle from the table/namespace having vanished. A bare
+	// or unrecognized 404 stays an ambiguous ErrRESTError.
+	cases := []struct {
+		name    string
+		errType string // empty => bare 404 with no body
+		wantErr error
+		notErr  error
+	}{
+		{"bare 404", "", ErrRESTError, ErrNoSuchPlanTask},
+		{"unrecognized type", "SomeFutureException", ErrRESTError, ErrNoSuchPlanTask},
+		{"no such plan-task", errTypeNoSuchPlanTask, ErrNoSuchPlanTask, catalog.ErrNoSuchTable},
+		{"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, ErrNoSuchPlanTask},
+		{"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, ErrNoSuchPlanTask},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000003"
+			cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+				mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+					require.Equal(t, http.MethodPost, req.Method)
+					writeRESTNotFound(t, w, tc.errType)
+				})
+			})
+
+			_, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+				IdempotencyKey: &idempotencyKey,
+				PlanTask:       "task-1",
+			})
+			require.ErrorIs(t, err, tc.wantErr)
+			if tc.notErr != nil {
+				assert.NotErrorIs(t, err, tc.notErr)
+			}
+		})
+	}
+}
+
+func TestPlanTableScanMapsNotFound(t *testing.T) {
+	t.Parallel()
+
+	// The POST .../plan 404 carries no plan-id, so a recognized 404 splits only
+	// into a gone table vs namespace; a bare or unrecognized 404 stays an
+	// ambiguous ErrRESTError rather than being guessed as a missing table.
+	cases := []struct {
+		name    string
+		errType string // empty => bare 404 with no body
+		wantErr error
+		notErr  error
+	}{
+		{"bare 404", "", ErrRESTError, catalog.ErrNoSuchTable},
+		{"unrecognized type", "SomeFutureException", ErrRESTError, catalog.ErrNoSuchTable},
+		{"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, catalog.ErrNoSuchNamespace},
+		{"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, catalog.ErrNoSuchTable},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+				mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+					require.Equal(t, http.MethodPost, req.Method)
+					writeRESTNotFound(t, w, tc.errType)
+				})
+			})
+
+			_, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+			require.ErrorIs(t, err, tc.wantErr)
+			if tc.notErr != nil {
+				assert.NotErrorIs(t, err, tc.notErr)
+			}
+		})
+	}
+}
+
+func TestFetchPlanningResultResponseAcceptsCancelled(t *testing.T) {
+	t.Parallel()
+
+	// cancelled is a valid poll result (unlike PlanTableScanResponse, which
+	// rejects it). Pin it so a refactor routing it into the default error case
+	// is caught.
+	var resp FetchPlanningResultResponse
+	require.NoError(t, json.Unmarshal([]byte(`{"status":"cancelled"}`), &resp))
+	assert.Equal(t, PlanStatusCancelled, resp.Status)
+}
+
+func TestFetchPlanningResultStatusArms(t *testing.T) {
+	t.Parallel()
+
+	t.Run("cancelled returns ErrPlanCancelled", func(t *testing.T) {
+		t.Parallel()
+
+		cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+			mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+				_, err := w.Write([]byte(`{"status":"cancelled"}`))
+				require.NoError(t, err)
+			})
+		})
+
+		_, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+		require.ErrorIs(t, err, ErrPlanCancelled)
+	})
+
+	t.Run("failed returns PlanFailedError", func(t *testing.T) {
+		t.Parallel()
+
+		cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+			mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+				_, err := w.Write([]byte(`{"status":"failed","error":{"message":"boom","type":"ServerError","code":500}}`))
+				require.NoError(t, err)
+			})
+		})
+
+		_, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+		require.ErrorIs(t, err, ErrPlanFailed)
+		var pfe *PlanFailedError
+		require.ErrorAs(t, err, &pfe)
+		require.NotNil(t, pfe.Detail)
+		assert.Equal(t, "boom", pfe.Detail.Message)
+	})
+}
+
+func TestCancelPlanningRequest(t *testing.T) {
+	t.Parallel()
+
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointCancelPlanning}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodDelete, req.Method)
+			assert.Empty(t, req.Header.Values(headerIdempotencyKey))
+			assert.Empty(t, req.Header.Values(headerIcebergAccessDelegation))
+			w.WriteHeader(http.StatusNoContent)
+		})
+	})
+
+	require.NoError(t, cat.CancelPlanning(context.Background(), table.Identifier{"db", "tbl"}, "plan-123"))
+}
+
+func TestFetchScanTasksRequest(t *testing.T) {
+	t.Parallel()
+
+	idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000002"
+	cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+		mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+			require.Equal(t, http.MethodPost, req.Method)
+			assert.Equal(t, idempotencyKey, req.Header.Get(headerIdempotencyKey))
+			assert.Empty(t, req.Header.Values(headerIcebergAccessDelegation))
+
+			body, err := io.ReadAll(req.Body)
+			require.NoError(t, err)
+			assert.JSONEq(t, `{"plan-task":"task-1"}`, string(body))
+
+			_, err = w.Write([]byte(`{
+				"plan-tasks": ["child-task"],
+				"file-scan-tasks": [{}],
+				"delete-files": [{}]
+			}`))
+			require.NoError(t, err)
+		})
+	})
+
+	resp, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+		IdempotencyKey: &idempotencyKey,
+		PlanTask:       "task-1",
+	})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"child-task"}, resp.PlanTasks)
+	assert.Len(t, resp.FileScanTasks, 1)
+	assert.Len(t, resp.DeleteFiles, 1)
+}
+
+func TestScanPlanningEndpointGating(t *testing.T) {
+	t.Parallel()
+
+	ident := table.Identifier{"db", "tbl"}
+	cases := []struct {
+		name string
+		call func(*Catalog) error
+	}{
+		{"plan", func(c *Catalog) error {
+			_, err := c.PlanTableScan(context.Background(), ident, PlanTableScanRequest{})
+
+			return err
+		}},
+		{"fetch-result", func(c *Catalog) error {
+			_, err := c.FetchPlanningResult(context.Background(), ident, "plan-123", FetchPlanningResultOptions{})
+
+			return err
+		}},
+		{"cancel", func(c *Catalog) error {
+			return c.CancelPlanning(context.Background(), ident, "plan-123")
+		}},
+		{"fetch-tasks", func(c *Catalog) error {
+			_, err := c.FetchScanTasks(context.Background(), ident, FetchScanTasksRequest{PlanTask: "task-1"})
+
+			return err
+		}},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			cat := &Catalog{endpoints: newEndpointSet(defaultEndpoints)}
+			err := tc.call(cat)
+			require.ErrorIs(t, err, ErrEndpointNotSupported)
+			assert.NotErrorIs(t, err, ErrRESTError)
+		})
+	}
+}
+
+func newScanPlanningTestCatalog(t *testing.T, endpoints []endpoint, register func(*http.ServeMux)) *Catalog {
+	t.Helper()
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/config", func(w http.ResponseWriter, req *http.Request) {
+		require.Equal(t, http.MethodGet, req.Method)
+		err := json.NewEncoder(w).Encode(map[string]any{
+			"defaults":  map[string]any{},
+			"overrides": map[string]any{},
+			"endpoints": endpointStrings(endpoints),
+		})
+		require.NoError(t, err)
+	})
+	if register != nil {
+		register(mux)
+	}
+
+	srv := httptest.NewServer(mux)
+	t.Cleanup(srv.Close)
+
+	cat, err := NewCatalog(context.Background(), "rest", srv.URL)
+	require.NoError(t, err)
+
+	return cat
+}
+
+func endpointStrings(endpoints []endpoint) []string {
+	if endpoints == nil {
+		return nil
+	}
+
+	out := make([]string, len(endpoints))
+	for i, e := range endpoints {
+		out[i] = e.String()
+	}
+
+	return out
+}
+
+// writeRESTNotFound writes a 404 response. A non-empty errType emits a REST
+// ErrorModel body ({"error":{...,"type":errType}}) so the client can split the
+// 404 on error.type; an empty errType writes a bare 404 with no body (the
+// fallback path).
+func writeRESTNotFound(t *testing.T, w http.ResponseWriter, errType string) {
+	t.Helper()
+
+	w.WriteHeader(http.StatusNotFound)
+	if errType == "" {
+		return
+	}
+
+	_, err := fmt.Fprintf(w, `{"error":{"message":%q,"type":%q,"code":404}}`, errType, errType)
+	require.NoError(t, err)
+}
+
+func stringPtr(s string) *string { return &s }