@beignet/core 0.0.51 → 0.0.52

package/src/events/index.ts

@@ -7,8 +7,21 @@ import {
 } from "../tracing/index.js";
 import {
   isEventPayloadParsed,
-  markEventPayloadParsed,
+  isEventPayloadTransportStable,
+  markEventPayloadTransportStable,
 } from "./payload-state.js";
+import {
+  EventTransportError,
+  type EventTransportValue,
+  eventTransportValuesEqual,
+  toEventTransportValue,
+} from "./transport.js";
+
+export {
+  EventTransportError,
+  type EventTransportErrorReason,
+  type EventTransportValue,
+} from "./transport.js";
 
 /**
  * Any Standard Schema compatible validator.
@@ -299,6 +312,18 @@ export class EventValidationError extends Error {
   }
 }
 
+/**
+ * Parsed runtime value and canonical JSON value for one event publication.
+ */
+export interface PreparedEventPayload<E extends EventPayloadDef> {
+  /** Parsed Standard Schema output delivered to in-process listeners. */
+  readonly payload: InferEventPayload<E>;
+  /** Canonical JSON value written by serialized transports. */
+  readonly transportValue: EventTransportValue;
+  /** Complete publish metadata to forward to in-process subscribers. */
+  readonly publishOptions: EventPublishOptions;
+}
+
 function formatPath(path: StandardSchemaV1.Issue["path"]): string {
   if (!path?.length) return "";
 
@@ -345,7 +370,9 @@ async function parsePayload<Schema extends StandardSchemaV1>(
  * Define a typed event.
  *
  * Event payloads are validated before publishing through `publishEvent(...)`
- * and before registered listeners run.
+ * and before registered listeners run. Producer helpers also require parsed
+ * output to be plain JSON that remains unchanged when validated again after a
+ * transport round trip.
  */
 export function defineEvent<
   Name extends string,
@@ -388,7 +415,101 @@ export async function parseEventPayload<E extends EventPayloadDef>(
 }
 
 /**
- * Validate an event payload and publish it through an event bus.
+ * Parse an event payload and prove that its canonical JSON survives transport.
+ *
+ * Custom event-bus providers must call this before publishing. The returned
+ * runtime payload is suitable for in-process listeners; `transportValue` is
+ * the exact JSON-safe value to encode for a serialized transport.
+ */
+export async function prepareEventPayloadForTransport<
+  E extends EventPayloadDef,
+>(
+  event: E,
+  payload: unknown,
+  options?: EventPublishOptions,
+): Promise<PreparedEventPayload<E>> {
+  const parsed = isEventPayloadParsed(event, payload, options)
+    ? (payload as InferEventPayload<E>)
+    : await parseEventPayload(event, payload);
+  const transportValue = toEventTransportValue(event.name, parsed);
+  let canonicalPayload = parsed;
+  let transportStateIsCurrent = false;
+
+  try {
+    transportStateIsCurrent = isEventPayloadTransportStable(
+      event,
+      parsed,
+      transportValue,
+      options,
+    );
+  } catch {
+    // Revalidate if a mutated or proxied payload can no longer be compared.
+  }
+
+  if (!transportStateIsCurrent) {
+    let reparsed: InferEventPayload<E>;
+    try {
+      reparsed = await parseEventPayload(event, transportValue);
+    } catch (error) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        message:
+          "is not transport-stable: its canonical JSON failed validation when decoded again. Event schemas must accept their own canonical JSON output.",
+        cause: error,
+      });
+    }
+
+    let reparsedTransportValue: EventTransportValue;
+    try {
+      reparsedTransportValue = toEventTransportValue(event.name, reparsed);
+    } catch (error) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        path: error instanceof EventTransportError ? error.path : undefined,
+        message:
+          "is not transport-stable: validating its canonical JSON produced a value that is not JSON-safe.",
+        cause: error,
+      });
+    }
+
+    if (!eventTransportValuesEqual(transportValue, reparsedTransportValue)) {
+      throw new EventTransportError({
+        eventName: event.name,
+        reason: "not-stable",
+        message:
+          "is not transport-stable: its canonical JSON changed when validated again. Event schema transforms must be idempotent.",
+      });
+    }
+    canonicalPayload = reparsed;
+  }
+
+  try {
+    return {
+      payload: canonicalPayload,
+      transportValue,
+      publishOptions: markEventPayloadTransportStable(
+        event,
+        canonicalPayload,
+        transportValue,
+        options,
+      ),
+    };
+  } catch (error) {
+    throw new EventTransportError({
+      eventName: event.name,
+      reason: "not-stable",
+      message:
+        "is not transport-stable: its canonical output could not be inspected consistently.",
+      cause: error,
+    });
+  }
+}
+
+/**
+ * Validate an event payload, prove transport stability, and publish it through
+ * an event bus.
  */
 export async function publishEvent<E extends EventPayloadDef>(
   eventBus: EventBusLike,
@@ -396,8 +517,12 @@ export async function publishEvent<E extends EventPayloadDef>(
   payload: InferEventPayload<E>,
   options?: EventPublishOptions,
 ): Promise<void> {
-  const parsed = await parseEventPayload(event, payload);
-  await eventBus.publish(event, parsed, markEventPayloadParsed(options));
+  const prepared = await prepareEventPayloadForTransport(
+    event,
+    payload,
+    options,
+  );
+  await eventBus.publish(event, prepared.payload, prepared.publishOptions);
 }
 
 function assertReadyTimeoutMs(value: number): void {
@@ -490,9 +615,11 @@ export function registerListeners<Ctx>(
           listener.event,
           async (rawPayload, publishOptions) => {
             try {
-              const payload = isEventPayloadParsed(publishOptions)
-                ? rawPayload
-                : await parseEventPayload(listener.event, rawPayload);
+              const prepared = await prepareEventPayloadForTransport(
+                listener.event,
+                rawPayload,
+                publishOptions,
+              );
               const traceAttributes = {
                 "beignet.listener.name": listener.name,
                 "beignet.event.name": listener.event.name,
@@ -504,14 +631,14 @@ export function registerListeners<Ctx>(
                   name: `beignet.listener ${listener.name}`,
                   type: "listener",
                   kind: "consumer",
-                  parent: parseTraceCarrier(publishOptions?.trace),
+                  parent: parseTraceCarrier(prepared.publishOptions.trace),
                   attributes: traceAttributes,
                   metricAttributes: traceAttributes,
                 },
                 run: (ctx) =>
                   listener.handle({
                     event: listener.event,
-                    payload,
+                    payload: prepared.payload,
                     ctx,
                   }),
               });

package/src/events/payload-state.ts

@@ -1,24 +1,223 @@
 import type { EventPublishOptions } from "./index.js";
+import type { EventTransportValue } from "./transport.js";
 
 const PARSED_EVENT_PAYLOAD = Symbol.for("beignet.eventPayload.parsed");
+const TRANSPORT_STABLE_EVENT_PAYLOAD = Symbol.for(
+  "beignet.eventPayload.transportStable",
+);
 
 type ParsedEventPublishOptions = EventPublishOptions & {
-  [PARSED_EVENT_PAYLOAD]?: true;
+  [PARSED_EVENT_PAYLOAD]?: object;
+  [TRANSPORT_STABLE_EVENT_PAYLOAD]?: object;
 };
 
+interface ParsedPayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: unknown;
+}
+
+type PayloadSnapshot =
+  | { readonly kind: "primitive"; readonly value: unknown }
+  | {
+      readonly kind: "array";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly items: readonly PayloadSnapshot[];
+    }
+  | {
+      readonly kind: "object";
+      readonly value: object;
+      readonly prototype: object | null;
+      readonly entries: readonly (readonly [string, PayloadSnapshot])[];
+    };
+
+interface TransportStablePayloadState {
+  readonly eventName: string;
+  readonly payloadSchema: object;
+  readonly validate: unknown;
+  readonly payload: PayloadSnapshot;
+  readonly fingerprint: string;
+}
+
+interface EventPayloadIdentity {
+  readonly name: string;
+  readonly payload: {
+    readonly "~standard": {
+      readonly validate: unknown;
+    };
+  };
+}
+
+const transportStablePayloadStates = new WeakMap<
+  object,
+  TransportStablePayloadState
+>();
+const parsedPayloadStates = new WeakMap<object, ParsedPayloadState>();
+
+function transportFingerprint(value: EventTransportValue): string {
+  return JSON.stringify(value);
+}
+
+function capturePayloadSnapshot(value: unknown): PayloadSnapshot {
+  if (value === null || typeof value !== "object") {
+    return { kind: "primitive", value };
+  }
+  if (Array.isArray(value)) {
+    const items: PayloadSnapshot[] = [];
+    for (let index = 0; index < value.length; index += 1) {
+      const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+      if (!descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable array state must contain data properties.",
+        );
+      }
+      items.push(capturePayloadSnapshot(descriptor.value));
+    }
+    return {
+      kind: "array",
+      value,
+      prototype: Object.getPrototypeOf(value),
+      items,
+    };
+  }
+  return {
+    kind: "object",
+    value,
+    prototype: Object.getPrototypeOf(value),
+    entries: Reflect.ownKeys(value).map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (typeof key !== "string" || !descriptor || !("value" in descriptor)) {
+        throw new TypeError(
+          "Transport-stable payload state must contain data properties.",
+        );
+      }
+      return [key, capturePayloadSnapshot(descriptor.value)] as const;
+    }),
+  };
+}
+
+function matchesPayloadSnapshot(
+  snapshot: PayloadSnapshot,
+  value: unknown,
+): boolean {
+  if (snapshot.kind === "primitive") return Object.is(snapshot.value, value);
+  if (snapshot.value !== value || value === null || typeof value !== "object") {
+    return false;
+  }
+  if (Object.getPrototypeOf(value) !== snapshot.prototype) return false;
+  if (snapshot.kind === "array") {
+    return (
+      Array.isArray(value) &&
+      value.length === snapshot.items.length &&
+      snapshot.items.every((item, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          value,
+          String(index),
+        );
+        return (
+          descriptor !== undefined &&
+          "value" in descriptor &&
+          matchesPayloadSnapshot(item, descriptor.value)
+        );
+      })
+    );
+  }
+  if (Array.isArray(value)) return false;
+  const keys = Reflect.ownKeys(value);
+  return (
+    keys.length === snapshot.entries.length &&
+    snapshot.entries.every(([key, item], index) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return (
+        keys[index] === key &&
+        descriptor !== undefined &&
+        "value" in descriptor &&
+        matchesPayloadSnapshot(item, descriptor.value)
+      );
+    })
+  );
+}
+
 export function markEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
   options?: EventPublishOptions,
 ): EventPublishOptions {
+  const token = {};
+  parsedPayloadStates.set(token, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
   return {
     ...options,
-    [PARSED_EVENT_PAYLOAD]: true,
+    [PARSED_EVENT_PAYLOAD]: token,
   } as ParsedEventPublishOptions;
 }
 
-export function isEventPayloadParsed(options?: EventPublishOptions): boolean {
+export function isEventPayloadParsed(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    PARSED_EVENT_PAYLOAD
+  ];
+  const state = token ? parsedPayloadStates.get(token) : undefined;
+  return (
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    Object.is(state.payload, payload)
+  );
+}
+
+export function markEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): EventPublishOptions {
+  const parsedToken = {};
+  parsedPayloadStates.set(parsedToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload,
+  });
+  const stableToken = {};
+  transportStablePayloadStates.set(stableToken, {
+    eventName: event.name,
+    payloadSchema: event.payload,
+    validate: event.payload["~standard"].validate,
+    payload: capturePayloadSnapshot(payload),
+    fingerprint: transportFingerprint(transportValue),
+  });
+  return {
+    ...options,
+    [PARSED_EVENT_PAYLOAD]: parsedToken,
+    [TRANSPORT_STABLE_EVENT_PAYLOAD]: stableToken,
+  } as ParsedEventPublishOptions;
+}
+
+export function isEventPayloadTransportStable(
+  event: EventPayloadIdentity,
+  payload: unknown,
+  transportValue: EventTransportValue,
+  options?: EventPublishOptions,
+): boolean {
+  const token = (options as ParsedEventPublishOptions | undefined)?.[
+    TRANSPORT_STABLE_EVENT_PAYLOAD
+  ];
+  const state = token ? transportStablePayloadStates.get(token) : undefined;
   return (
-    (options as ParsedEventPublishOptions | undefined)?.[
-      PARSED_EVENT_PAYLOAD
-    ] === true
+    state?.eventName === event.name &&
+    state.payloadSchema === event.payload &&
+    state.validate === event.payload["~standard"].validate &&
+    matchesPayloadSnapshot(state.payload, payload) &&
+    state.fingerprint === transportFingerprint(transportValue)
   );
 }

