fix(gateway): register only declared tiers and pricing from heartbeats (board N23)

[LamaSu]

Summary

Board row N23 (composition), the data-layer half. Steward ruling #3538.

KernelFacade.heartbeat serves POST /api/kernels/:kernelId/heartbeat and POST /api/operator/heartbeat, the path pcc-node's daemon calls. It auto-registers the capabilities a kernel announces. When an announcement carried no terms, it filled them in: assuranceTiers ?? [0, 1] and pricing ?? {currency: "USDC", baseCost: "0", minimum: "0"} (kernel.facade.ts 531-533 at master). Every reader then took the defaults as the provider's own offer:

• The catalog lists a price nobody set ("USDC 0") and tiers nobody declared.
• The plan re-read (R10, revalidatePlanSnapshots, feat(gateway): live provider re-read for externally authored plans (R10) #355 on the stack) re-reads rows as the provider's terms. So a heartbeat with a real price and no tiers yields a row that R10 sells at tier 1. R10 itself refuses the zero price (non-positive-price).

The change

A NEW announced capability is registered only when it declares both of these:

Term	Required shape	Stored as
tiers	a non-empty list of integers 0..3, at most 16 entries	a sorted set
pricing	currency ([A-Za-z0-9]{1,16}), baseCost and minimum (the column's type needs both), plus any of perMinute, perGram, perCm3; all plain decimal strings, and at least one non-zero	exactly as declared

Anything else is skipped, and the heartbeat response says why.

• A new additive field, capabilitiesSkipped: [{type, reason}], with reason one of no-declared-tiers, invalid-tiers, no-declared-pricing, invalid-pricing or zero-price.
• capabilitiesReceived still counts every announcement.
• Existing rows are untouched. A heartbeat only refreshes their TTL, as before.
• Capping tiers at the kernel's verified ceiling is N43's handler half (gateway, WP-C), not this PR.

Why skip rather than store an incomplete row. pricing is a NOT NULL column typed {currency, baseCost, minimum, ...}, so "no price" has no type-valid representation. An off-type {} would reach every catalog reader. A typed "terms not declared" state belongs in the capability DTOs (PX-7).

Know this before merging

• pcc-node's daemon announces capabilities without terms. daemon.py _build_capabilities_from_devices sends {type, deviceId, protocol}.
  • After this PR, a NEW kernel's daemon-announced capabilities are not auto-registered until the daemon declares tiers and pricing.
  • Today those rows carry the invented defaults, and they are unsellable through R10 anyway because of the zero price.
  • Follow-up for pcc-node's owner: declare the terms. The agent package's operator_heartbeat schema also leaves the capability items untyped.
• Existing defaulted rows in production remain, and one kind is live-sellable. Fixing or retiring them is a production DB write, so it is parked for the operator and not part of this PR. There are two kinds.
  • Both terms defaulted (pricing exactly USDC / "0" / "0", tiers [0, 1]). R10 refuses these on the zero price.
  • A real declared price with DEFAULTED tiers. The kernel sent pricing but not tiers, so the row was stored with tiers [0, 1]. R10 sells these at tier 1 today. They cannot be told apart from a declared [0, 1] by the row alone.
  • Candidates can be found as rows whose id is cap-<kernelId>-<type>, whose description is the heartbeat default (Auto-registered from heartbeat for kernel <kernelId>), and whose tiers are [0, 1]. A kernel that sent its own description is not caught this way.
  • The operator decides whether to retire them or require re-declaration.
• Gateway's unpushed WP-C fold may touch the same file (kernel.facade.ts; steward #3538).
• Siblings the sweep found, left alone here and listed for their owners:
  • facades/capability.facade.ts:337: POST /api/capabilities defaults pricing to "USDC 0" (N43's handler half, gateway).
  • routes/onboard.ts:84, routes/wizard.ts:590, routes/setup.ts:655: zero-price defaults.
  • routes/capabilities.ts:679: the TD output defaults tiers to [0, 1, 2, 3].
  • services/agentic-decomposer.ts:238: the legacy decomposer's ?? [0, 1]. Its proposals re-quote at R10.
  • This same insert's location ?? {lat: 0, lng: 0}, outside the ruled scope.

Tests

Suite	Result
new heartbeat-declared-terms.test.ts	9 passed
protocol-fixes and kernel-ttl-integration, whose announcements now declare terms	passed (31 with the new file)
full gateway	2936 passed, 6 skipped, 0 failed

Two suites fail to load in a worktree without a built @pcc/verifier dist: capture and capture-3d. They are untouched here, and CI builds first.

• The real-state test runs the real routes and the real facade over an in-memory store, including the exact payload pcc-node's daemon sends. It shows that no row is registered and none offers tier 1.
  • R10 is not on master. The R10-level assertion ("a heartbeat without tiers, then R10 must not sell tier 1") goes into the real-state trace (test(gateway): end-to-end accept trace over real SQLite rows and the real routes (composition) #433) once this reaches the stack.
• Mutations: 12 of 12 killed. Each was read from its counts:
  • restoring either default;
  • dropping the zero check;
  • weakening the tier range;
  • ignoring the tier skip;
  • dropping normalization;
  • dropping any pricing pattern or presence check;
  • accepting an empty list;
  • dropping the tier-count cap;
  • keeping unknown pricing keys.

Review

• Gateway reviews on resume (steward #3538).
• Cross-family: pack 53.

🤖 Generated with Claude Code