fix: define content and redaction convergence while suppressed writes retain older RVs

README.md

@@ -67,34 +67,37 @@ server.
 
 ```mermaid
 flowchart LR
-  person["Person\nediting a form"]
-  browser["Your browser app\n@configbutler/krm-stream"]
-  store["LiveResourceStore\nbase + local draft + live update\nthree-way merge"]
-  host["Your Go application\nidentity, authorization, scope\nprojection and redaction"]
-  api["Kubernetes API\nand resource watch"]
-  resources["KRM resources\napps, policies, databases,\nplatform and business objects"]
-  save["Your save endpoint\nvalidates and applies a patch"]
-
-  person --> browser --> store
-  store <-->|"snapshots and live deltas (SSE)"| host
-  host <-->|"read and watch"| api --> resources
-  store -->|"draft, conflicts, merge patch"| browser
-  browser -->|"explicit save"| save --> api
-
-  classDef person fill:#fff3cd,stroke:#d39e00,color:#3f3000;
-  classDef browser fill:#dff3ff,stroke:#1677a4,color:#062f45;
-  classDef host fill:#e4f7e8,stroke:#27834c,color:#113d23;
-  classDef api fill:#f8e0ef,stroke:#a83970,color:#4b1230;
-  classDef store fill:#ede7ff,stroke:#6750a4,color:#2d1e5c;
-  class person person;
-  class browser,store browser;
-  class host,save host;
-  class api,resources api;
+  api["Kubernetes API"]
+  gateway["Embedded Go gateway<br/>Enforces host authorization<br/>Projection and redaction"]
+  store["Browser store<br/>Delivered state, local draft and conflicts"]
+  ui["Your form or live view"]
+  save["Your Go save handler<br/>Write authorization and patch validation"]
+
+  api -->|"Snapshot and watch updates"| gateway
+  gateway -->|"One-way SSE"| store
+  store -->|"Render draft and live status"| ui
+  ui -->|"Local edits"| store
+  ui -->|"On Save: capture patch, UID and RV from store"| save
+  save -->|"Conditional PATCH"| api
+
+  classDef library fill:#dff3ff,stroke:#1677a4,color:#062f45;
+  classDef application fill:#e4f7e8,stroke:#27834c,color:#113d23;
+  classDef upstream fill:#f8e0ef,stroke:#a83970,color:#4b1230;
+  class gateway,store library;
+  class save,ui application;
+  class api upstream;
 ```
 
 The library owns the read stream and browser reconciliation. Your application owns identity,
 authorization policy, Kubernetes credentials, and writes. The browser never receives a Kubernetes
