feat: start v2 milestone — Exchange (HEP-7) and Registry (HEP-8) layers#18
Merged
Conversation
Open the v2 milestone by promoting the Exchange and Registry design sketches into the normative specification through the HEP process. v2 is additive: harness.yaml `version` stays "1" and harness.schema.json's $id is frozen; the new layers get their own schemas under the /schema/v2/ $id namespace. - HEP-7 Exchange: signed offer envelope + consent-first peer-to-peer flow. Adds exchange.schema.json, protocol/exchange.md (+ docs mirror), examples/exchange/, security/exchange.md, and eval coverage. - HEP-8 Registry: hosted discovery, SHA-256 integrity, transparency log. Adds registry.schema.json, protocol/registry.md (+ mirror), examples/registry/, security/registry.md, and eval coverage. - security/crypto-map.md reconciles ed25519 (Exchange transit), SHA-256 (content/index integrity), and minisign (publisher signing, per integrity.md) as orthogonal primitives. - Framing: README/overview/getting-started layer tables, CHANGELOG [Unreleased] v2 section, GOVERNANCE three-version model; extensions sketches converted to promoted-pointer stubs (repo + site mirrors). Both HEPs are Draft with the in-repo format prototype satisfied; runtime prototypes (harness-kit) gate Accepted status. Refs #16, #17 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…rency log Independent review (sonnet + haiku critics) caught two consistency bugs in the v2 kickoff that falsified the "purely additive" claim: - B1: Exchange's Apply step annotated the resulting `extends` entry with `x-exchange-received-from`/`x-exchange-received-at` and used `source: local://...`/`file://...`. But v1 `extends[].items` is `additionalProperties: false` (only `source`/`version`; no `x-` carve-out) and v1 source-resolution defines no `local://`/`file://` schemes — so the applied harness would fail v1 validation. Fixed by referencing the received fragment via a standard `./` local source and keeping provenance in the implementation's exchange store, off the harness file. Updated protocol/exchange.md (+mirror) and HEP-7. - B2: security/integrity.md describes a v2 transparency log whose entries carry minisign signatures, conflicting with registry.schema.json's hash-only index events, and labels mandatory-integrity/signing "v2" ambiguously. Added a scope note to integrity.md (+mirror) and reciprocal notes in registry.md and crypto-map.md (+mirrors): one append-only log, hash-based in v2, signatures added when publisher signing ships. Also: forbid `recipient` on plaintext offers in exchange.schema.json (the unaddressed invariant); note that `expires` is unsigned so relays must enforce against their own clock (security/exchange.md); add eval coverage for the apply-step round-trip and the plaintext-recipient rejection. eval: 292 passed. Docs build: clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
b6ffb89 to
53fd8cb
Compare
This was referenced Jun 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Opens the v2 milestone by promoting the Exchange and Registry design sketches into the normative specification through the HEP process. The defining property: v2 is additive, not a schema break —
harness.yamlversionstays"1",harness.schema.json's$id(/schema/v1/…) is frozen, and a v1 fragment is Exchange-compatible and Registry-indexable unmodified. The new layers get their own schemas under the/schema/v2/$idnamespace.Both HEPs are Draft with the in-repo format prototype satisfied (schema + examples + eval + prose); runtime prototypes in harness-kit gate Accepted status.
Refs #16 (Exchange), #17 (Registry).
Changes
HEP-7 — Exchange (peer-to-peer 1:1 fragment sharing):
heps/hep-0007-exchange-layer.md— Standards Track HEP; resolves the 6 open questions from the sketch.schema/draft/exchange.schema.json— the signed offer-envelope (ed25519 identity, optional X25519 encryption,oneOfplaintext/encrypted).protocol/exchange.md(+ docs mirror),examples/exchange/(plaintext + encrypted),security/exchange.md(+ mirror), terminology, andeval/src/tests/schema/exchange.test.ts.HEP-8 — Registry (hosted 1:many discovery):
heps/hep-0008-registry-layer.md— Standards Track HEP; v2/v3 boundary kept verbatim.schema/draft/registry.schema.json— transparency-log entries + registration request/response shapes.protocol/registry.md(+ mirror),examples/registry/,security/registry.md(+ mirror), andeval/src/tests/schema/registry.test.ts.Cross-cutting:
security/crypto-map.md(+ mirror) — reconciles ed25519 (Exchange transit), SHA-256 (content/index integrity), and minisign (publisher signing, owned byintegrity.md) as deliberately orthogonal primitives; registry-index signing deferred to v3.eval/src/lib/schema.ts— addsvalidateExchange/validateRegistryloaders.protocol/overview.md/ getting-started layer tables → "draft (HEP-7/8)";CHANGELOG.md[Unreleased] — v2;GOVERNANCE.mdthree-version model (milestone vs. layer vs. document-format).extensions/exchange.md+extensions/registry.mdconverted to promoted-pointer stubs (repo-root and website mirrors), keeping the dual-surface invariant.Test Plan
cd eval && npx vitest run→ 289 passed (36 new: 19 exchange + 17 registry), zero regressions.cd website && npm run build→ 41 static pages, types valid, new spec/security pages wired into the sidebar.Notes
harness.yamlschema change;version: "1"and the v1$idare untouched.website/public/schema/v2/mirrors are intentionally not populated yet — that happens at release, not in draft.