@@ -156,18 +156,60 @@ export const MESHERY_EXTENSION_EVENT_TYPES = Object.values(
156156 MESHERY_EXTENSION_EVENT
157157) as readonly MesheryExtensionEventType [ ] ;
158158
159+ const isRecord = ( value : unknown ) : value is Record < string , unknown > =>
160+ typeof value === 'object' && value !== null ;
161+
162+ const isString = ( value : unknown ) : value is string => typeof value === 'string' ;
163+
164+ const isStringArray = ( value : unknown ) : value is string [ ] =>
165+ Array . isArray ( value ) && value . every ( isString ) ;
166+
159167/**
160- * Narrows an event received from the bus to a known contract member.
168+ * Payload check per event literal, keyed by the literal itself.
169+ *
170+ * The type discriminant alone is not the contract - the payload shape is half of
171+ * it. A host that renames `designId` to `id` keeps publishing a literal this
172+ * build recognises while every subscriber reads `undefined`, which is the same
173+ * silent no-op the literal map exists to prevent. Checking only required fields
174+ * (never rejecting extra ones) keeps additive payload changes compatible while
175+ * making a rename or removal visible.
176+ *
177+ * `satisfies Record<MesheryExtensionEventType, ...>` is the completeness guard:
178+ * adding a member to `MesheryExtensionEvent` without a check here fails to
179+ * compile, so this table cannot drift behind the union.
180+ */
181+ const MESHERY_EXTENSION_EVENT_DATA_CHECKS = {
182+ K8S_CONTEXTS_UPDATED : data => isStringArray ( data . selectedK8sContexts ) ,
183+ OPEN_VIEW_SCOPED_TO_DESIGN : data => isString ( data . designId ) && isString ( data . designName ) ,
184+ OPEN_DESIGN_IN_EXTENSION : data => isString ( data . designId ) && isString ( data . designName ) ,
185+ OPEN_VIEW_IN_EXTENSION : data => isString ( data . viewId ) && isString ( data . viewName ) ,
186+ MERGE_DESIGN : data => isString ( data . id ) && isString ( data . name ) ,
187+ DISPATCH_TO_MESHERY_STORE : data =>
188+ isString ( data . type ) && ( data . payload === undefined || isRecord ( data . payload ) ) ,
189+ FeatureRequiresUserAccount : data => isString ( data . feature ) ,
190+ MISSING_PERMISSION : data => isString ( data . keyId ) ,
191+ MISSING_CAPABILITY : data => isString ( data . capabilityId )
192+ } as const satisfies Record < MesheryExtensionEventType , ( data : Record < string , unknown > ) => boolean > ;
193+
194+ /**
195+ * Narrows an event received from the bus to a known contract member, checking
196+ * both the type discriminant and the payload it promises to carry.
161197 *
162198 * Subscribers must treat a `false` result as a defect to report, not as something
163- * to ignore: it means the publisher is emitting a literal this build has never
164- * heard of, which is exactly the host/extension skew that used to present as a
165- * silently dead feature.
199+ * to ignore. It means the publisher is emitting either a literal this build has
200+ * never heard of or a payload this build cannot read - both are the host/extension
201+ * skew that used to present as a silently dead feature, and both call for the same
202+ * response: say so loudly rather than no-op.
166203 */
167- export const isMesheryExtensionEvent = ( event : unknown ) : event is MesheryExtensionEvent =>
168- typeof event === 'object' &&
169- event !== null &&
170- MESHERY_EXTENSION_EVENT_TYPES . includes ( ( event as { type : MesheryExtensionEventType } ) . type ) ;
204+ export const isMesheryExtensionEvent = ( event : unknown ) : event is MesheryExtensionEvent => {
205+ if ( ! isRecord ( event ) ) return false ;
206+ const type = event . type as MesheryExtensionEventType ;
207+ // Membership is checked against the literal array before indexing the check
208+ // table, so a payload carrying `type: 'toString'` cannot reach an inherited
209+ // Object.prototype member and be mistaken for a validator.
210+ if ( ! MESHERY_EXTENSION_EVENT_TYPES . includes ( type ) ) return false ;
211+ return isRecord ( event . data ) && MESHERY_EXTENSION_EVENT_DATA_CHECKS [ type ] ( event . data ) ;
212+ } ;
171213
172214/* -------------------------------------------------------------------------- */
173215/* Injected capabilities */
@@ -249,6 +291,18 @@ export const MESHERY_EXTENSION_HANDSHAKE_FIELDS = ['contractVersion'] as const;
249291
250292/** Outcome of comparing a host's `injectProps` against the declared contract. */
251293export type InjectedCapabilityReport = {
294+ /**
295+ * Set when the host advertised a `contractVersion` differing from the one this
296+ * build declares, which means a rename or removal happened on one side. `host`
297+ * is typed `unknown` because it is untrusted input: a host may advertise
298+ * anything, and anything that is not this build's version is a mismatch.
299+ *
300+ * `null` also covers a host that advertises nothing at all - every host
301+ * deployed before the handshake existed. Those predate the field rather than
302+ * disagreeing about it, so they are reported as the supported legacy case
303+ * instead of drowning the report in mismatches the operator cannot act on.
304+ */
305+ contractVersionMismatch : { host : unknown ; extension : number } | null ;
252306 /** Contract keys the host did not provide. Each one is a dead feature. */
253307 missing : MesheryExtensionCapability [ ] ;
254308 /** Contract hook keys absent from `injectProps.hooks`. */
@@ -283,7 +337,13 @@ export const reportInjectedCapabilities = (
283337 ...Object . keys ( MESHERY_EXTENSION_DEPRECATED_CAPABILITIES )
284338 ] ) ;
285339
340+ const advertisedVersion = provided . contractVersion ;
341+
286342 return {
343+ contractVersionMismatch :
344+ advertisedVersion === undefined || advertisedVersion === MESHERY_EXTENSION_CONTRACT_VERSION
345+ ? null
346+ : { host : advertisedVersion , extension : MESHERY_EXTENSION_CONTRACT_VERSION } ,
287347 missing : MESHERY_EXTENSION_CAPABILITIES . filter ( key => provided [ key ] === undefined ) ,
288348 // `hooks` itself being absent is already reported as a missing capability;
289349 // reporting all three hooks again would be noise, so only look inside when
@@ -300,12 +360,15 @@ export const reportInjectedCapabilities = (
300360} ;
301361
302362/**
303- * True when the host satisfied every declared capability. Deprecated and
304- * unrecognized keys are informational and do not fail the check — only an
305- * outright missing capability is a broken contract.
363+ * True when the host advertised a compatible contract version and satisfied every
364+ * declared capability. Deprecated and unrecognized keys are informational and do
365+ * not fail the check - only an outright missing capability, a missing hook, or a
366+ * version disagreement is a broken contract.
306367 */
307368export const isInjectedCapabilityReportSatisfied = ( report : InjectedCapabilityReport ) : boolean =>
308- report . missing . length === 0 && report . missingHooks . length === 0 ;
369+ report . contractVersionMismatch === null &&
370+ report . missing . length === 0 &&
371+ report . missingHooks . length === 0 ;
309372
310373/**
311374 * Renders a report as a single actionable message naming the offending keys.
@@ -317,15 +380,22 @@ export const describeInjectedCapabilityReport = (
317380 if ( isInjectedCapabilityReportSatisfied ( report ) ) return null ;
318381
319382 const parts : string [ ] = [ ] ;
383+ if ( report . contractVersionMismatch !== null ) {
384+ const { host, extension } = report . contractVersionMismatch ;
385+ parts . push (
386+ `host advertises contract v${ String ( host ) } , this build declares v${ extension } ` +
387+ ' (a rename or removal happened on one side)'
388+ ) ;
389+ }
320390 if ( report . missing . length > 0 ) {
321391 parts . push ( `missing capabilities: ${ report . missing . join ( ', ' ) } ` ) ;
322392 }
323393 if ( report . missingHooks . length > 0 ) {
324394 parts . push ( `missing hooks: ${ report . missingHooks . join ( ', ' ) } ` ) ;
325395 }
326396 return (
327- `Meshery host did not satisfy the extension contract (v${ MESHERY_EXTENSION_CONTRACT_VERSION } ) — ` +
328- `${ parts . join ( '; ' ) } . The host and this extension bundle were built against ` +
329- 'different contract versions; features depending on these keys will not work.'
397+ `Meshery host did not satisfy the extension contract (v${ MESHERY_EXTENSION_CONTRACT_VERSION } ): ` +
398+ `${ parts . join ( '; ' ) } . Host and extension bundle were built against different ` +
399+ 'contract revisions; the features these keys back will not work.'
330400 ) ;
331401} ;
0 commit comments