feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13)

[LamaSu]

Summary

Adds the kit-demand signal and the pure layer a publisher would use to release public opportunity aggregates. The signal is the private demand input that Capability Kit work uses to decide which kits to fund.

This is interface and library code only: no routes, no gateway changes, and nothing public is emitted.

• @pcc/spec
  • UnmetReason, UnmetCapability, and a server-owned DemandEnvelope.unmet. UnmetCapabilitySchema ties the key form to the reason: no_capability_type only as a kebab slug, every other reason only as a CSD URI.
  • CallerDemandEnvelopeSchema is the caller input without any server-only field. ServerCapturedDemandEnvelopeSchema is the only schema that carries unmet. stripServerOnlyDemandFields() stays as a second guard.
  • KitDemandSignal is a private record per capability key. It holds counts by evidence class, exact verified-requester counts and histograms, with consistency refinements and a sha256:<hex> digest.
  • The public release layer, reworked after the round-1 cross-family review (pack 10, findings F1-F5):
    • one frozen PUBLIC_RELEASE_POLICY: k = 5 distinct verified requesters at or above an authenticated-order floor, with a 24 h grace. No caller can choose a policy;
    • only canonical UTC calendar-month periods, released after the month closes. Any other window, an open month, or a signal computed before the close throws;
    • only IDs in a publisher-supplied approved set that pass isPublishableCapabilityId: a CSD URI whose slug has at most 40 characters, at most 3 hyphens and no run of 4+ digits;
    • a period label, never an activity date. Counts are banded 5-9 / 10-24 / 25-99 / 100+;
    • buildPublicRelease() returns one deterministic release per period, with the approved set's digest and a release digest, for a publisher to record once.
• @pcc/demand-intel: UnmetDemandLens folds server-captured unmet intents into validated signals. computeForPeriod() produces the input for a release.
  • It reads only first-party capture event types, never intent.external_ingest.
  • It resolves keys reason-first and can drop CSD URIs outside a registered set.
  • Verified breadth counts only actorType: "authenticated_operator" rows. Counting is exact, and timestamps come from the server row.

Not in this PR (by design)

• Nothing is public. There is no publisher and no endpoint. The publisher (a no-parameter read surface, a server release job, a write-once ledger per period, the approved set) is separate work and defaults OFF.
• Cross-release and cross-key privacy accounting is an open decision. A public feed waits for it and for proven requester identity.
• The gateway half (server-computed unmet at capture, actor labels, ingest parsing) is feat(gateway): server-side unmet-demand capture, flag default OFF (R44 D2, stacked on #365) #387, stacked on this PR.
• No data. Every fixture is synthetic.

Tests (base ac86a404)

Package	Typecheck	Tests
@pcc/spec	clean	865/865 across 39 files
@pcc/demand-intel	clean	55/55 across 5 files

The adversarial cases the round-1 review asked for:

• two k values;
• sliding windows at millisecond precision;
• a CSD-shaped no_capability_type key;
• one unverified late intent.

Also covered: open and in-grace months, signals computed before the close, exact approved-set membership, ID hygiene, release determinism and input immutability.

Each guard was mutation-checked locally: removing it fails the suite. CI build-and-test passes at 6377dd5d.

Review

• Round 1 (pack 10): DO-NOT-SHIP as a public feed; the private signal and lens could continue. This head addresses all five findings in the pure layer. Round 2 is queued.
• Merge is the operator's call.

🤖 Generated with Claude Code