Shared contracts
spark-contracts (folder spark_contracts) is a small TypeScript package that every service builds against. It holds types and constants only, plus pure helpers. It never talks to a network or a database.
What it contains
| Module | Contents |
|---|---|
legacy | The original shared types, kept unchanged for older services. |
topics | The Kafka topic catalogue: every topic name as a constant, grouped by family. |
envelope | The Kafka header envelope: event id, occurred-at, organization, producer, schema. |
control-plane | Actors (ActorRef, ActorKind), autonomy levels, authorize requests and answers. |
hashing | canonicalJson() and hashCanonical(): stable JSON (sorted keys, safe integers only) and its sha256:v1: hash, used to bind approvals to exact content. |
mail, flows | Event payload types for mail and flows. |
launch | Launch vocabulary (platforms, statuses, methods, stages), platform snapshot types and the ReadinessSummary. |
strategy | Strategy steps, Sourced<T> provenance, version statuses, goal units, funnel stages, KPI metrics and KPI snapshot types. |
How services use it
- Each service depends on it as a local package (
"spark-contracts": "file:../spark_contracts") and imports from the package root. - Services import the built output, so the package is built before services that use a new version.
- Changes are additive: add new types, constants and topics; do not rename or remove what a running service still uses. The version number moves with each addition (launch contracts arrived in 2.4, strategy contracts in 2.5).
Rules
- Numbers that go into a hash must be safe integers. Represent money in whole units or minor units, percentages as integers, ratings in tenths.
- A value that one service produces and another consumes belongs here, not in either service.
- Keep the package free of runtime dependencies.