fix(metadata,client): subscribeMetadata delivers true MetadataEvents — producer fulfils the declared contract (#4602) (#4628)

MetadataManager now builds a schema-valid MetadataEvent (generated uuid id,
flattened top-level metadataType/name/definition, userId when the write
declares an actor via the new MetadataWriteOptions.userId seam), validates it
with MetadataEventSchema.parse before publishing, and carries it as the
RealtimeEventPayload envelope's payload. A register() overwrite now publishes
metadata.{type}.updated (mirroring the added/changed watcher split) instead of
a second .created. Types outside the closed MetadataEventType enum publish
nothing (declared = enforced) instead of an event every compliant consumer
must reject.

The client SDK's subscribeMetadata unwraps the envelope and validates with
MetadataEventSchema.safeParse at the boundary — off-contract payloads are
rejected loudly (callback never invoked), and the 'as any as MetadataEvent'
double-cast is deleted. client-react's metadata hooks delegate to it and are
fixed transitively.

Out-of-scope findings filed: #4626 (subscribeData/DataEvent twin defect),
#4627 (MetadataEventType enum coverage vs registrable types).


Claude-Session: https://claude.ai/code/session_012C2cd7tL8QDoZ2QKN3djJ5

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/metadata-event-contract.md

@@ -0,0 +1,46 @@
+---
+"@objectstack/metadata": patch
+"@objectstack/client": patch
+"@objectstack/spec": minor
+---
+
+fix(metadata,client): `subscribeMetadata` callbacks receive real `MetadataEvent`s — the producer now fulfils the declared contract (#4602)
+
+`@objectstack/spec/api`'s `MetadataEvent` declares top-level `id` (uuid,
+required), `metadataType`, `name`, `definition?`, `userId?` — and after
+#4587's convergence it is the **only** declared contract for realtime
+metadata-change events. But the producer (`MetadataManager`) published a raw
+`RealtimeEventPayload` envelope with everything nested under `payload` and no
+`id`/`userId`, while the client SDK force-cast that envelope into the callback
+(`callback(event as any as MetadataEvent)`). Subscribers who wrote
+`event.name` / `event.metadataType` — exactly what the types promised —
+compiled green and read `undefined` at runtime.
+
+Producer now fulfils the contract:
+
+- `MetadataManager.register()` / `unregister()` build a true `MetadataEvent`
+  (generated uuid `id`, flattened top-level fields, `userId` when the write
+  declares an actor) and validate it with `MetadataEventSchema.parse` before
+  publishing. The transport envelope is unchanged (`RealtimeEventPayload`,
+  with `payload` carrying the complete `MetadataEvent`).
+- A `register()` **overwrite now publishes `metadata.{type}.updated`** instead
+  of a second `.created`, mirroring the existing `added`/`changed` watcher
+  split. Previously `.updated` was declared with no producer at all.
+- `MetadataEventType` is a closed enum: metadata types outside it (e.g.
+  `translation`) have no declared realtime event, so nothing is published for
+  them (debug-logged) instead of emitting an event every schema-compliant
+  consumer must reject.
+
+Consumer validates instead of casting:
+
+- `@objectstack/client`'s `subscribeMetadata` (and therefore
+  `@objectstack/client-react`'s metadata hooks, which delegate to it) unwraps
+  the envelope and runs `MetadataEventSchema.safeParse` at the boundary. An
+  off-contract payload is rejected loudly (handler error, callback never
+  invoked) — never coerced or passed through. The `as any as MetadataEvent`
+  double-cast is gone.
+
+New seam: `MetadataWriteOptions.userId` (`@objectstack/spec/contracts`) lets
+write paths that know the acting user carry it into the published event's
+`userId`. Existing callers are unaffected — the field is optional and absence
+means "no human actor".

packages/client/src/realtime-api.test.ts

@@ -0,0 +1,140 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #4602 — subscribeMetadata delivers TRUE `MetadataEvent`s, validated at the
+ * boundary.
+ *
+ * The callback is typed `(event: MetadataEvent) => void` — top-level `id`
+ * (uuid), `metadataType`, `name`, `definition?`, `userId?`. Before this fix
+ * the handler delivered the raw `RealtimeEventPayload` envelope via
+ * `callback(event as any as MetadataEvent)`, so `event.name` /
+ * `event.metadataType` were `undefined` at runtime while the types said
+ * `string`.
+ *
+ * Pins:
+ *  - the subscriber receives the top-level fields (fails on the pre-fix
+ *    envelope-passthrough);
+ *  - an off-contract payload (e.g. the pre-fix producer's nested shape) is
+ *    rejected LOUDLY — callback never invoked, error surfaced — not passed
+ *    through or coerced.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { RealtimeEventPayload } from '@objectstack/spec/contracts';
+import { RealtimeAPI } from './realtime-api';
+
+const VALID_EVENT = {
+  id: 'a3bb189e-8bf9-4888-9912-ace4e6543002',
+  type: 'metadata.object.created',
+  metadataType: 'object',
+  name: 'account',
+  packageId: 'com.acme.crm',
+  definition: { name: 'account', label: 'Account' },
+  userId: 'usr_123',
+  timestamp: '2026-08-02T12:00:00.000Z',
+} as const;
+
+function envelopeOf(payload: Record<string, unknown>, type = 'metadata.object.created'): RealtimeEventPayload {
+  return {
+    type,
+    object: 'object',
+    payload,
+    timestamp: '2026-08-02T12:00:00.000Z',
+  };
+}
+
+describe('#4602 — RealtimeAPI.subscribeMetadata contract boundary', () => {
+  let api: RealtimeAPI;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    api = new RealtimeAPI('http://localhost:3000');
+  });
+
+  afterEach(() => {
+    api.disconnect();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  function deliver(envelope: RealtimeEventPayload): void {
+    api._bufferEvent(envelope);
+    vi.advanceTimersByTime(2000); // poll interval drains the buffer
+  }
+
+  it('delivers the MetadataEvent with top-level fields to the callback', () => {
+    const seen: unknown[] = [];
+    api.subscribeMetadata('object', (event) => seen.push(event));
+
+    deliver(envelopeOf({ ...VALID_EVENT }));
+
+    expect(seen).toHaveLength(1);
+    const event = seen[0] as typeof VALID_EVENT;
+    // Top-level, as the type declares — NOT nested under `payload`.
+    expect(event.id).toBe(VALID_EVENT.id);
+    expect(event.type).toBe('metadata.object.created');
+    expect(event.metadataType).toBe('object');
+    expect(event.name).toBe('account');
+    expect(event.packageId).toBe('com.acme.crm');
+    expect(event.definition).toEqual({ name: 'account', label: 'Account' });
+    expect(event.userId).toBe('usr_123');
+    expect(event.timestamp).toBe(VALID_EVENT.timestamp);
+  });
+
+  it('rejects the pre-fix producer shape LOUDLY instead of passing it through', () => {
+    // The old MetadataManager payload: no id/type/timestamp inside, fields
+    // that DO exist are fine — but the event as a whole violates the schema.
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const callback = vi.fn();
+    api.subscribeMetadata('object', callback);
+
+    deliver(envelopeOf({
+      metadataType: 'object',
+      name: 'account',
+      definition: { name: 'account' },
+    }));
+
+    expect(callback).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalled();
+    const logged = String(errorSpy.mock.calls.map((c) => c.join(' ')).join('\n'));
+    expect(logged).toContain('realtime event handler');
+  });
+
+  it('rejects a payload with a wrong field type instead of coercing it', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const callback = vi.fn();
+    api.subscribeMetadata('object', callback);
+
+    deliver(envelopeOf({ ...VALID_EVENT, id: 'not-a-uuid' }));
+
+    expect(callback).not.toHaveBeenCalled();
+    expect(errorSpy).toHaveBeenCalled();
+  });
+
+  it('still filters by event type and packageId on the envelope', () => {
+    const callback = vi.fn();
+    api.subscribeMetadata('object', callback, { packageId: 'com.other' });
+
+    // packageId mismatch → filtered out before the boundary parse.
+    deliver(envelopeOf({ ...VALID_EVENT }));
+    expect(callback).not.toHaveBeenCalled();
+
+    // matching packageId → delivered.
+    const matching = { ...VALID_EVENT, packageId: 'com.other' };
+    deliver(envelopeOf(matching));
+    expect(callback).toHaveBeenCalledTimes(1);
+    expect(callback.mock.calls[0][0].packageId).toBe('com.other');
+  });
+
+  it('unsubscribe stops delivery', () => {
+    const callback = vi.fn();
+    const off = api.subscribeMetadata('object', callback);
+
+    deliver(envelopeOf({ ...VALID_EVENT }));
+    expect(callback).toHaveBeenCalledTimes(1);
+
+    off();
+    deliver(envelopeOf({ ...VALID_EVENT }));
+    expect(callback).toHaveBeenCalledTimes(1);
+  });
+});

packages/client/src/realtime-api.ts

@@ -8,7 +8,7 @@
  */
 
 import type { RealtimeEventPayload } from '@objectstack/spec/contracts';
-import type { MetadataEvent, DataEvent } from '@objectstack/spec/api';
+import { MetadataEventSchema, type MetadataEvent, type DataEvent } from '@objectstack/spec/api';
 
 export interface RealtimeSubscriptionFilter {
   /** Metadata/object type filter */
@@ -67,10 +67,23 @@ export class RealtimeAPI {
         ]
       },
       handler: (event) => {
-        // Type guard and filter
-        if (event.type.startsWith('metadata.')) {
-          callback(event as any as MetadataEvent);
+        if (!event.type.startsWith('metadata.')) return;
+        // Contract boundary (#4602): the wire carries a RealtimeEventPayload
+        // envelope whose `payload` is the producer's MetadataEvent. Validate
+        // it here — the callback is typed `(event: MetadataEvent) => void`,
+        // so delivering anything else would be a lie the type system can't
+        // catch. An off-contract payload is rejected LOUDLY (throw → surfaced
+        // by emitEvent's handler-error log), never coerced or passed through:
+        // a malformed event means the producer is broken and must be fixed
+        // there, not tolerated here.
+        const parsed = MetadataEventSchema.safeParse(event.payload);
+        if (!parsed.success) {
+          throw new Error(
+            `subscribeMetadata('${type}'): event '${event.type}' payload does not satisfy ` +
+            `MetadataEventSchema — rejecting off-contract event (fix the producer): ${parsed.error.message}`
+          );
         }
+        callback(parsed.data);
       }
     });
 

