conceptualv0.1 · skeleton docs
Versioning
How hooks, the HookCall schema and the SDK change without breaking callers.
Three things are versioned
| Thing | Where | Breaking change means |
|---|---|---|
| Hook interface | Major version in the ID (.v1) | New hook ID |
| Hook implementation | Semver in the registry (1.2.0) | Never breaking; minor/patch only |
| HookCall / HookReceipt schema | version field in each message | Gateway supports old + new during a window |
| SDK | npm semver | Major bump |
Hook IDs are promises
imd.research.v1 will always accept the v1 input schema and return the v1 output schema. When IMD needs a different shape, it registers imd.research.v2. v1 keeps working until it is deprecated, and even then historical executions stay resolvable.
What may change under v1:
- bug fixes and gas improvements in the adapter;
- new optional input fields that default to the old behaviour;
- new output fields appended at the end.
What may not:
- removing or renaming fields or actions;
- changing the meaning or units of a field;
- tightening validation so previously valid calls fail.
Schema versions
The gateway rejects messages with a version it doesn't support. When a new schema version ships, the gateway accepts both old and new for a published window before dropping the old one. The window length is in the upgrade policy.
Pin what you depend on
// Pin the hook major in code. Never construct hook IDs dynamically from user input.
const HOOK = "imd.research.v1" as const;