feat(examples): compare native, full and spec sources with measurements

CONTRIBUTING.md

@@ -19,8 +19,8 @@ Start with watch streams and authoritative resource views; add editing as an opt
 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 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.
+writes conditional merge patches back through the same proxy; the comparison example measures the
+sources side by side. Streaming lists, pagination and editor cleanup 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.
@@ -66,6 +66,8 @@ the rule it protects.
 | `task e2e-browser` | Native `EventSource`, unbundled ESM and the native viewer and editor pages in Chromium. |
 | `task cluster-facts` | Record observed Kubernetes behavior for the supported cluster version. |
 | `task test-real-api` | Compose the save path and native viewing and editing against a real API server: gateway or host proxy, host endpoint and browser store. |
+| `task compare-browser` | The comparison page in Chromium against the real comparison host, on both entry points. |
+| `task compare-measure` | Measure native, full and spec sources, unshared and shared, under identical workloads against a real API server; `task compare-native-baseline BASELINE_REF=<sha>` compares the native connector with an earlier build. Results are evidence for the run, recorded in `docs/facts/`. |
 | `task test-cluster` | Exercise the Kubernetes backend against a real API server. |
 
 The cluster tasks need Docker and take longer; the fixture suites are the per-pull-request baseline.

Taskfile.yml

@@ -96,7 +96,7 @@ tasks:
   # -------------------------------------------------------------------- test --
   test:
     desc: "Run both suites against the shared conformance fixtures."
-    deps: [test-gateway, test-kube, test-client, test-vue]
+    deps: [test-gateway, test-kube, test-client, test-vue, test-compare]
 
   test-gateway:
     desc: "Go: the gateway + its half of the conformance suite."
@@ -136,6 +136,15 @@ tasks:
     cmds:
       - npm test
 
+  test-compare:
+    desc: "Typecheck the comparison page and driver, and test their field sync and measurement gates (no cluster)."
+    deps: [_client-deps]
+    cmds:
+      # The page and the driver are the only TypeScript outside the client package that nothing else
+      # typechecks: build.mjs and node both strip types without checking them.
+      - packages/krm-stream/node_modules/.bin/tsc -p examples/comparison
+      - node --test examples/comparison/fields.test.ts examples/comparison/gates.test.ts
+
   _vue-deps:
     internal: true
     dir: examples/vue
@@ -385,7 +394,7 @@ tasks:
     cmds:
       # .task/ is Task's checksum store: what makes a task say "up to date". Remove it when one is wrong.
       - rm -rf .task
-      - rm -rf {{.CLIENT_DIR}}/node_modules {{.CLIENT_DIR}}/dist examples/native-editor/dist
+      - rm -rf {{.CLIENT_DIR}}/node_modules {{.CLIENT_DIR}}/dist examples/native-editor/dist examples/comparison/dist
       - rm -rf examples/vanilla-browser/node_modules
       # Go's test cache is content-addressed and sound: a cached `ok` means those inputs really did
       # pass. Use `go test -count=1` to watch a suite run; `go clean -cache` buys nothing but minutes.
@@ -478,3 +487,76 @@ tasks:
       # -p 1: the shared-host example measures a CLUSTER-WIDE API-server watch gauge, which the
       # backend suite's own real watches corrupt if their packages run concurrently.
       - go test -tags e2e -v -count=1 -p 1 -timeout 10m ./...
+
+  # ------------------------------------------------------------- comparison --
+  # One host serves the same Widgets and Secrets through every source — native /k8s, krm-full/v1 and
+  # krm-spec/v1, unshared and shared — so a page and a driver can compare them under identical churn.
+  # Port 8110, so it never collides with `task demo` or a browser suite on 8100. See
+  # examples/comparison/README.md and the dated runs in docs/facts/comparison-*.md.
+  build-compare-page:
+    desc: "Build the library and compile the comparison page's controller, with the editors and recipe it reuses, into examples/comparison/dist."
+    deps: [build-client]
+    sources:
+      - examples/comparison/build.mjs
+      - examples/comparison/page.ts
+      - examples/comparison/fields.ts
+      - examples/native-editor/editor.ts
+      - examples/conditional-save/editor.ts
+      - examples/editor-recipes/keepLocal.ts
+    generates:
+      - examples/comparison/dist/page.js
+    status:
+      - test -f examples/comparison/dist/page.js
+    cmds:
+      # Types stripped, library import renamed to the published package; see build.mjs.
+      - node examples/comparison/build.mjs
+
+  compare:
+    desc: "Serve the comparison page against the spike cluster: native vs krm-full/v1 vs krm-spec/v1, with editing and counters."
+    deps: [cluster-up, build-compare-page]
+    dir: gateway/kube
+    env:
+      KUBECONFIG: '{{.KUBECONFIG_PATH}}'
+    cmds:
+      # The browser address is the TLS one: HTTP/2, so the page's six streams do not use up the six
+      # HTTP/1.1 connections a browser allows one origin. The certificate is self-signed at startup.
+      - echo "→ https://127.0.0.1:8111/   (also ?entry=bundle, ?variant=shared; plain http://127.0.0.1:8110/ is for drivers)"
+      # Foreground, so Ctrl-C reaches the host, which deletes its scratch namespace on the way out.
+      - go run ./examples/comparison/cmd/compare --addr 127.0.0.1:8110 {{.CLI_ARGS}}
+
+  compare-browser:
+    desc: "The comparison page in Chromium against the real comparison host, on both entry points (needs the spike cluster)."
+    deps: [cluster-up, build-compare-page, _example-deps]
+    env:
+      KUBECONFIG: '{{.KUBECONFIG_PATH}}'
+    cmds:
+      # BUILD the host and hand Playwright the binary: `go run` would leave its child holding the port
+      # and keep the scratch namespace alive when Playwright stops the parent.
+      - |
+        set -e
+        bin="$(mktemp -t krm-compare-XXXX)"
+        trap 'rm -f "$bin"' EXIT
+        (cd gateway/kube && go build -o "$bin" ./examples/comparison/cmd/compare)
+        cd examples/vanilla-browser
+        npx --no-install playwright install chromium --with-deps >/dev/null
+        COMPARE_BIN="$bin" npx --no-install playwright test -c compare.config.ts {{.CLI_ARGS}}
+
+  compare-measure:
+    desc: "Measure every source under every workload against the spike cluster (CLI_ARGS go to measure.ts)."
+    # Not cached, and it must not be: it measures a cluster, not files.
+    deps: [cluster-up, build-client]
+    env:
+      KUBECONFIG: '{{.KUBECONFIG_PATH}}'
+    cmds:
+      - bash examples/comparison/measure.sh {{.CLI_ARGS}}
+
+  compare-native-baseline:
+    desc: "Native before/after: measure the native source with the library built at BASELINE_REF (default main), then with this tree's."
+    deps: [cluster-up, build-client]
+    vars:
+      # Name the commit BEFORE the change under test. Once main contains it, main is not a baseline.
+      BASELINE_REF: '{{.BASELINE_REF | default "main"}}'
+    env:
+      KUBECONFIG: '{{.KUBECONFIG_PATH}}'
+    cmds:
+      - bash examples/comparison/measure.sh --baseline-ref {{.BASELINE_REF}} {{.CLI_ARGS}}