feat(gateway): server-side unmet-demand capture, flag default OFF (R44 D2, stacked on #365)

[LamaSu]

Summary

The gateway half of the kit-demand work, stacked on #365. With PCC_UNMET_CAPTURE_ENABLED=true (default OFF), the first-party intent capture points record two server-owned facts.

1. Who made the request. It comes only from the server-side auth context, never from the body, and is recorded at one of two strengths:

   • authenticated_operator: a proven wallet only. That is an /a2a SIWE session, or req.provenWallet once the gateway's identity binding sets it. Nothing sets req.provenWallet yet, so /api routes record none.
   • authenticated_key: a plain API-key holder. The key's operatorId is self-asserted at provisioning, so it counts as volume, never breadth.

   All identity reading for capture lives in services/unmet-capture.ts.

2. Which requested types no live supply can serve (fulfillmentPath plus unmet), from CapabilityFacade.listByType:

   • Live supply decides whether a type is served. The CSD registry decides only the key.
   • Every listed entry passes UnmetCapabilitySchema: a registered type is keyed by its canonical CSD URI, and a type with no CSD appears only as no_capability_type with a slug.
   • An unmet type that cannot be keyed that way is counted, not listed. The intent is still marked unfulfilled, never auto.
   • Matching runs off the response path and never rejects. It checks at most 16 types per intent and records unmetTruncated, and it reads supply through a bounded per-type 30 s cache.

Separately and unconditionally, POST /api/intents/ingest parses with CallerDemandEnvelopeSchema, which has no fulfillmentPath, unmet or unmetTruncated, and strips them again. A caller can never assert unmet demand.

With the flag OFF, the capture points emit exactly what they emit today.

Changes

File	Change
packages/gateway/src/services/unmet-capture.ts	new: principal extraction at two strengths, flag, bounded cached supply reads, schema-checked matcher, envelope stamping, off-path emit
routes/requests.ts, routes/negotiation.ts	matcher plus principal, flag-gated, off the response path
routes/a2a-tasks.ts	the resolved key or SIWE session is passed down explicitly
routes/nl-query.ts	principal only (its type is unknown_synthetic, so there is no matching)
routes/intent-ingest.ts	parses with CallerDemandEnvelopeSchema, plus the strip
services/event-bus.ts, packages/spec/src/types/analytics.ts	authenticated_operator and authenticated_key added to the actorType union
packages/spec/src/types/demand.ts	server-owned unmetTruncated; the strip helper covers it

Not in this PR

• price_exceeds_budget and region_unavailable are not computed: there is no reliable price or service-area supply data yet.
• funded evidence is a follow-up.
• A2A quote failures still emit no intent.
• Proven identity on /api routes waits for the gateway's identity binding. Until then, breadth there is 0. An /a2a SIWE wallet already counts as proven, following the gateway's definition. Such wallets cost nothing to mint, so whether they are enough for a public k is an open decision, and the public feed waits for it.

Tests

All run locally at 991e635b. CI runs suites only on PRs based on master, so this stacked PR gets no suite run until it is retargeted.

Package	Typecheck	Tests
@pcc/gateway	clean	3026 passed, 6 skipped, 0 failed across 189 files
@pcc/spec	clean	865/865
@pcc/demand-intel	clean	55/55

• unmet-capture.test.ts (31 tests) covers:
  • the flag;
  • both principal strengths, and that body fields are never read;
  • every matcher outcome;
  • schema-consistent keys (no capacity for an uncatalogued type, non-canonical CSD URLs, and unslugifiable names all end up unkeyed);
  • the cache TTL and bound;
  • truncation;
  • the never-rejecting emit.
• unmet-capture-routes.test.ts (14 tests) runs against real routes and a seeded store. It covers:
  • flag OFF is unchanged;
  • key holders are labelled authenticated_key, and proven wallets authenticated_operator (lower-cased);
  • smuggled identity fields are ignored;
  • ingest drops all three server-only fields.
  • Seam (capture → lens → buildPublicRelease):
    • 4 proven principals stay private and 5 publish 5-9 for the period;
    • a repeat wallet adds volume, not breadth;
    • an unapproved type stays private;
    • key holders and proposed types never publish.

Review and merge

• Gateway review: SHIP_WITH_FIXES; both fixes are in ebf7c70a.
• Round 1 cross-family: pack 10; the fixes are here and in feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13) #365. Round 2 covers this head.
• The PR is retargeted to master before merge, after the auth-hardening PR fix(gateway)!: WP-A scope hardening — wildcard is not money/admin authority, fail-closed scopes, identity binding (P0 MUST-CLOSE 6-10) #326.
• Merge is the operator's call.

🤖 Generated with Claude Code