package/src/events/transport.ts

@@ -0,0 +1,242 @@
+/** Canonical JSON value that can cross an event transport boundary. */
+export type EventTransportValue =
+  | null
+  | string
+  | number
+  | boolean
+  | readonly EventTransportValue[]
+  | { readonly [key: string]: EventTransportValue };
+
+/** Why an event payload cannot safely cross a serialized transport. */
+export type EventTransportErrorReason = "not-json-safe" | "not-stable";
+
+/** Error thrown when an event payload cannot survive canonical JSON transport. */
+export class EventTransportError extends Error {
+  /** Stable event name. */
+  readonly eventName: string;
+  /** Whether the value is not JSON-safe or changes under repeated parsing. */
+  readonly reason: EventTransportErrorReason;
+  /** Payload path associated with a JSON-safety failure. */
+  readonly path?: string;
+
+  constructor(args: {
+    eventName: string;
+    reason: EventTransportErrorReason;
+    message: string;
+    path?: string;
+    cause?: unknown;
+  }) {
+    super(`Event "${args.eventName}" payload ${args.message}`, {
+      cause: args.cause,
+    });
+    this.name = "EventTransportError";
+    this.eventName = args.eventName;
+    this.reason = args.reason;
+    this.path = args.path;
+  }
+}
+
+function childTransportPath(path: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
+    ? `${path}.${key}`
+    : `${path}[${JSON.stringify(key)}]`;
+}
+
+function throwJsonSafetyError(args: {
+  eventName: string;
+  path: string;
+  message: string;
+}): never {
+  throw new EventTransportError({
+    eventName: args.eventName,
+    reason: "not-json-safe",
+    path: args.path,
+    message: `is not transport-safe at ${args.path}: ${args.message}`,
+  });
+}
+
+export function toEventTransportValue(
+  eventName: string,
+  value: unknown,
+  path = "payload",
+  seen: WeakSet<object> = new WeakSet(),
+): EventTransportValue {
+  if (value === null) return null;
+
+  if (typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "numbers must be finite.",
+      });
+    }
+    return Object.is(value, -0) ? 0 : value;
+  }
+
+  if (typeof value !== "object") {
+    return throwJsonSafetyError({
+      eventName,
+      path,
+      message: `received ${typeof value}; use null, strings, finite numbers, booleans, arrays, or plain objects.`,
+    });
+  }
+
+  try {
+    if (value instanceof Date) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "Date values are not supported; use an ISO string or number.",
+      });
+    }
+
+    if (seen.has(value)) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "circular references are not supported.",
+      });
+    }
+
+    seen.add(value);
+    if (Array.isArray(value)) {
+      const output: EventTransportValue[] = [];
+      const ownKeys = Reflect.ownKeys(value);
+      const hasUnsupportedKey = ownKeys.some((key) => {
+        if (key === "length") return false;
+        if (typeof key !== "string") return true;
+        const index = Number(key);
+        return (
+          !Number.isInteger(index) ||
+          index < 0 ||
+          index >= value.length ||
+          String(index) !== key
+        );
+      });
+      if (hasUnsupportedKey) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "arrays cannot contain symbol or custom properties.",
+        });
+      }
+      if (ownKeys.length !== value.length + 1) {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "sparse arrays are not supported.",
+        });
+      }
+      for (let index = 0; index < value.length; index += 1) {
+        const key = String(index);
+        const itemPath = `${path}[${index}]`;
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "sparse arrays are not supported.",
+          });
+        }
+        if (!("value" in descriptor) || !descriptor.enumerable) {
+          return throwJsonSafetyError({
+            eventName,
+            path: itemPath,
+            message: "array items must be enumerable data properties.",
+          });
+        }
+        output.push(
+          toEventTransportValue(eventName, descriptor.value, itemPath, seen),
+        );
+      }
+      return output;
+    }
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+      return throwJsonSafetyError({
+        eventName,
+        path,
+        message: "objects must be plain objects.",
+      });
+    }
+
+    const output = {} as Record<string, EventTransportValue>;
+    for (const key of Reflect.ownKeys(value)) {
+      if (typeof key !== "string") {
+        return throwJsonSafetyError({
+          eventName,
+          path,
+          message: "symbol properties are not supported.",
+        });
+      }
+      const propertyPath = childTransportPath(path, key);
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor) || !descriptor.enumerable) {
+        return throwJsonSafetyError({
+          eventName,
+          path: propertyPath,
+          message: "properties must be enumerable data properties.",
+        });
+      }
+      Object.defineProperty(output, key, {
+        configurable: true,
+        enumerable: true,
+        writable: true,
+        value: toEventTransportValue(
+          eventName,
+          descriptor.value,
+          propertyPath,
+          seen,
+        ),
+      });
+    }
+    return output;
+  } catch (error) {
+    if (error instanceof EventTransportError) throw error;
+    throw new EventTransportError({
+      eventName,
+      reason: "not-json-safe",
+      path,
+      message: `could not be inspected as transport data at ${path}.`,
+      cause: error,
+    });
+  } finally {
+    seen.delete(value);
+  }
+}
+
+export function eventTransportValuesEqual(
+  left: EventTransportValue,
+  right: EventTransportValue,
+): boolean {
+  if (left === right) return true;
+  if (left === null || right === null || typeof left !== typeof right) {
+    return false;
+  }
+  if (Array.isArray(left) || Array.isArray(right)) {
+    if (!Array.isArray(left) || !Array.isArray(right)) return false;
+    return (
+      left.length === right.length &&
+      left.every((value, index) =>
+        eventTransportValuesEqual(value, right[index]),
+      )
+    );
+  }
+  if (typeof left !== "object" || typeof right !== "object") return false;
+
+  const leftRecord = left as Readonly<Record<string, EventTransportValue>>;
+  const rightRecord = right as Readonly<Record<string, EventTransportValue>>;
+  const leftKeys = Object.keys(leftRecord).sort();
+  const rightKeys = Object.keys(rightRecord).sort();
+  return (
+    leftKeys.length === rightKeys.length &&
+    leftKeys.every(
+      (key, index) =>
+        key === rightKeys[index] &&
+        eventTransportValuesEqual(leftRecord[key], rightRecord[key]),
+    )
+  );
+}