docs(lab): CL-10 public evidence contract

[Wibias]

Summary

Defines the CL-10 contract for public Compatibility Lab evidence export, publishing, and community trust.

This is the final planned Compatibility Lab phase after merged CL-09.

Base

• dev: 4fed8d3fe431ad23be83f3aff2af18ef8b8ecd71
• CL-09 prerequisite: merged feat(lab): CL-09 passive production evidence #1489 at the same commit
• branch: feat/cl-10-public-evidence-contract

Scope

Contract/design only. No runtime export, upload, remote fetch, signing-key creation, community cache, API, CLI, or UI implementation is included or authorized by this PR alone.

The contract freezes:

• a closed PublicEvidenceBundleV1 export schema
• strict public-route exportability rules so private route dimensions cannot be silently generalized away
• export-scoped IDs with no relationship to local subject/event/request/decision/Fabric IDs
• UTC-day time bucketing and diagnostic minimization
• explicit public_export artifact policy plus second-pass privacy scanning
• explicit user consent with no automatic telemetry or background publishing
• pseudonymous Ed25519 publisher provenance and bundle signatures
• separate community_untrusted_v1 trust semantics for imported evidence
• complete isolation of community evidence from local canonical verdicts, freshness, Routing Profiles, Router Intelligence, and CL-08 scheduling
• signed revocation semantics
• strict import bounds and fail-closed unknown-field handling
• a hard gate that forbids remote publishing until an exact service origin/security/retention/revocation contract is independently reviewed

Chosen architecture

local canonical Lab evidence
  -> exportability gate
  -> allowlist-only public projector
  -> export privacy scan
  -> export-scoped IDs
  -> canonical bundle digest/signature
  -> explicit local export
  -> optional publish only after transport contract acceptance

community bundle
  -> bounded schema/digest/signature verification
  -> separate non-authoritative community cache
  -> clearly labelled read surfaces
  X-> no compatibility.jsonl writes
  X-> no local verdict/routing/CL-08 feedback

Delivery sequence after contract acceptance

1. CL-10.1 public projector and privacy validator
2. CL-10.2 public bundle storage and publisher signatures
3. CL-10.3 local preview/export surfaces
4. CL-10.4 community import, verification, revocation, and read surfaces
5. CL-10.5 remote publishing only after the exact service contract is accepted
6. CL-10.6 adversarial closure and programme acceptance

Files

• devlog/_plan/260807_compatibility_lab/010_cl10_public_evidence_export.md
• docs/superpowers/specs/2026-08-12-cl10-public-evidence-design.md

Review focus

Please review this primarily as a privacy/trust boundary, not as a product-surface proposal.

Key questions:

• Can any local/private identity still leak through the public schema?
• Can an exact private route be misleadingly generalized into a public claim?
• Are publisher signatures described narrowly enough to avoid implying truth?
• Is community evidence completely isolated from local authority and routing?
• Are consent, revocation, and remote-publishing gates strong enough?

Validation

Contract PR minimum:

• branch is based exactly on current dev
• no runtime/source files changed
• no TODO/TBD placeholders in the normative contract
• repository markdown/hygiene checks
• CodeRabbit / independent review

Do not merge based only on the contract draft. Runtime CL-10 implementation starts only after independent contract acceptance.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 59ffa949-5257-4bcf-a480-e6731c337386

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

Contract review on exact head e07ea0949ad528c9b4de3d1c6469cf7852d0339d against current dev@cbbfdd877.

The overall privacy/trust direction is conservative and valuable: public export is an allowlist-only projection, private route dimensions make evidence non-exportable instead of being silently generalized, local identifiers and arbitrary diagnostics are excluded, signatures prove integrity/continuity rather than truth, explicit consent is required, community evidence remains non-authoritative, and remote publishing is blocked on a later fixed-origin service contract. I found no runtime behavior change because this PR changes documentation only, and exact-head docs/hygiene CI is green.

I am not approving the contract yet because two normative boundaries need to be made exact before implementation starts:

1. Canonicalization and signature domain are underspecified. The contract names deterministic canonical bytes and Ed25519 signatures, but it does not freeze a concrete canonicalization algorithm/encoding or state whether bundleDigest and signature are excluded from the signed payload. It also does not freeze domain-separation bytes and verification order. Different serializers could produce incompatible or ambiguously self-referential bundles. Define one exact byte contract (for example, a named canonical JSON profile with UTF-8, integer/string rules, object-key ordering, and duplicate-key rejection), the exact preimage for bundleDigest, the exact signature preimage/domain tag, and the validation order.

2. Revocation trust needs an anti-substitution rule. “The same publisher key” is necessary but not sufficient if an importer accepts a valid signed revocation whose publisher identity or target IDs are not bound to the original imported bundle's verified signer and schema domain. Require the revocation preimage to include a dedicated domain tag, schema/version, publisher key identity, target bundle/record IDs, and issued day; importers must apply it only when the verified key exactly matches the target bundle's verified publisher key. Also define deterministic conflict/replay handling for repeated or contradictory revocations.

Please update both the normative CL-10 contract and the shorter design summary so they do not diverge. After those byte-level and revocation bindings are explicit, this remains a strong contract candidate. This comment does not authorize runtime export/publish/import implementation or remote service selection.