-credential or a raw API-server URL.
+credential or a raw API-server URL. The blue boxes are the library; the green boxes are your product.
+Both Go components run inside your application: the host decides authorization policy, and the
+embedded gateway enforces it. A successful write returns through the Kubernetes watch as another
+live update.
+
+Each connection starts with a complete projected snapshot, then follows visible changes. The store
+keeps that delivered state separate from local edits. A quiet stream can still hold an older write
+version: see [why a quiet stream can reject a save](docs/saving.md#why-a-quiet-stream-can-still-reject-a-save).
 
 ## Start here
 

conformance/README.md

@@ -125,7 +125,9 @@ Every fixture names the rule it defends, in `why:`. The ones that catch real bug
 | `resync-midstream` | upstream continuity can be lost *without* the SSE connection dropping → a fresh cycle mid-stream |
 | `nested-field-removed` | `added`/`modified` **replace**; a deep-merge would resurrect a field the server deleted (a ghost) |
 | `status-follow-live` | `status` is read-only under the full projection: it follows the server live, and never becomes dirty, never conflicts, never enters a patch |
-| `status-only-churn` | a spec-only projection suppresses controller status churn entirely, without disturbing an in-flight spec edit |
+| `status-only-churn` | a final status-only write under spec projection is suppressed; visible content converges with an older held RV and an intact spec edit |
+| `final-redaction-rotation` | a final hidden-value change emits a redaction revision even when projected content excluding RV is unchanged |
+| `final-bookkeeping-only` | a final ignored bookkeeping write is suppressed; visible content converges with an older held RV |
 | `edit-vs-unrelated-change` | **R-THREEWAY** — the base is the previous *server* object |
 | `conflict-and-converge` | a conflict clears when the server's value arrives at what you typed |
 | `dotted-label-keys` | **R-ID** — `app.kubernetes.io/name` is ONE path segment. Dot-joining it is silently wrong |
@@ -161,3 +163,22 @@ reader trust a mental model that will mislead them the next time.
 2. Add `fixtures/<id>.yaml`. Say in `why:` which rule it defends; if it doesn't defend one, ask whether
    it earns its keep.
 3. `task fixtures` (rebuilds `gen/`), then `task test`. Commit the YAML **and** the generated JSON.
+
+## Convergence evidence
+
+The [normative invariant](../spec/v1.md#6-ordering-delivery--the-state-guarantee) and
+[suppression decision](../docs/proposals/0004-views-and-bytes.md#suppression) share one comparison.
+[Final bookkeeping](fixtures/final-bookkeeping-only.yaml) and
+[final spec-only status churn](fixtures/status-only-churn.yaml) run through the
+[gateway conformance suite](../gateway/stream_conformance_test.go) and the client object and SSE
+suites. The [convergence test](../packages/krm-stream/test/convergence.test.ts) compares the held
+content with the final upstream body under that projection and asserts the older held RV explicitly.
+The [gateway suppression test](../gateway/stream_test.go) also checks the suppression observation
+and original delivered object under all three built-in projections.
+The symmetric [final Secret rotation](fixtures/final-redaction-rotation.yaml) must emit its changed
+redaction revision; that same client test checks the held records at each delivered upsert.
+Existing snapshot, pruning, ordering and redaction tests remain part of `task test`.
+
+This narrows the promised invariant without changing wire emissions. The conventional `fix:` commit
+records the clarification for Release Please's generated release notes; no manual changelog entry
+is maintained. Adoption recipes, real-API save hardening and watch continuation remain subsequent work.

conformance/bodies/cm-app.v2-bookkeeping.yaml

@@ -0,0 +1,23 @@
+# A final bookkeeping-only revision of cm-app.v1: visible data stays the same.
+# Every built-in projection ignores these added managedFields and last-applied metadata.
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  uid: cm-app-0001
+  name: app-config
+  namespace: app
+  resourceVersion: "1002"
+  managedFields:
+    - manager: bookkeeping
+      operation: Apply
+      apiVersion: v1
+      fieldsType: FieldsV1
+      fieldsV1: {}
+  labels:
+    app.kubernetes.io/name: shop
+  annotations:
+    note: keep
+    kubectl.kubernetes.io/last-applied-configuration: '{"apiVersion":"v1","kind":"ConfigMap"}'
+data:
+  log-level: info
+  replicas: "3"

conformance/bodies/secret-token.v2-wire.yaml

@@ -0,0 +1,13 @@
+# The same Secret under `krm-full/v1`: values are omitted from the object. The accompanying event's
+# `redacted` entries declare which paths exist upstream, allowing the client to render them as
+# read-only without introducing a placeholder value.
+apiVersion: v1
+kind: Secret
+metadata:
+  uid: secret-token-0001
+  name: git-creds
+  namespace: app
+  resourceVersion: "4002"
+  labels:
+    app.kubernetes.io/name: shop
+type: Opaque

conformance/bodies/secret-token.v2.yaml

@@ -0,0 +1,14 @@
+# Final token rotation: username and all visible content are unchanged except RV.
+apiVersion: v1
+kind: Secret
+metadata:
+  uid: secret-token-0001
+  name: git-creds
+  namespace: app
+  resourceVersion: "4002"
+  labels:
+    app.kubernetes.io/name: shop
+type: Opaque
+data:
+  token: bmV3LXRva2Vu       # "new-token"; still withheld
+  username: Ym9i            # "bob"

conformance/fixtures/final-bookkeeping-only.yaml

@@ -0,0 +1,23 @@
+id: final-bookkeeping-only
+title: A final bookkeeping-only write leaves visible content converged and the held RV older.
+why: >
+  Spec §6 excludes metadata.resourceVersion from convergence. The final upstream write changes only
+  ignored managedFields and last-applied metadata plus RV. No later visible write refreshes the RV.
+suites: [gateway, client]
+scope: { target: demo, version: v1, resource: configmaps, namespace: app }
+projection: krm-full/v1
+watch:
+  - { op: list, bodies: [cm-app.v1] }
+  - { op: modified, body: cm-app.v2-bookkeeping }
+events:
+  - { type: reset }
+  - { type: added, body: cm-app.v1 }
+  - { type: synced }
+client:
+  expect:
+    uids: [cm-app-0001]
+    dirty: []
+    conflicts: []
+    draftSubset:
+      metadata: { resourceVersion: "1001" }
+      data: { log-level: info, replicas: "3" }

conformance/fixtures/final-redaction-rotation.yaml

@@ -0,0 +1,31 @@
+id: final-redaction-rotation
+title: A final Secret rotation must deliver its changed redaction revision.
+why: >
+  Spec §6 includes redaction records in the visible comparison. The final token rotation leaves
+  projected content excluding RV unchanged, but its changed redaction revision MUST reach the client.
+  No later write or snapshot can repair a missed rotation; the hidden token must remain absent.
+suites: [gateway, client]
+scope: { target: demo, version: v1, resource: secrets, namespace: app }
+projection: krm-full/v1
+watch:
+  - { op: list, bodies: [secret-token.v1] }
+  - { op: modified, body: secret-token.v2 }
+events:
+  - { type: reset }
+  - type: added
+    body: secret-token.v1-wire
+    redacted: [{ path: "/data/token", rev: 1 }, { path: "/data/username", rev: 1 }]
+  - { type: synced }
+  - type: modified
+    body: secret-token.v2-wire
+    redacted: [{ path: "/data/token", rev: 2 }, { path: "/data/username", rev: 1 }]
+client:
+  expect:
+    uids: [secret-token-0001]
+    dirty: []
+    conflicts: []
+    draftSubset:
+      metadata: { resourceVersion: "4002" }
+    absentPaths: [[data]]
+    readOnlyPaths: [[data, token], [data, username]]
+    patch: null

conformance/fixtures/status-only-churn.yaml

@@ -4,6 +4,9 @@ why: >
   `krm-spec/v1` ignores `status`, so a controller-only update must emit no event at all. Meanwhile the
   user is editing `spec.replicas`; the suppressed status heartbeat must not touch that draft.
 
+  The status write is final: spec §6 visible content converges without refreshing the held RV 3001
+  to upstream RV 3002. No later event is needed to satisfy convergence.
+
   On a real workload this — not editing — is the dominant traffic on the stream.
 suites: [gateway, client]
 scope: { target: demo, group: apps, version: v1, resource: deployments, namespace: app }
@@ -25,5 +28,6 @@ client:
     dirty: [[spec, replicas]]               # the ONLY dirty path — status can never be one
     conflicts: []
     draftSubset:
+      metadata: { resourceVersion: "3001" }
       spec: { replicas: 4 }                 # the edit survived suppressed status churn
     patch: { spec: { replicas: 4 } }        # status is NOT in the patch. It cannot be.

conformance/gen/bodies.json

@@ -35,6 +35,36 @@
       "replicas": "3"
     }
   },
+  "cm-app.v2-bookkeeping": {
+    "apiVersion": "v1",
+    "kind": "ConfigMap",
+    "metadata": {
+      "uid": "cm-app-0001",
+      "name": "app-config",
+      "namespace": "app",
+      "resourceVersion": "1002",
+      "managedFields": [
+        {
+          "manager": "bookkeeping",
+          "operation": "Apply",
+          "apiVersion": "v1",
+          "fieldsType": "FieldsV1",
+          "fieldsV1": {}
+        }
+      ],
+      "labels": {
+        "app.kubernetes.io/name": "shop"
+      },
+      "annotations": {
+        "note": "keep",
+        "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ConfigMap\"}"
+      }
+    },
+    "data": {
+      "log-level": "info",
+      "replicas": "3"
+    }
+  },
   "cm-app.v2": {
     "apiVersion": "v1",
     "kind": "ConfigMap",
@@ -488,5 +518,37 @@
       "token": "aHVudGVyMg==",
       "username": "Ym9i"
     }
+  },
+  "secret-token.v2-wire": {
+    "apiVersion": "v1",
+    "kind": "Secret",
+    "metadata": {
+      "uid": "secret-token-0001",
+      "name": "git-creds",
+      "namespace": "app",
+      "resourceVersion": "4002",
+      "labels": {
+        "app.kubernetes.io/name": "shop"
+      }
+    },
+    "type": "Opaque"
+  },
+  "secret-token.v2": {
+    "apiVersion": "v1",
+    "kind": "Secret",
+    "metadata": {
+      "uid": "secret-token-0001",
+      "name": "git-creds",
+      "namespace": "app",
+      "resourceVersion": "4002",
+      "labels": {
+        "app.kubernetes.io/name": "shop"
+      }
+    },
+    "type": "Opaque",
+    "data": {
+      "token": "bmV3LXRva2Vu",
+      "username": "Ym9i"
+    }
   }
 }