feat(client): resume native watches from a consumed checkpoint

CONTRIBUTING.md

@@ -18,8 +18,9 @@ Run `task fixtures-check`, `task test`, and `task lint` before opening a pull re
 Start with watch streams and authoritative resource views; add editing as an optional layer.
 The [README](README.md) explains current capabilities and how to choose a native or gateway source.
 Current API examples must match this branch. Native viewing is LIST/WATCH on the shared
-connection lifecycle, and native editing writes conditional merge patches back through the same
-proxy; native resume, editor cleanup and larger comparisons are separate. Save-progress evaluation remains a proposal until implemented.
+connection lifecycle and resumes ordinary reconnects from a per-handle checkpoint, and native editing
+writes conditional merge patches back through the same proxy; streaming lists, pagination, editor
+cleanup and larger comparisons are separate. Save-progress evaluation remains a proposal until implemented.
 
 - Keep the core gateway free of `client-go`; Kubernetes integration belongs in `gateway/kube`.
 - Keep the browser client framework-free and free of runtime dependencies.

README.md

@@ -55,7 +55,7 @@ Start with the resource state and guarantees the page needs; framing is an imple
 
 | Source | What the page receives | Connector |
 |---|---|---|
-| Native through a host proxy | Original authorized resources, with the shared client lifecycle and store | `connectNativeWatch`: LIST, then WATCH, and a fresh LIST on every reconnect; edits are written back through the same proxy |
+| Native through a host proxy | Original authorized resources, with the shared client lifecycle and store | `connectNativeWatch`: LIST, then WATCH; a reconnect resumes the WATCH, and only an expired history lists again; edits are written back through the same proxy |
 | Gateway | Projected, redacted or suppressed views and optional upstream watch sharing | `connectResourceStream`, delivered over SSE |
 
 Native is the straightforward starting point for hosts that already proxy Kubernetes. It delivers
@@ -92,10 +92,11 @@ connection.close();
 
 The host mounts the API server's paths under a base such as `/k8s` and owns credentials, routing and
 which collections a user may read. The connector lists the complete collection, delivers it as a
-snapshot and becomes `live` once the WATCH from the collection's resourceVersion is accepted. Every
-reconnect lists again, and the store prunes only when that snapshot completes. HTTP or in-stream 410
-recovers within the bounded retry budget; 401, 403 and other 4xx are terminal. The connector does not
-paginate: a LIST that returns a continuation token is refused. The
+snapshot and becomes `live` once the WATCH from the collection's resourceVersion is accepted. A
+dropped or ended watch resumes from the last event applied, without a new snapshot, so drafts stay
+and missed changes arrive as events. HTTP or in-stream 410 (expired history) lists again within the
+bounded retry budget, and the store prunes only when that snapshot completes; 401, 403 and other 4xx
+are terminal. The connector does not paginate: a LIST that returns a continuation token is refused. The
 [native viewer example](examples/native-viewer/README.md) runs this against `kubectl proxy`.
 
 ## Watch a gateway view

docs/adopting.md

