Platform Contract
The Meridian Platform Contract is the open protocol every Merkava Drive speaks. HMAC-signed, event-driven, versioned.
What it is
The Platform Contract defines how Merkava Core talks to Drives — first-party and third-party alike. Every Drive announces a manifest; every event is signed; every response is typed. The same protocol third-party authors will use when the Garage opens is the protocol we use in-house today.
A published spec doc is on the roadmap. The version running in production today is v1.
Shape, in brief
- Manifest. Each Drive publishes a JSON manifest describing its capabilities and events.
- HMAC signing. Every event between Core and a Drive is HMAC-signed with a per-tenant secret.
- Event schema. Typed events — not arbitrary payloads.
- Backward compat. Deprecations ship with a full version before removal.
Platform Contract — questions, plainly answered.
What is the Meridian Platform Contract?
An open, HMAC-signed, event-driven protocol that every Merkava Drive — first-party and third-party — speaks. It defines the manifest format, signing keys, event schemas, and error contracts. The version running in production today is v1; deprecations ship with a full prior version before removal.
Why HMAC instead of OAuth or JWT?
HMAC gives every event between Core and a Drive a verifiable shared-secret signature, scoped per-tenant. OAuth solves user-authorization (which we use for integrations like GitHub, Stripe, Slack); JWT solves session bearer tokens. Drive-to-Core traffic is server-to-server with rotating per-tenant secrets — HMAC fits the threat model exactly without bringing in a token-issuance service.
How does a Drive announce itself to Merkava Core?
Each Drive publishes a JSON manifest (drive.manifest.json) describing its capabilities, events emitted, events consumed, required scopes, and pricing tier. Core reads the manifest at install time, presents the operator with the scope-approval screen, and registers the Drive's HMAC signing key. See /resources/drive-manifest for the full schema.
Are Drive events arbitrary JSON payloads?
No. Every event is typed — defined in the Drive's manifest with required and optional fields. Core validates events against the manifest's schema before delivering them. Arbitrary payloads make the system fragile; typed events make Drive-to-Drive composition possible without webhooks or third-party glue.
What about backward compatibility when the protocol changes?
Deprecations ship with a full version before removal. v1 will keep working when v2 lands; Drives written against v1 don't break the day v2 ships. Breaking changes are announced on /resources/changelog and the developer mailing list with a runway, not a flag day.
Can third-party developers build Drives today?
The Garage marketplace API is on the public roadmap (Later tier). The Platform Contract spec is published; SDK + docs + signing test vectors are next. If you want to start building, email [email protected] — we're prioritizing the SDK based on developer interest.
Are first-party Drives held to this same contract?
Yes. First-party Drives speak the same protocol as third-party will. No private API for our own Drives. This keeps the contract honest — if it works for Beacon, Quillsly, and Centerline, it works for any third-party Drive built against the same spec.
How are signing keys rotated?
Per-tenant rotation via Settings → Drives → [Drive name] → Rotate signing key. Old key remains valid for a 24-hour overlap window during which both signatures are accepted; after the window, only the new key is honored. Operators can rotate at will; Drives must handle the overlap window cleanly (the SDK does this automatically).