midi-backplane.git · README.md

revision 25e5ac3b9169856258ac030ef0ba9131c347defe · 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
Operational command recipes live in `.codex/skills/repo-tooling/SKILL.md`.

## CI
GitHub Actions runs the repo tooling checks (IDL lint, facts generation, conformance, JS tests) plus Swift tests on pushes and PRs. See `.codex/skills/repo-tooling/SKILL.md` for the command list.

## 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: see `.codex/skills/repo-tooling/SKILL.md`.