@@ -11,8 +11,8 @@ delivered over SSE. Both connectors share one fetch-based frontend lifecycle.
 
 For native access, a host that already proxies Kubernetes needs no gateway: point
 `connectNativeWatch` at a collection behind that proxy, as in the [README](../README.md#watch-native-resources-through-a-host-proxy)
-and the [native viewer example](../examples/native-viewer/README.md). It re-lists on every
-reconnect; to edit through the same proxy, see [native editing](saving.md#native-editing-through-a-host-proxy).
+and the [native viewer example](../examples/native-viewer/README.md). A reconnect resumes the watch,
+and only an expired history lists again; to edit through the same proxy, see [native editing](saving.md#native-editing-through-a-host-proxy).
 The steps below wire the gateway source.
 
 ## 1. Mount the stream endpoint

docs/field-reports/third-our-identity.md

@@ -1,7 +1,7 @@
 # Watch streams, optional editing and native access
 
-**Request of 2026-10-05. Slice 1, the native viewer, and slice 2, native editing, are implemented;
-the other follow-ups below remain open.** It builds on the connector separation, Go API cleanup and real-API save tests. Use
+**Request of 2026-10-05. Slice 1, the native viewer, slice 2, native editing, and native watch
+resumption are implemented; the other follow-ups below remain open.** It builds on the connector separation, Go API cleanup and real-API save tests. Use
 [proposal 0006](../proposals/0006-stream-and-save-implementation-plan.md#open-work-and-delivery-order)
 for completed work, delivery order and independent tracks.
 
@@ -154,16 +154,56 @@ saved and echoed on both entry points and rendered a real 422. The comparative f
 
 Each is separate from the slices above and from the others:
 
-- Native resume, streaming lists and pagination.
+- Native resume — **implemented**, see [below](#native-watch-resumption); streaming lists and
+  pagination remain open.
 - Comparative view and sharing measurements.
 - Independent gateway continuation and save-progress evaluation.
 - The independently proposed editor API cleanup in proposal 0009.
 
-Resumable native watches, streaming-list initialization and pagination are later improvements with
-their own recovery tests. Slice 1 improves adoption and lifecycle reuse; re-listing on every reconnect
-does not claim resume efficiency. Gateway upstream continuation has a different checkpoint owner and
+Slice 1 re-listed on every reconnect and claimed no resume efficiency; the requirements above are
+the contract it was built against. Gateway upstream continuation has a different checkpoint owner and
 can proceed independently. Neither implies browser replay for gateway SSE v1.
 
+### Native watch resumption
+
+**Implemented** in `connectNativeWatch`; the contract is in the
+[client reference](../../packages/krm-stream/README.md#native-connections).
+
+- Each handle keeps a private checkpoint, armed only once a complete snapshot was applied and its
+  WATCH accepted, and advanced only after the consumer applied an event or the stream passed a
+  bookmark. It is never exposed, accepted or shared, so it stays bound to the handle's proxy, scope,
+  selectors and credentials. Resource versions are opaque and replaced in stream order. Bookmarks
+  (`allowWatchBookmarks=true`) move only the checkpoint, never an object's write version.
+- EOF, network failures, a truncated final frame and retryable refusals (408, 429, 5xx, HTTP or in
+  the stream) resume the WATCH from the checkpoint: no LIST, `reset` or `synced`, so membership,
+  drafts and conflicts survive and missed updates, deletes, selector exits and same-name UID
+  replacements arrive as watch events. The state goes `connecting` → `live` once the resumed watch is
+  accepted.
+- HTTP or in-stream 410, malformed frames, an error without a code and an event without a
+  resourceVersion discard the checkpoint; the next connection is a fresh, complete LIST/WATCH
+  snapshot, during which the state is not live and editors refuse to save. Terminal refusals, the
+  bounded retry budget, cancellation and callback-error cleanup are unchanged; every reconnect still
+  consumes the budget.
+
+**Acceptance.** `packages/krm-stream/test/native.test.ts` covers missed updates, deletes, selector
+exits and UID replacement replayed on resume, bookmarks, opaque versions, split and truncated frames,
+malformed input, interrupted initialization, HTTP and in-stream expiry, repeated expiry to
+exhaustion, terminal and transient refusals on a resumed watch, cancellation, per-handle checkpoints
+and drafts/conflicts across a resume and a re-list; `native-editing.test.ts` covers a save refused
+during expiry recovery. `task e2e-browser` runs the viewer and editor pages through resume and an
+in-stream 410 on both entry points. `TestRealAPINativeResumeThroughHostProxy` (`task test-real-api`,
+v1.36.4+k3s1) drops the watch at a host proxy, mutates the cluster while the next WATCH is held and
+converges with no second LIST; it then rewrites a WATCH's resourceVersion to `1` so the real API server
+answers with its own in-stream 410, and recovers through a fresh snapshot, twice in a row. The expiry
+is induced by the proxy; the 410 is the server's.
+
+**Limits.** A resumed watch is live on acceptance, so an expired one is briefly live until its
+in-stream 410 arrives; a resume does not invalidate a guarded read as a snapshot does (an event for
+the object does), as on any live watch; the checkpoint is in memory and a page reload lists again.
+Streaming-list initialization and pagination are evaluated in
+[proposal 0006](../proposals/0006-stream-and-save-implementation-plan.md#3-native-streaming-lists-and-pagination)
+and not implemented.
+
 ## Show the value of each path
 
 After the viewer works, compare native/full/spec and shared/unshared gateway runs using the same

docs/glossary.md

@@ -34,6 +34,15 @@ See [quiet streams and saving](saving.md#why-a-quiet-stream-can-still-reject-a-s
 as bookmarks and errors. History can expire and initialization/recovery must establish a complete
 collection boundary. The current gateway handles these mechanics for its browser clients.
 
+**Bookmark** is a watch event that carries only a collection resource version: "the stream has
+reached here". It changes no object and is not an object's write version.
+
+**Checkpoint** is the collection resource version a watch can resume from: the last event the client
+applied, or the last bookmark. `connectNativeWatch` keeps one per connection handle, privately, and
+**resumes** a dropped WATCH from it instead of listing again; the server replays what followed. When
+the server reports the history expired (410), the checkpoint is discarded and a fresh snapshot
+recovers. Gateway browser connections do not resume: each starts a snapshot.
+
 **Scope** selects a target, resource kind, namespace, optional name and allowed labels. The host
 still authorizes the request; a selector does not grant permission.
 

docs/proposals/0006-stream-and-save-implementation-plan.md

@@ -2,7 +2,8 @@
 
 **Status: active delivery plan, updated 2026-10-05.** This is the single inventory of completed work,
 open work and ordering. The implementation includes connector separation, Go API cleanup,
-real-API save-composition tests, the native viewer and native editing with a browser page. Detailed
+real-API save-composition tests, the native viewer, native editing with a browser page and native
+watch resumption. Detailed
 contracts stay in the linked proposals and guides rather than becoming another roadmap.
 
 Start with [watching resources](../why-a-gateway.md); add the [editor](../client-state-model.md) only
@@ -29,8 +30,9 @@ remain separate delivery steps.
 | Optional editor and safe-save baseline | Draft reconciliation, explicit conflicts, atomic intent capture and guarded projected reads; recovery remains review plus another deliberate Save | [Editor model](../client-state-model.md), [saving](../saving.md) |
 | Editor integration and recovery recipes | Tested deletion recovery, keep-local resolution and Vue subscription ownership | [Recipes](../../examples/editor-recipes/README.md), [Vue](../../examples/vue/README.md) |
 | Real-API save composition | Cases for suppressed churn, guarded-read overlap, structured errors and same-name UID replacement | [Completed baseline](#completed-baseline) |
-| Native viewer (slice 1) | `connectNativeWatch` and `nativeCollectionURL`: unpaginated LIST, WATCH from the collection RV, fresh LIST on reconnect, native 410 recovery and terminal refusals on a lifecycle shared with the gateway connector; fake-fetch, Chromium and real-API tests; minimal example | [Request](../field-reports/third-our-identity.md#slice-1-a-native-viewer), [example](../../examples/native-viewer/README.md), [client](../../packages/krm-stream/README.md#native-connections) |
+| Native viewer (slice 1) | `connectNativeWatch` and `nativeCollectionURL`: unpaginated LIST, WATCH from the collection RV, fresh LIST on reconnect (superseded by resumption below), native 410 recovery and terminal refusals on a lifecycle shared with the gateway connector; fake-fetch, Chromium and real-API tests; minimal example | [Request](../field-reports/third-our-identity.md#slice-1-a-native-viewer), [example](../../examples/native-viewer/README.md), [client](../../packages/krm-stream/README.md#native-connections) |
 | Native editing (slice 2) | Machinery (`managedFields`, last-applied annotation) read-only in the store under every policy; maps holding a protected path merged key by key; `nativeObjectURL`; `gateway.ValidateNativeMergePatch` for host proxies; a native conditional editor with guarded native recovery reads; fake-fetch and real-API tests; a minimal one-ConfigMap page accepted in Chromium on both entry points | [Request](../field-reports/third-our-identity.md#slice-2-native-editing), [example](../../examples/native-editor/README.md), [saving](../saving.md#native-editing-through-a-host-proxy) |
+| Native watch resumption | A per-handle checkpoint advanced only after a consumed event or bookmark; ordinary reconnects resume the WATCH without LIST, reset or synced; 410, malformed input and unclassifiable errors discard it for a fresh snapshot; fake-fetch, Chromium (both entry points) and real-API resume/expiry tests | [Request](../field-reports/third-our-identity.md#native-watch-resumption), [client](../../packages/krm-stream/README.md#native-connections) |
 | Watch-first documentation | README, watch/edit/save guides, native-fetch request and compact decision records; duplicate/superseded guides removed | [README](../../README.md), [current request](../field-reports/third-our-identity.md) |
 
 ## Open work and delivery order
@@ -42,7 +44,7 @@ before starting a later one. Deliver separately reviewable changes and use the p
 |---|---|---|
 | 1 | Native viewer — **completed** | See [completed work](#completed-work); acceptance evidence is recorded in the [request](../field-reports/third-our-identity.md#acceptance-for-slice-1). |
 | 2 | Native editing — **completed** | See [completed work](#completed-work); acceptance evidence, browser acceptance included, is recorded in the [request](../field-reports/third-our-identity.md#acceptance-for-slice-2). No editor method changed, so proposal 0009's cleanup is unaffected. |
-| 3 | Native reconnect efficiency | After the viewer; evaluate resumable watches, streaming-list initialization and pagination with explicit membership/checkpoint tests. Do not claim these efficiencies for slice 1. |
+| 3 | Native reconnect efficiency — **resumption completed** | See [completed work](#completed-work). Streaming-list initialization and pagination are evaluated [below](#3-native-streaming-lists-and-pagination) and remain open; implement them only with their own membership, checkpoint and recovery tests. |
 | 4 | Gateway upstream continuation | Independent track with a design below; review reopen/credential bounds, record a baseline, implement and measure. No dependency on native transport. |
 | 5 | Save progress during suppressed churn | Independent evaluation using existing real-API fixtures; bounded submitted-intent recovery first, optional version delivery second. Implementation depends on measured benefit and reviewed scope. |
 | 6 | Comparative frontend and measurements | Follow working native viewing and editing. Compare native/full/spec and shared/unshared workloads; the larger project is outside slice 1. |
@@ -53,11 +55,11 @@ before starting a later one. Deliver separately reviewable changes and use the p
 
 The native viewer and native editing are in place: native frame parsing stays separate from SSE,
 both connectors share the lifecycle and HTTP helpers, and native writes go back through the host
-proxy as conditional merge patches. The connector re-lists on every reconnect and refuses paginated
-responses; it claims no resume efficiency. Choose the next change from order 3 or from the
-independent tracks; none of them waits for another.
+proxy as conditional merge patches. Ordinary reconnects resume the WATCH from a per-handle
+checkpoint; expiry and malformed input fall back to a fresh snapshot. The connector still requires an
+unpaginated LIST. Choose the next change from the independent tracks; none of them waits for another.
 
-Native reconnect efficiency (order 3) needs its own membership and checkpoint tests. Keep the current
+Streaming lists and pagination (order 3) need their own membership and checkpoint tests. Keep the current
 standalone state-input helper; proposed editor removals remain in
 [proposal 0009](0009-stream-and-editor-separation.md#proposed-editor-cleanup), with brief API change notes
 when implemented. Gateway continuation and save measurements proceed independently. Retain the existing
@@ -87,6 +89,30 @@ fresh deliberate save after churn stops; they do not establish usable save progr
 churn. `task test-real-api` runs these cases. Record actual runs, server versions, skips and final
 commit separately from fake-client and general CI results.
 
+## 3. Native streaming lists and pagination
+
+**Status: evaluated, not implemented.** Resumption removes the LIST from ordinary reconnects; these
+two would reduce the cost of the snapshots that remain (first connection, expiry, malformed input).
+
+**Streaming-list initialization** (`sendInitialEvents=true`, `resourceVersionMatch=NotOlderThan`)
+replaces LIST + WATCH with one request and avoids buffering the collection into one JSON body, which
+helps memory and time-to-first-row for large collections. `reset` precedes the first synthetic ADDED;
+the only boundary is the BOOKMARK annotated `k8s.io/initial-events-end: "true"` (F1), and `synced`,
+pruning and arming the checkpoint (to that bookmark's resourceVersion) happen there and nowhere else.
+Anything before it, a 410 included, leaves no checkpoint and prunes nothing, and synthetic ADDEDs must
+not advance a resumable checkpoint. Aggregated APIs refuse the request (F6), so a handle needs a
+classified, non-terminal fallback to LIST-then-WATCH. Tests: boundary gating, a partial initial
+stream, a missing end bookmark, fallback classification, and the real API on both kube-apiserver and
+the aggregated API.
+
+**Pagination** (`limit`/`continue`) bounds each response for very large collections. `reset` precedes
+the first page, every page's items count as membership, nothing is pruned before the last page, and
+`synced` and the checkpoint arm only after the final page and an accepted WATCH from the first page's
+resourceVersion. An expired continue token (410 mid-list) abandons the whole cycle without pruning
+and restarts from page one; duplicate UIDs across pages are malformed; no WATCH opens before the last
+page. Tests: abort between pages, 410 on page N, a terminal error on a later page, and the store
+keeping its previous membership throughout.
+
 ## 4. Measured upstream continuation
 
 Implement behind [the Kubernetes backend](../../gateway/kube/backend.go) and its existing `Watcher`