Skip to content

feat: start v2 milestone — Exchange (HEP-7) and Registry (HEP-8) layers#18

Merged
siracusa5 merged 2 commits into
mainfrom
c/loving-curie-2e1e65
Jun 6, 2026
Merged

feat: start v2 milestone — Exchange (HEP-7) and Registry (HEP-8) layers#18
siracusa5 merged 2 commits into
mainfrom
c/loving-curie-2e1e65

Conversation

@siracusa5

Copy link
Copy Markdown
Collaborator

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 breakharness.yaml version stays "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/ $id namespace.

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, oneOf plaintext/encrypted).
  • protocol/exchange.md (+ docs mirror), examples/exchange/ (plaintext + encrypted), security/exchange.md (+ mirror), terminology, and eval/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), and eval/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 by integrity.md) as deliberately orthogonal primitives; registry-index signing deferred to v3.
  • eval/src/lib/schema.ts — adds validateExchange / validateRegistry loaders.
  • Framing: README / protocol/overview.md / getting-started layer tables → "draft (HEP-7/8)"; CHANGELOG.md [Unreleased] — v2; GOVERNANCE.md three-version model (milestone vs. layer vs. document-format).
  • extensions/exchange.md + extensions/registry.md converted to promoted-pointer stubs (repo-root and website mirrors), keeping the dual-surface invariant.

Test Plan

  • Local tests pass — cd eval && npx vitest run289 passed (36 new: 19 exchange + 17 registry), zero regressions.
  • Both new schemas compile against JSON Schema 2020-12; all 6 example documents validate against them.
  • Docs site builds — cd website && npm run build → 41 static pages, types valid, new spec/security pages wired into the sidebar.
  • CI checks pass.

Notes

@siracusa5 siracusa5 added documentation Improvements or additions to documentation enhancement New feature or request labels Jun 5, 2026
siracusa5 and others added 2 commits June 6, 2026 15:06
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>
@siracusa5 siracusa5 force-pushed the c/loving-curie-2e1e65 branch from b6ffb89 to 53fd8cb Compare June 6, 2026 19:06
@siracusa5 siracusa5 merged commit 913f04f into main Jun 6, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant