midi-backplane.git · README.md

revision adaeb52b3376b37071a3df72edbe13d7ff794b78 · complete file
# MIDI Backplane

A clean home for the MIDI 2.0 pub/sub backplane and WebGPU bindings. This repository owns the MIDI-native IDL (topics, envelopes, QoS, capabilities), the schema-to-facts generator, shared runtime bindings (`midi2.js`/`midi2.swift` extensions), and conformance suites. Application code, prompts, and facts instances live elsewhere (e.g., FountainKit); this repo publishes the contract and the tooling that enforces it.

## Contents
- `schema/`: MIDI IDL (versioned contract for topics, envelopes, QoS, errors, capability masks, timing budgets, chunking)
- `tools/`: schema linting and `midi-schema-to-facts` generator
- `runtimes/`: shared backplane bindings for JS/Swift with WebGPU helpers
- `conformance/`: protocol fixtures, jitter/latency benches, GPU correctness tests
- `docs/`: narrative specs, envelope/QoS definitions, governance and release notes

## Tooling
- `npm run lint:idl` → validate `schema/idl.yaml`
- `npm run facts` → emit facts JSON from `schema/idl.yaml` (use `--out` to write a file)
- `npm test` → conformance smoke against `conformance/fixtures/valid-gpu-dispatch.json`

## CI
- GitHub Actions runs `npm ci`, `npm run lint:idl`, a facts smoke (`npm run facts -- --out /tmp/facts.json`), and the conformance smoke (`npm test`) on pushes and PRs.

## Runtime (JS scaffold)
- Exported at `midi-backplane/runtime`: `loadIdlFromFile`, `normalizeIdl`, `hasCapabilities`, `validateEnvelope`, `checkBudgets`, `telemetryFromViolations`, `evaluate`.

## Runtime (Swift scaffold)
- SwiftPM package at `runtimes/swift` (depends on Yams).
- `loadIDL(fromPath:)` parses `schema/idl.yaml` and validates QoS/capabilities/topics into a typed `IDL` model.
- `validateEnvelope(idl:envelope:nowNs:)` checks topic/QoS/capabilities, resume token, and TTL; `checkBudgets` enforces latency/jitter/payload budgets; `evaluate` wraps validation + budgets and emits telemetry. Unit tests live under `runtimes/swift/Tests`.

## Boundaries
- In this repo: contract, generators, runtimes, conformance, telemetry spec.
- Not in this repo: app code, prompts, facts instances, or store seeders; those stay in consuming workspaces.
- Compatibility bridges (HTTP↔MIDI) belong in consumers, not here.

## Next steps
1) Finalize the IDL scaffold (envelope/QoS/capability/error model, base topics) under `schema/`.
2) Ship `midi-schema-to-facts` and schema linting in `tools/`.
3) Publish JS/Swift runtime bindings that load the IDL, enforce envelopes/budgets/chunks, and expose WebGPU helpers for `gpu/*` topics.
4) Add conformance fixtures for envelope correctness, chunking (including retransmit/overlap), timing/jitter budgets, and GPU dispatch correctness.