packages/metadata/src/metadata-manager.ts

@@ -44,6 +44,11 @@ import type {
 } from '@objectstack/spec/kernel';
 import type { MetadataOverlay } from '@objectstack/spec/kernel';
 import { getMetadataTypeActions } from '@objectstack/spec/kernel';
+import {
+  MetadataEventType,
+  MetadataEventSchema,
+  type MetadataEvent as RealtimeMetadataEvent,
+} from '@objectstack/spec/api';
 import { createLogger, type Logger } from '@objectstack/core';
 import { JSONSerializer } from './serializers/json-serializer.js';
 import { YAMLSerializer } from './serializers/yaml-serializer.js';
@@ -64,6 +69,24 @@ import type {
  */
 export type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
 
+/**
+ * RFC-4122 v4 uuid for realtime `MetadataEvent.id` (#4602).
+ * Prefers `crypto.randomUUID`; the fallback keeps browser-compatible (Pure)
+ * environments without WebCrypto working while still satisfying
+ * `MetadataEventSchema`'s `z.string().uuid()`.
+ */
+function generateEventUuid(): string {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === 'function') {
+    return c.randomUUID();
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (ch) => {
+    const r = (Math.random() * 16) | 0;
+    const v = ch === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
 /**
  * Payload format for cluster-wide metadata change broadcasts.
  *
@@ -260,6 +283,70 @@ export class MetadataManager implements IMetadataService {
     this.logger.info('RealtimeService configured for metadata events');
   }
 
+  /**
+   * Publish a realtime {@link RealtimeMetadataEvent} for a metadata write
+   * (#4602 — contract-first).
+   *
+   * What reaches a `subscribeMetadata` callback must BE the spec's
+   * `MetadataEvent` (`@objectstack/spec/api`): `id` (uuid) at the top level,
+   * flattened `metadataType`/`name`/`definition`, `userId` when the write
+   * carried an actor. The transport keeps its `RealtimeEventPayload`
+   * envelope — `payload` carries the complete `MetadataEvent`, and the client
+   * SDK unwraps + validates it at the boundary.
+   *
+   * Two loud-by-design gates:
+   *  - `MetadataEventType` is a CLOSED enum. A metadata type outside it has
+   *    no declared realtime event contract, so we skip publishing (debug log)
+   *    instead of emitting an event every compliant consumer must reject.
+   *    Declared = enforced; widening coverage means widening the spec enum,
+   *    not producing off-contract events.
+   *  - The event body is `MetadataEventSchema.parse`d before publish, so a
+   *    malformed producer fails here (warn log, event not published) rather
+   *    than delivering a lie downstream.
+   */
+  private async publishRealtimeMetadataEvent(
+    action: 'created' | 'updated' | 'deleted',
+    type: string,
+    name: string,
+    opts: { definition?: unknown; packageId?: unknown; userId?: string } = {},
+  ): Promise<void> {
+    if (!this.realtimeService) return;
+
+    const eventType = `metadata.${type}.${action}`;
+    if (!(MetadataEventType.options as readonly string[]).includes(eventType)) {
+      this.logger.debug(
+        `Metadata type '${type}' has no declared realtime event type (MetadataEventType) — skipping publish`,
+        { eventType, name },
+      );
+      return;
+    }
+
+    try {
+      const event: RealtimeMetadataEvent = MetadataEventSchema.parse({
+        id: generateEventUuid(),
+        type: eventType,
+        metadataType: type,
+        name,
+        ...(typeof opts.packageId === 'string' ? { packageId: opts.packageId } : {}),
+        ...(opts.definition !== undefined ? { definition: opts.definition } : {}),
+        ...(opts.userId ? { userId: opts.userId } : {}),
+        timestamp: new Date().toISOString(),
+      });
+
+      const envelope: RealtimeEventPayload = {
+        type: event.type,
+        object: type,
+        payload: { ...event },
+        timestamp: event.timestamp,
+      };
+
+      await this.realtimeService.publish(envelope);
+      this.logger.debug(`Published ${eventType} event`, { name });
+    } catch (error) {
+      this.logger.warn(`Failed to publish metadata event`, { type, name, error });
+    }
+  }
+
   /**
    * Register a new metadata loader (data source)
    */
@@ -323,27 +410,14 @@ export class MetadataManager implements IMetadataService {
       }
     }
 
-    // Publish metadata.{type}.created event to realtime service
-    if (this.realtimeService) {
-      const event: RealtimeEventPayload = {
-        type: `metadata.${type}.created`,
-        object: type,
-        payload: {
-          metadataType: type,
-          name,
-          definition: data,
-          packageId: (data as any)?.packageId,
-        },
-        timestamp: new Date().toISOString(),
-      };
-
-      try {
-        await this.realtimeService.publish(event);
-        this.logger.debug(`Published metadata.${type}.created event`, { name });
-      } catch (error) {
-        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
-      }
-    }
+    // Publish metadata.{type}.created / .updated event to realtime service.
+    // An overwrite is an UPDATE, mirroring the 'added' vs 'changed' split the
+    // watcher event below already makes (#4602).
+    await this.publishRealtimeMetadataEvent(existed ? 'updated' : 'created', type, name, {
+      definition: data,
+      packageId: (data as any)?.packageId,
+      userId: options?.userId,
+    });
 
     // Announce last, once the write has landed in the registry and every
     // writable loader — a subscriber that re-reads on the event must not
@@ -484,24 +558,9 @@ export class MetadataManager implements IMetadataService {
     }
 
     // Publish metadata.{type}.deleted event to realtime service
-    if (this.realtimeService) {
-      const event: RealtimeEventPayload = {
-        type: `metadata.${type}.deleted`,
-        object: type,
-        payload: {
-          metadataType: type,
-          name,
-        },
-        timestamp: new Date().toISOString(),
-      };
-
-      try {
-        await this.realtimeService.publish(event);
-        this.logger.debug(`Published metadata.${type}.deleted event`, { name });
-      } catch (error) {
-        this.logger.warn(`Failed to publish metadata event`, { type, name, error });
-      }
-    }
+    await this.publishRealtimeMetadataEvent('deleted', type, name, {
+      userId: options?.userId,
+    });
 
     // Announce last, once the removal has landed everywhere (see register()).
     if (options?.notify !== false) {