midi-backplane.git · README.md

revision 2f9b780cd64f26e404583733cdac592447aa238e · 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`), conformance (`npm test`), JS handler tests (`npm run test:js`), and Swift tests on pushes and PRs.

## Runtime (JS scaffold)
- Exported at `midi-backplane/runtime`: `loadIdlFromFile`, `normalizeIdl`, `hasCapabilities`, `validateEnvelope`, `checkBudgets`, `telemetryFromViolations`, `evaluate`, `ChunkTracker`, `createRuntimeLoop`.
- Runtime loop expects a `transport.emit(payload)` to forward telemetry (errors, jitter, resource).

## 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`.
- `RuntimeLoop` scaffold wires `MessageHandler` with jitter/resource hooks to a `TransportEmitter`.

## 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.

## Release status
- Package version: 1.0.0 (npm scope `@fountain-coach/midi-backplane`); Swift library exposed via SwiftPM.
- Tests to keep green: `npm run lint:idl`, `npm run facts`, `npm test`, `npm run test:js`, `swift test`.