tech(hooks): add version compatibility checks and runtime helpers#39
tech(hooks): add version compatibility checks and runtime helpers#39
Conversation
Add checkHookContractVersion() and parseHookContextSafe() utilities so hook authors can validate contract versions at runtime with structured results (compatible / newer_minor / unsupported). Codify the full evolution rules (additive vs breaking changes) in the HOOK_CONTRACT_VERSION JSDoc and export HOOK_CONTRACT_VERSION_MIN. Add 54 smoke tests covering: - Version range checks (exact, future, old, fractional, NaN) - Safe context parsing with version validation - Additive field tolerance (unknown keys survive parsing) - task_failed status semantics - Hook-contract.md and README drift guards Update hook-contract.md with runtime helper docs and improved version check examples that distinguish newer_minor from unsupported. Closes SYM-44
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 12b9bae797
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (version > HOOK_CONTRACT_VERSION) { | ||
| return { | ||
| status: "newer_minor", | ||
| requestedVersion: version, |
There was a problem hiding this comment.
The new compatibility helper treats any version > HOOK_CONTRACT_VERSION as newer_minor, but this repo’s policy states that additive changes do not bump the version and only breaking changes do. In that model, a higher version means the payload may be incompatible, so returning non-fatal status will let hooks continue parsing potentially broken shapes instead of failing fast. This is especially risky because parseHookContextSafe now depends on this check and will accept those future versions as success.
Useful? React with 👍 / 👎.
1 participant
Summary
Add runtime version compatibility infrastructure for the hook contract, fulfilling all acceptance criteria from SYM-44.
Changes
extensions/teams/hooks.tsHOOK_CONTRACT_VERSION_MIN— new constant defining the minimum supported versioncheckHookContractVersion(version)— structured version check returningcompatible/newer_minor/unsupportedwith descriptive messagesparseHookContextSafe(json)— combines JSON parse + version validation; recommended entry point for hook scriptsHookVersionCheckResulttype — structured return for version checksHOOK_CONTRACT_VERSIONJSDoc to codify the full evolution rules (additive vs breaking) directly in codescripts/smoke-test.mts54 new tests covering:
MIN <= CURRENT, both integers ≥ 1)checkHookContractVersionfor exact match, future, far-future, zero, negative, fractional, NaNparseHookContextSafefor valid v1, additive fields (future v2), version 0, invalid JSON, missing version, non-object, string versiontask_failedpayload semantics (status = "pending")checkHookContractVersion+parseHookContextSafe;hook-contract.mddocuments version helpers andnewer_minorstatusdocs/hook-contract.mdnewer_minor(warn, proceed) fromunsupported(exit)checkHookContractVersionandparseHookContextSafewith usage examplesREADME.mdcheckHookContractVersionandparseHookContextSafeAcceptance Criteria
Closes SYM-44