Skip to content

Commit 5d67d0f

Browse files
hyperpolymathclaude
andcommitted
feat: add Groove Protocol standard — universal plug-and-play composition
Groove Protocol specification for type-safe, zero-config system composition: spec/SPEC.adoc — Full protocol specification covering: - Discovery (local port probing + distributed mDNS/BEAM) - Capability negotiation (structural matching, SemVer versioning) - Idris2 dependent type proofs (match safety, linear handles, capability authenticity, composition soundness) - Connection lifecycle (states, heartbeat, graceful degradation) - Attestation (VeriSimDB provenance hash-chains) - Groove Mesh (transitive composition with type-safety proofs) - Groove Bridge (legacy adaptation, BoJ as reference) - Security (mTLS, capability requirements, blocklists) spec/CONFORMANCE.adoc — Four conformance levels: Level 1 Groove-Aware, Level 2 Connected, Level 3 Proven, Level 4 Native spec/MODULARITY.adoc — Module architecture following ABI/FFI/API triple: Idris2 ABI → Zig FFI → V API. Dependency graph, user journeys, stripping-back guide. Each module is self-contained. docs/POSITIONING.adoc — Market positioning strategy: Five audience channels, phased rollout, one-line pitches per audience. "Groove occupies unclaimed space — it doesn't compete with anything." harness/groove-harness.js — Universal Groove Harness: Copy-paste boilerplate that handles discovery, connection lifecycle, heartbeat, FLI provisioning, and attestation. Panel authors only write their capabilities, UI, and handlers. harness/groove-panel-template/ — Mintable panel template: Three-step panel creation (declare capabilities, write handlers, write UI). Everything else is automatic. examples/ — Burble manifest (full) and minimal manifest Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent ac5794b commit 5d67d0f

13 files changed

Lines changed: 2167 additions & 279 deletions

File tree

.tool-versions

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,5 +5,3 @@
55
# Primary runtime
66
deno 2.1.4
77

8-
# Build tools
9-
just 1.36.0

Justfile

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,6 @@ lint:
2626
clean:
2727
@echo "Clean not configured yet"
2828

29-
# [AUTO-GENERATED] Multi-arch / RISC-V target
30-
build-riscv:
31-
@echo "Building for RISC-V..."
32-
cross build --target riscv64gc-unknown-linux-gnu
33-
3429
# Run panic-attacker pre-commit scan
3530
assail:
3631
@command -v panic-attack >/dev/null 2>&1 && panic-attack assail . || echo "panic-attack not found — install from https://github.com/hyperpolymath/panic-attacker"

consent-aware-http/justfile

Lines changed: 0 additions & 270 deletions
This file was deleted.

groove-protocol/README.adoc

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell
3+
= Groove Protocol
4+
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
5+
:toc: left
6+
:toclevels: 3
7+
:icons: font
8+
:source-highlighter: rouge
9+
10+
== What Is Groove?
11+
12+
Groove is a protocol where independent systems discover each other at runtime,
13+
negotiate capabilities through type-safe interfaces, and compose — or don't —
14+
without either side needing configuration or the other to function.
15+
16+
A groove is the shape cut into the surface of a system. It is passive until
17+
engaged. It guides without constraining. Fit is structural, not negotiated —
18+
the Idris2 dependent types make compatibility a compile-time property, not a
19+
runtime handshake that might fail.
20+
21+
== Quick Example
22+
23+
Start two groove-aware systems:
24+
25+
[source,bash]
26+
----
27+
# Terminal 1: start Burble (voice/text comms)
28+
burble start --port 6473
29+
30+
# Terminal 2: start Gossamer (desktop app shell)
31+
gossamer start --port 6470
32+
----
33+
34+
Gossamer probes nearby ports. Port 6473 responds with Burble's capability
35+
manifest. Burble offers `voice`, `text`, `presence`, `spatial-audio`, `tts`,
36+
`stt`. Gossamer consumes `voice` and `text`. Types match. Voice UI appears in
37+
Gossamer. No configuration was written. No plugin was installed.
38+
39+
Stop Burble. Gossamer keeps working — voice UI disappears gracefully.
40+
41+
== Design Principles
42+
43+
. **Bare by default** — every system works alone, unplugged
44+
. **Structural fit** — compatibility is a type property, not a config option
45+
. **Zero configuration** — start services, they find each other
46+
. **Graceful degradation** — losing a groove partner is not an error
47+
. **Linear safety** — connection handles are consumed exactly once
48+
. **Provenance** — every groove connection is attestable
49+
50+
== Specification
51+
52+
See link:spec/SPEC.adoc[SPEC.adoc] for the full protocol specification.
53+
54+
== Status
55+
56+
[cols="1,3"]
57+
|===
58+
| Stage | Working Draft
59+
| Version | 0.1.0
60+
| Media Type | `application/groove+a2ml` (registration pending)
61+
| Reference Impl | Burble, Gossamer, VeriSimDB, Vext
62+
| Formal Proofs | Idris2 ABI in `src/abi/`
63+
|===
64+
65+
== Related Standards
66+
67+
- link:../a2ml/[A2ML] — capability manifests are encoded in A2ML
68+
- link:../axel-protocol/[Axel Protocol] — age-gating can groove with content systems
69+
- https://github.com/hyperpolymath/burble[Burble] — reference groove provider (voice/text)
70+
- https://github.com/hyperpolymath/gossamer[Gossamer] — reference groove consumer (desktop shell)
71+
72+
== License
73+
74+
PMPL-1.0-or-later

0 commit comments

Comments
 (0)