feat(spec): Capability Kit manifest identity, OperatorBindingDTO and OpportunityDTO v0 contracts (interface-only; not before wave D)

[LamaSu]

Summary

These are interface-only @pcc/spec contracts for the kits lane (ledger R5/R6/R7/R8/R41/R45, product PX-13). The PR adds no routes and no storage. It is not for merge before wave D (steward ruling #3058).

The contracts are v0, frozen for consumers: adk (R4), readmodels (PX-7), operator-ux (PX-11) and refvertical (R46) build against these shapes, and any change needs their ack on the bus first.

types/capability-kit.ts: Capability Kit manifest and identity

• The manifest references existing artifacts by digest and inlines none. CapabilityKitManifestV1 is strict zod, and its references are:
  • a CSD pinned by capabilityContractDigest, because a url alone is a mutable pointer;
  • artifacts named by the sha256 of their bytes: adapter or method, tests, install and provenance recipes, and machine-native labware, PLR and CAD files;
  • economics-lane terms hashes, which only economics compiles.
• Identity. computeKitDigest = sha256(canonicalize(normalized manifest)). That is the same construction as capabilityContractDigest and uses the single @pcc/spec canonicalizer. List order never changes the digest.
• Lineage. parentKitDigest records forks and revisions.
• Golden vectors are pinned. The minimal one was re-derived independently in Python and matches sha256:e05bb524…2527. Re-run them when N15 / fix(spec): canonicalize refuses values that have no JSON form #359 changes the canonicalizer.
• Reusable vs one-off. validateKitCompleteness separates a reusable kit from a one-off listing. A reusable kit has an implementation, tests, an install recipe, a provenance recipe and a license. This is the L1 acceptance rule for kit-build bounties.

types/operator-binding.ts: OperatorBindingDTO v0

The shape was agreed with operator-ux (bus #2896 / #2944):

• Principal: principal.identityStatus is self_asserted | proven.
• Server-derived fields: executorKinds, the bindings (each with a kitDigest and a server-capped tier), and claim rights.
• No money authority: moneyAuthority is the literal "none". Execution authority is derived from bindings, never from the key's scopes.
• Payee: a masked read of the server-resolved destination (N21). The schema refuses an unmasked address, and a binding grants no payout or spend authority (R41).

types/opportunity.ts: OpportunityDTO v0

There are three kinds: funded_offer, kit_build_request and demand_aggregate.

• Funding: funded needs an authoritative, server-verified source.
• Demand aggregates carry exactly painpoints' toPublicOpportunityAggregate fields (type, band, as-of): no location, evidence or deadline, and no raw intents, priors or requester identities.
• Hygiene: amounts are base-unit strings, titles are single-line and server-templated, and the schema is strict.

Tests

Command (run on the Spark in /mnt/sparkbulk/pcc-lanes/wt-kits-spec)	Result
packages/spec: npx vitest run src/__tests__/kits-contracts.test.ts	21/21
packages/spec: npx vitest run	818/818 (39 files)
packages/spec: npx tsc --noEmit	exit 0

The tests cover:

• digest determinism across key and list order;
• that every content change moves the digest;
• that invalid manifests get no identity;
• fork lineage, the golden vectors and completeness;
• the money-authority and masking invariants;
• the funding and aggregate invariants.

Merge conditions (steward #3058)

1. The OpportunityDTO exposes only the k-suppressed public aggregate. The steward runs a boundary check before any merge.
2. Golden vectors are re-run when fix(spec): canonicalize refuses values that have no JSON form #359 lands.
3. OperatorBindingDTO carries no money or payout authority.
4. The shapes are v0, frozen for consumers.

Merging is the operator's call, and only after wave D opens.

Refs: kits reconciliation §0.4 K1/K3/K4 and §0.5.1; bus #2780 (refvertical manifest mapping), #2896/#2944 (operator-ux), #2607 (painpoints demand policy).

Round 3: astra 112b fixes, at a173743

Every open finding was reproduced at 072f9a1 first. The fixes are in 8 commits, written by a Sonnet implementer from my spec, then reviewed and mutation-checked by me:

• CRITICAL 1 (demand privacy): a demand_aggregate's capabilityType must be IN an approved public set (opportunityDTOSchemaFor; the default is the built-in CSDs, and ACTIVE kits come via publicCapabilityUrls). It carries a required releaseDigest, and demandAggregatesFromRelease checks the record's digest, its approvedSetDigest (same bytes as feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13) #365), its periods and its membership.
• License: isAllowedLicenseExpression is an honest allow-list (renamed from isSpdxLicenseExpression).
• HIGH 4: executable means evidenceIsExecutable: tier-eligible under evidence's computeCsdEligibility, with live verifiers. validatePrimitiveParams fails closed.
• Masking and describe: at most 25% of a destination is revealed, and describe refuses scheme:// text.
• Read times: asOf and lastSeenAt may not run more than 5 minutes ahead of the parsing clock.
• Versioning: a semantic corpus per literal (refinements included) is pinned with the shape fingerprint.

Evidence: spec 885/885, both typechecks clean, mutations 10/10 killed in my independent pass. Review pack: 112c-k-397-r3-a173743e.

At merge with master, one pinned test (the built-in public list) gains pcc://capabilities/document-print-and-mail/v1 (2d80818) by design.

Round 4: astra 112c fixes, at cbc1c14

Master was merged first (3f16596). It brings painpoints' #365 (types/kit-demand.ts) and the 9th built-in CSD. Every open finding was reproduced at a173743 first. The fixes are mine:

• CRITICAL 1: demandAggregatesFromRelease reads feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13) #365's exact PublicOpportunityRelease:
  • the one fixed policy (k 5, counted at authenticated_order);
  • releasable only after feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13) #365's 24-hour grace, by the server clock;
  • its digest and approved-set digest.
  • A DTO's asOf must come after the period's close plus that grace.
• HIGH 4: evidenceIsExecutable is CUMULATIVE. It builds a dependency-closed program for tiers 0 through the target, runs evidence's computeCsdEligibility with requireImplementedVerifier, and requires every tier through the target to be eligible. Payer approval alone is no longer executable at tier 2 or 3.
• MEDIUM 8: each literal's lock also pins the SHA-256 of its defining module, so a refinement-only edit fails the lock until it is deliberately re-pinned.

Evidence: spec 1185/1185, both typechecks 0, mutations 8/8. Review pack: 112d-k-397-r4-cbc1c149.

Round 5: astra 112d fixes, at 79a3330

Both open findings were reproduced at cbc1c14 first (3 failing cases, 2 controls). The fixes are mine:

• CRITICAL 1: the release reader requires feat(spec,demand-intel): kit-demand signal and fixed periodic public release layer (R44, PX-13) #365's canonical order (capabilityType strictly increasing in code units, as buildPublicRelease sorts), so a reordered record is refused and the order carries no information.
• HIGH 4: every named primitive must sit in some tier, or the requirement is not executable. A primitive with an unmet dependency (for example confirm.execution_mode without receipt.kernel_signed) is no longer silently dropped. The test that pinned that hole now expects false.
• LOW: the module header names every external input.

Evidence: spec 1187/1187, both typechecks 0, mutations 11/11, opportunity corpus 97 cases (LOCK re-pinned). Review pack: 112e-k-397-r5-79a3330d.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FT8WYWkfig4KNcxtMqvMuj