midi2-gpu-fabric.git · README.md

revision 48801c746d2563a3bd1c97f8671a5a832ae0cc82 · complete file
# MIDI2 GPU Fabric

Greenfield workspace for a MIDI 2.0 + GPU ecosystem. The MIDI IDL (via `@fountain-coach/midi-backplane`) is the single source of truth. No OpenAPI. Facts and telemetry are seeded into FountainStore; runtime loops (JS/Swift) enforce envelopes, budgets, and chunk rules and emit telemetry.

## Contents
- `schema/`: pinned IDL + telemetry schemas (copied from midi-backplane releases for reference)
- `seed/`: FountainStore seeder (Swift) that runs midi-schema-to-facts
- `apps/js-sample/`: JS sample using runtime loop with a stub transport
- `apps/swift-sample/`: Swift sample host using RuntimeLoop
- `apps/stage-native/`: macOS Stage Native world (Metal + Bullet) with screenplay editor + in-app assistant (Ollama/OpenAI) for chat control
- `apps/teatro-stage-web/`: reference web client for the `stage/*` instrument topics
- `tests/`: integration tests (Node + Swift) and conformance runner wiring
- `ci/`: GitHub Actions (lint, facts, conformance, JS/Swift tests)

## Contract
- Contract source: `@fountain-coach/midi-backplane@1.0.0` (IDL + telemetry)
- Facts derived from the MIDI IDL only (no OpenAPI). Facts stored in FountainStore.
- Telemetry per `schema/telemetry.yaml` (errors, jitter, resource).

## Commands
- `npm run lint:idl` (delegates to midi-backplane lint on the pinned IDL copy)
- `npm run facts` (generate `schema/facts.json` via midi-backplane)
- `npm test` (JS integration)
- `swift test` (Swift integration)
- `npm run seed` (run FountainStore seeder via Swift binary)
- CI: GitHub Actions runs lint/facts (and checks facts are committed), JS tests, and Swift tests for instrument + seed.

## Transport
- JS: use `createRuntimeLoop` and implement `transport.emit(payload)` to forward telemetry/logging.
- Swift: implement `TransportEmitter` and wire `RuntimeLoop`.

## Notes
- OpenAPI is not used. All surfaces derive from the MIDI IDL.
- Conformance integrates midi-backplane fixtures (chunk/resume/budget/telemetry/GPU).
- FountainStore dependencies are now private (`Fountain-Coach/Fountain-Store`, `Fountain-Coach/swift-secretstore`), so SwiftPM requires GitHub auth (SSH or `gh auth login`). For CI, use a PAT or `GITHUB_TOKEN` with access and configure `git` to use it.

## Docs
- `docs/publication-policy.md` — the public/private boundary for Book projections and runtime source.
- `docs/midi-backplane.md` — IDL contract, telemetry, and the FountainStore topic extensions.
- `docs/fountainstore-instrument.md` — MIDI-native FountainStore handler surface.
- `docs/ollama-driver.md` — LLM tool driver and eval harness, persona/topic gating.
- `docs/instrument-template.md` — checklist and stubs for adding a new instrument namespace.
- `.codex/skills/fountain-coach-instrument-creation/SKILL.md` — generic scenario-first workflow for creating, verifying, admitting, releasing, integrating, and publishing bounded FCIS-KIT instruments.
- `docs/stage-native-chat.md` — how Stage Native chat control works (Ollama → backplane tools → world).
- `docs/modernization-studio-pipeline.md` — Modernization Studio purpose, architecture, and full processing pipeline.
- `docs/modernization-studio-operator-playbook.md` — command-first runbooks for power users operating Modernization Studio.

## Quick tour (city map metaphor)
- Map: `schema/idl.yaml` lists every street/topic and its rules (QoS, budgets, fields).
- Offices: handlers (e.g., FountainStore instrument on `fountainstore/*`) live on those streets.
- Badges: roles in `roles:<corpusId>` decide which personas can use which streets/offices.
- Dispatcher: Ollama driver asks the LLM for a route plan (JSON), checks map + badge, then executes via the instrument; eval mode drives test routes for each badge.

## Add a new instrument (checklist)
- Define topics in `schema/idl.yaml` (with qos/budget/required fields).
- Implement a handler for the new topic namespace (mirroring `FountainStoreInstrument`).
- Add topics to roles in `roles:<corpusId>` so the LLM can see/use them.
- Run `npm run lint:idl`, `npm run facts` (and reseed), then `OLLAMA_EVAL=1 Scripts/ollama-smoke` to validate persona/topic behavior.