feat(readmodels): ProductHomeDTO, GET /api/product/home (PX-7)

[LamaSu]

PX-7: ProductHomeDTO (GET /api/product/home)

The shell's StatusBar and Command Center get their platform-wide numbers from one typed read model, so the UI projects them instead of counting (shell #2007 / #2051, product-steward #2170). Schema pcc.product-home/v1.

Stack: on #389 (feat/readmodels-operator-work), which is on #353. CI suites run only on PRs based on master (#2474), so the counts below are from local runs.

What each section says

Section	Source	Rule
kernels	kernel rows + capability rows	online / stale / other, using the kernel read model's staleness rule (isKernelStale: a 5-minute heartbeat window, with the listing grace for kernels that list a capability). The rule is stated in rule.
capabilities	capability rows + the kernels section's states	total, onOnlineKernels (the capability's kernel row exists and is online by the kernels rule; stale, offline or missing kernels never count), and byType (a row with no type is type: null, sorted last). A listing is not a promise of capacity.
jobs	job rows	byPhase over the execution phases (executionPhaseOf, the same mapping as JobExecutionDTO). active counts phases that are known and not finished; unknown is never active.
settlementNetwork	gateway config (PCC_NETWORK)	Name + chain id for known names, basis: "gateway_config". It is not evidence that any escrow lives on that network.
escrowHeld	escrow_milestones + escrows	Sums of milestone amounts in held states, per currency, exact in base units. Mock escrows (mock-escrow- addresses) are left out and counted in excludedSimulatedEscrows. confirmation: "record_only": no chain read.

A section whose read fails is {state: "unavailable", reason}, never a zero. "Gateway reachable" is not a field, because the DTO arriving already proves it. The served build commit is on /api/health (N5, #369).

What it replaces (the negative tests pin each one)

• Kernel and job counts computed from the first page of a list, or invented.
• A "Total Value Locked" that summed every escrow's totalAmount, including refunded, released and mock escrows. Escrow totals are never summed here, because an active escrow can hold released milestones.
• Unknown status words guessed into a bucket. They are counted in unclassifiedMilestones. An amount that doesn't convert to base units exactly, or has an unknown currency, is counted in uncountedMilestones.

Held / not-held milestone words (@pcc/spec)

• Held: FUNDED, LOCKED, EVIDENCE_SUBMITTED, RELEASING, DISPUTED, and the V-next states FUNDED_ACTIVE through REFUND_ALLOCATED.
• Not held: CREATED, UNFUNDED, PENDING, RELEASED, SETTLED_RELEASED, REFUNDED, SETTLED_REFUNDED, SLASHED.
• The two sets are disjoint and in normalized form.
• A spec test checks that every EscrowStatus word is in one of the sets (at compile time), along with the words the paid-job flow writes outside that type (pending, evidence_submitted).
• The escrow lane is asked to confirm the sets. SLASHED and REFUND_ALLOCATED are the judgment calls.

Tenancy

With TENANT_ENFORCE on:

• Job counts are the caller's tenant's.
• A caller with no tenant gets job counts withheld, and no cross-tenant read happens.
• escrowHeld is withheld, because escrow records carry no tenant.

The route states each withheld reason at the source. cache-control: no-store.

Evidence

• gateway: pnpm test gives 3086 passed / 6 skipped / 0 failed (190 files, solo run at bf7bd95). One earlier run alongside other suites hit the known completion-real-tier flake; that test passed 3/3 when run alone.
• spec: 875 passed.
• tsc clean for gateway and spec.
• Mutation check: 22/22 killed. The mutations covered stale counted as online, capabilities counted as live on a stale or missing kernel, typeless rows merged into a real type, the null type sorted first, unavailable capabilities read as zero, listing grace ignored, unknown counted as active, mock escrows summed, not-held words summed, unclassified words dropped, inexact amounts rounded, unsorted currencies, unavailable read as zero (kernels and escrow), an invented chain id, tenant gates removed (escrow and jobs), no-store dropped, PENDING dropped, RELEASED counted as held, and the withheld reason lost.
• The first pass found one mutation that changed no output: a duplicate tenant gate. The route now carries a single gate, at the source.

Not in this PR

• Binding the StatusBar and Command Center to the DTO; the shell owns that.
• An opportunities section. It will come with OpportunityDTO (charter item 8: public bounties plus policy-approved demand aggregates).

🤖 Generated with Claude Code

https://claude.ai/code/session_01A2ZvsqsAb7jC7AC8Viisqn