Skip to content

feat(protocol): accept usage.v6, where webhook use counts any successful delivery - #23

Merged
the-luap merged 4 commits into
mainfrom
feat/usage-v6
Oct 1, 2026
Merged

the-luap merged 4 commits into
mainfrom
feat/usage-v6

Conversation

@the-luap

@the-luap the-luap commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

Deploy this before PicPeak PR PicPeak/picpeak#1743 merges. A PicPeak install that enables participation or takes the upgrade posts usage-consent.v6 and gets SCHEMA_NOT_ACCEPTED from a collector that does not know it. Existing v5 participants are unaffected until they explicitly upgrade.

What usage.v6 is

usage.v5 with exactly one changed text: the webhooks use description. PicPeak's delivery worker now records the bit on any successful delivery (HTTP 2xx), automatic event-triggered or explicit admin test/replay, instead of only an admin test/replay enqueue — and only under confirmed usage-consent.v6. Earlier consents keep their meaning; shipped catalogs are immutable, so the wider meaning gets its own version. Same 87 keys, 64 configured/used pairs, 23 configuration-only signals, both inventory totals; diff features.v5.json features.v6.json is three lines.

What changed here

  • protocol/features.v6.json (new), protocol/schema.cjs — byte-identical to backend/src/usage/ on the PicPeak branch (cmp verified); docs/usage-coverage.v6.json (new) and docs/FEATURE_COVERAGE.md likewise. v2–v5 catalogs and protocol.cjs untouched.
  • Served automatically from the registry: /schema/usage.v6.json, /schema/ingress/usage.v6.json, /schema/features.v6.json; /api/health lists v6 in supported_schemas.
  • server/weeklyData.js, server/weeklyEmail.js — read the v6 catalog (same keys).
  • web/locales/{en,de}.json, web/main.tsx — catalogDisclosure describes v6 and its one change; a "JSON schema: usage.v6" link beside the now-legacy v5 link.
  • docs/PROTOCOL.md (lists + a short usage.v6 section), README.md.
  • Tests: test/v6.test.js (new) pins the v5 ingress schema hash — unchanged by the bump — and checks size bound, key parity with v5, rejection of extra/non-boolean webhooks fields, CONSENT_REQUIRED for a v5 participant sending v6, acceptance after consent, summary counts and unchanged retry of the old v5 packet. test/v4.test.js supported list; test/compatibility.test.js unknown-version fixture usage.v6 → usage.v7; test/integration.test.js upgrade test targets CURRENT_* instead of a literal v5, and its byte-identity lists include the v6 files.

Verification

  • npm run build (tsc + vite): passes.
  • npm test: 88 pass / 2 skipped / 1 fail — the one failure is protocol files are byte-identical in both repositories, which already fails on main before this change (same 1 failure on a clean checkout): the collector's docs/usage-coverage.v5.json is stale against PicPeak's, which changed it in picpeak#1717, #1718 and #1735 without syncing here. Not touched in this PR on purpose; a one-file sync is a separate follow-up.
  • REQUIRE_INTEGRATION=1 PICPEAK_CHECKOUT=<worktree of the PicPeak 1743 branch> node --test test/integration.test.js: 23 pass / 1 fail — the same pre-existing v5 coverage drift; every other vendored file (schema.cjs, protocol.cjs, features.v2–v6.json, usage-coverage.v2–v4,v6.json, FEATURE_COVERAGE.md) is byte-identical.
  • Note: when the integration test runs against a PicPeak checkout still on main (client at usage.v5), the four "vN to the current schema" cases fail with the client not knowing usage-consent.v6 — expected until picpeak#1743 merges; in CI (test:required) those cases skip without a checkout.

Follow-up commit

CI's picpeak checkout was pinned to 9396d019 (v5 era), so the cross-repo tests could only fail once the collector moved to v6. Pinned to 234a17c5 — the head of PicPeak/picpeak#1743 — and synced the two copies that test also compares: docs/usage-coverage.v5.json (had drifted after picpeak #1717/#1718/#1735; this closes the failure that was already on main) and web/locales/catalog.de.json (German webhooks.used text). Integration suite against that checkout: 24/24. After #1743 merges, repin ref: to its merge commit.

Paul Nothaft added 3 commits October 1, 2026 10:49
…ful delivery

usage.v6 is usage.v5 with exactly one changed text: the `webhooks` use
description. PicPeak's delivery worker now records the bit on any
successful delivery (HTTP 2xx), automatic event-triggered or explicit
admin test/replay, instead of only an admin test/replay enqueue — and
only under confirmed usage-consent.v6. Earlier consents keep their
meaning; shipped catalogs are immutable, so the wider meaning gets its
own version (PicPeak PR 1743).

protocol/features.v6.json and protocol/schema.cjs are byte-identical to
PicPeak's backend/src/usage copies on that branch; docs/usage-coverage.v6.json
and docs/FEATURE_COVERAGE.md likewise. The server serves /schema/usage.v6.json,
/schema/ingress/usage.v6.json and /schema/features.v6.json from the registry;
the weekly report reads the v6 catalog; the transparency page links the v6
schema and discloses the one change in EN/DE.

Deploy this before the PicPeak client: an install that enables or upgrades
posts usage-consent.v6 and gets SCHEMA_NOT_ACCEPTED from a collector that
does not know it. Existing v5 participants are unaffected until they
explicitly upgrade.

Tests: test/v6.test.js pins the v5 ingress schema hash (unchanged by the
bump), rejects extra/non-boolean webhook fields, and checks that a v5
participant gets CONSENT_REQUIRED on a v6 report until it consents. The
unknown-version fixture moves from usage.v6 to usage.v7; the upgrade
integration test targets the current schema instead of a literal v5.
…the v6 client

The cross-repo byte-identity test compares docs/usage-coverage.v5.json
and web/locales/catalog.de.json with the PicPeak checkout too. The v5
inventory copy had drifted (PicPeak/picpeak#1717, #1718 and #1735 changed
it without a sync) and the German catalog still carried the v5 webhooks
text. Both now match PicPeak/picpeak at 234a17c5, the usage.v6 client
branch (PicPeak/picpeak#1743), which CI's picpeak checkout is pinned to
until that PR lands; repin to its merge commit then.
npm audit --audit-level=high (the CI gate) fails on main since the
nodemailer advisories for the process-global DNS cache / TLS servername
reuse and the nested recipient-array stack exhaustion were published.
npm audit fix resolves it inside the existing ^10 range; lockfile only.

(cherry picked from commit 174b25d)
@the-luap
the-luap merged commit ae8b3ec into main Oct 1, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant