Relay / THS seam
Build on Relay.
relay-platform serves compiled runbooks over /api/**. Three seams connect it to the technician-facing runtime. Status below is honest: two are live on reads, one is a contract spike.
Schema version
X-Relay-Schema-Version
Semver wire version on every /api/** response. Clients negotiate compatibility before parsing.
✓ live on reads
Snapshot hash + ETag
ETag / If-None-Match
Deterministic content hash per compiled service and atom; a conditional GET returns 304 when unchanged.
✓ live on reads
Evidence ingestion
POST /api/evidence
Idempotent batched evidence with per-event partial failure. In-memory contract today; durable backend planned.
contract spike
Ref namespaces · src/lib/loader.ts:refToPath()
| Prefix | Resolves to | Used by |
|---|---|---|
| template:<slug> | data/templates/<slug>.yaml | catalog entry points |
| atom:<slug> | walks ATOM_DRAWERS for slug | compose[].atom, safety_ref, post_ref |
| vehicle:<path> | data/vehicles/<path>.yaml | Branch fragments (-remove / -install) |
| brake-type:<slug> | data/brake-types/<slug>.yaml | Branch.brake_refs, BranchRef.ref |
| glossary:<path> | data/glossary/<topic>/<term>.yaml | term cross-links |
| source:<path> | data/sources/<path>.yaml | sources_ref (sign-off gated) |
| workshop:<path> | data/workshops/<path>.yaml | instructor session plans |
Example request
# Fetch a compiled runbook as JSON GET /api/services/brake-pad-swap HTTP/1.1 Host: relay-platform.mmeg.us Accept: application/json # Response headers X-Relay-Schema-Version: 0.8.0 ETag: "sha256:…" Content-Type: application/json
VersionsSCHEMA_VERSION 0.8.0 is the wire version negotiated over HTTP. It is not the npm package version (0.3.1). Pin against the wire version, never the package version.