abxbus 2.4.31 → 2.5.0

package/src/BaseEvent.ts

@@ -13,11 +13,23 @@ import {
   withResolvers,
 } from './LockManager.js'
 import { _runWithTimeout } from './timing.js'
-import { extractZodShape, normalizeEventResultType, toJsonSchema } from './types.js'
+import { isZodSchema, normalizeEventResultType, toJsonSchema } from './types.js'
 import type { EventHandlerCallable, EventResultType } from './types.js'
 import { monotonicDatetime } from './helpers.js'
 
-const RESERVED_USER_EVENT_FIELDS = new Set(['bus', 'emit', 'first', 'toString', 'toJSON', 'fromJSON'])
+const RESERVED_USER_EVENT_FIELDS = new Set([
+  'bus',
+  'emit',
+  'wait',
+  'now',
+  'eventResult',
+  'eventResultsList',
+  'toString',
+  'toJSON',
+  'fromJSON',
+])
+
+const EVENT_TYPE_REGISTRY = new Map<string, typeof BaseEvent>()
 
 function assertNoReservedUserEventFields(data: Record<string, unknown>, context: string): void {
   for (const field_name of RESERVED_USER_EVENT_FIELDS) {
@@ -43,6 +55,18 @@ function assertNoModelPrefixedFields(data: Record<string, unknown>, context: str
   }
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value)
+}
+
+function isZodObjectSchema(value: unknown): value is z.ZodObject<z.ZodRawShape> {
+  return (
+    isZodSchema(value) &&
+    typeof (value as { safeExtend?: unknown }).safeExtend === 'function' &&
+    isRecord((value as { shape?: unknown }).shape)
+  )
+}
+
 function compareIsoDatetime(left: string | null | undefined, right: string | null | undefined): number {
   const left_value = left ?? ''
   const right_value = right ?? ''
@@ -58,10 +82,10 @@ export const BaseEventSchema = z
     event_created_at: z.string().datetime(),
     event_type: z.string(),
     event_version: z.string().default('0.0.1'),
-    event_timeout: z.number().positive().nullable(),
-    event_slow_timeout: z.number().positive().nullable().optional(),
-    event_handler_timeout: z.number().positive().nullable().optional(),
-    event_handler_slow_timeout: z.number().positive().nullable().optional(),
+    event_timeout: z.number().nonnegative().nullable(),
+    event_slow_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_slow_timeout: z.number().nonnegative().nullable().optional(),
     event_blocks_parent_completion: z.boolean().optional(),
     event_parent_id: z.string().uuid().nullable().optional(),
     event_path: z.array(z.string()).optional(),
@@ -79,6 +103,7 @@ export const BaseEventSchema = z
   .loose()
 
 const KNOWN_BASE_EVENT_FIELDS = new Set(Object.keys(BaseEventSchema.shape))
+type AnyEventSchema = z.ZodTypeAny
 
 export type BaseEventData = z.infer<typeof BaseEventSchema>
 export type BaseEventJSON = BaseEventData & Record<string, unknown>
@@ -109,12 +134,15 @@ type BaseEventFields = { [K in BaseEventFieldName]: BaseEventData[K] }
 export type BaseEventInit<TFields extends Record<string, unknown>> = TFields & Partial<BaseEventFields>
 
 type BaseEventSchemaShape = typeof BaseEventSchema.shape
-
 export type EventSchema<TShape extends z.ZodRawShape> = z.ZodObject<BaseEventSchemaShape & TShape>
 type EventPayload<TShape extends z.ZodRawShape> = TShape extends Record<string, never> ? {} : z.infer<z.ZodObject<TShape>>
 
 type EventInput<TShape extends z.ZodRawShape> = z.input<EventSchema<TShape>>
 export type EventInit<TShape extends z.ZodRawShape> = Omit<EventInput<TShape>, keyof BaseEventFields> & Partial<BaseEventFields>
+type EventPayloadFromSchema<TSchema extends AnyEventSchema> = z.output<TSchema> extends Record<string, unknown> ? z.output<TSchema> : {}
+type EventInputFromSchema<TSchema extends AnyEventSchema> = z.input<TSchema> extends Record<string, unknown> ? z.input<TSchema> : never
+export type EventInitFromSchema<TSchema extends AnyEventSchema> = Omit<EventInputFromSchema<TSchema>, keyof BaseEventFields> &
+  Partial<BaseEventFields>
 
 type EventWithResultSchema<TResult> = BaseEvent & { __event_result_type__?: TResult }
 
@@ -133,18 +161,22 @@ type ResultTypeFromEventResultTypeInput<TInput> = TInput extends z.ZodTypeAny
             : unknown
 
 type ResultSchemaFromShape<TShape> = TShape extends { event_result_type: infer S } ? ResultTypeFromEventResultTypeInput<S> : unknown
-type EventResultsListInclude<TEvent extends BaseEvent> = (
-  result: EventResultType<TEvent> | undefined,
+export type EventResultInclude<TEvent extends BaseEvent> = (
+  result: EventResult<TEvent>['result'],
   event_result: EventResult<TEvent>
 ) => boolean
-type EventResultsListOptions<TEvent extends BaseEvent> = {
-  timeout?: number | null
-  include?: EventResultsListInclude<TEvent>
+export type EventResultOptions<TEvent extends BaseEvent> = {
+  include?: EventResultInclude<TEvent>
   raise_if_any?: boolean
   raise_if_none?: boolean
 }
-type EventDoneOptions = {
-  raise_if_any?: boolean
+export type EventWaitOptions = {
+  timeout?: number | null
+  first_result?: boolean
+}
+export type EventWaitPromise<TEvent extends BaseEvent> = Promise<TEvent> & {
+  eventResult(options?: EventResultOptions<TEvent>): Promise<EventResultType<TEvent> | undefined>
+  eventResultsList(options?: EventResultOptions<TEvent>): Promise<Array<EventResultType<TEvent> | undefined>>
 }
 type EventResultUpdateOptions<TEvent extends BaseEvent> = {
   eventbus?: EventBus
@@ -153,13 +185,12 @@ type EventResultUpdateOptions<TEvent extends BaseEvent> = {
   error?: unknown
 }
 
-const EVENT_CLASS_DEFAULTS = new WeakMap<Function, Record<string, unknown>>()
 const ROOT_EVENTBUS_ID = '00000000-0000-0000-0000-000000000000'
 
 export type EventFactory<TShape extends z.ZodRawShape, TResult = unknown> = {
   (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>
   new (data: EventInit<TShape>): EventWithResultSchema<TResult> & EventPayload<TShape>
-  schema: EventSchema<TShape>
+  event_schema: EventSchema<TShape>
   class?: new (data: EventInit<TShape>) => EventWithResultSchema<TResult> & EventPayload<TShape>
   event_type?: string
   event_version?: string
@@ -167,6 +198,17 @@ export type EventFactory<TShape extends z.ZodRawShape, TResult = unknown> = {
   fromJSON?: (data: unknown) => EventWithResultSchema<TResult> & EventPayload<TShape>
 }
 
+export type SchemaEventFactory<TSchema extends AnyEventSchema, TResult = unknown> = {
+  (data: EventInitFromSchema<TSchema>): EventWithResultSchema<TResult> & EventPayloadFromSchema<TSchema>
+  new (data: EventInitFromSchema<TSchema>): EventWithResultSchema<TResult> & EventPayloadFromSchema<TSchema>
+  event_schema: TSchema
+  class?: new (data: EventInitFromSchema<TSchema>) => EventWithResultSchema<TResult> & EventPayloadFromSchema<TSchema>
+  event_type?: string
+  event_version?: string
+  event_result_type?: z.ZodTypeAny
+  fromJSON?: (data: unknown) => EventWithResultSchema<TResult> & EventPayloadFromSchema<TSchema>
+}
+
 type ZodShapeFrom<TShape extends Record<string, unknown>> = {
   [K in keyof TShape as K extends 'event_result_type' ? never : TShape[K] extends z.ZodTypeAny ? K : never]: Extract<
     TShape[K],
@@ -174,6 +216,130 @@ type ZodShapeFrom<TShape extends Record<string, unknown>> = {
   >
 }
 
+function baseEventDefaultShape(event_type: string): z.ZodRawShape {
+  return {
+    event_id: z.string().uuid(),
+    event_created_at: z.string().datetime(),
+    event_type: z.string().default(event_type),
+    event_version: z.string().default('0.0.1'),
+    event_timeout: z.number().nonnegative().nullable().default(null),
+    event_slow_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_timeout: z.number().nonnegative().nullable().optional(),
+    event_handler_slow_timeout: z.number().nonnegative().nullable().optional(),
+    event_blocks_parent_completion: z.boolean().default(false),
+    event_parent_id: z.string().uuid().nullable().optional(),
+    event_path: z.array(z.string()).optional(),
+    event_result_type: z.unknown().optional(),
+    event_emitted_by_handler_id: z.string().uuid().nullable().optional(),
+    event_pending_bus_count: z.number().nonnegative().optional(),
+    event_status: z.enum(['pending', 'started', 'completed']).optional(),
+    event_started_at: z.string().datetime().nullable().optional(),
+    event_completed_at: z.string().datetime().nullable().optional(),
+    event_results: z.record(z.string(), z.unknown()).optional(),
+    event_concurrency: z.enum(EVENT_CONCURRENCY_MODES).nullable().optional(),
+    event_handler_concurrency: z.enum(EVENT_HANDLER_CONCURRENCY_MODES).nullable().optional(),
+    event_handler_completion: z.enum(EVENT_HANDLER_COMPLETION_MODES).nullable().optional(),
+  }
+}
+
+function missingBaseFields(event_type: string, user_shape: z.ZodRawShape): z.ZodRawShape {
+  return Object.fromEntries(Object.entries(baseEventDefaultShape(event_type)).filter(([key]) => !(key in user_shape))) as z.ZodRawShape
+}
+
+type ZodSchemaWithPrefault = z.ZodTypeAny & {
+  prefault: (value: unknown) => z.ZodTypeAny
+}
+
+function shortcutDefaultSchema(base_field_schema: z.ZodTypeAny | undefined, value: unknown): z.ZodTypeAny {
+  if (!base_field_schema) {
+    return z.unknown().optional().default(value)
+  }
+  return (base_field_schema as ZodSchemaWithPrefault).prefault(base_field_schema.parse(value))
+}
+
+function schemaDefaultsForShortcut(event_type: string, raw_shape: Record<string, unknown>): z.ZodRawShape {
+  const defaults: Record<string, z.ZodTypeAny> = {}
+  const base_shape = baseEventDefaultShape(event_type)
+  for (const [key, value] of Object.entries(raw_shape)) {
+    if (key === 'event_result_type') continue
+    if (!isZodSchema(value)) {
+      defaults[key] = shortcutDefaultSchema(base_shape[key] as z.ZodTypeAny | undefined, value)
+    }
+  }
+  return defaults
+}
+
+function zodFieldsForShortcut(raw_shape: Record<string, unknown>): z.ZodRawShape {
+  const fields: Record<string, z.ZodTypeAny> = {}
+  for (const [key, value] of Object.entries(raw_shape)) {
+    if (key === 'event_result_type') continue
+    if (isZodSchema(value)) {
+      fields[key] = value
+    }
+  }
+  return fields
+}
+
+function eventResultTypeFromObjectSchema(schema: z.ZodObject<z.ZodRawShape>): z.ZodTypeAny | undefined {
+  const raw_event_result_type = schema.shape.event_result_type
+  return raw_event_result_type === undefined ? undefined : normalizeEventResultType(raw_event_result_type)
+}
+
+function buildFullEventSchema(
+  event_type: string,
+  spec: unknown
+): {
+  event_schema: AnyEventSchema
+  event_result_type?: z.ZodTypeAny
+  event_version?: string
+} {
+  if (isZodObjectSchema(spec)) {
+    const user_shape = spec.shape
+    assertNoReservedUserEventFields(user_shape, `BaseEvent.extend(${event_type})`)
+    assertNoUnknownEventPrefixedFields(user_shape, `BaseEvent.extend(${event_type})`)
+    assertNoModelPrefixedFields(user_shape, `BaseEvent.extend(${event_type})`)
+    const full_schema = spec.safeExtend({
+      event_result_type: z.unknown().optional(),
+      ...missingBaseFields(event_type, user_shape),
+    })
+    return {
+      event_schema: full_schema,
+      event_result_type: eventResultTypeFromObjectSchema(spec),
+    }
+  }
+
+  const raw_shape = (isRecord(spec) ? spec : {}) as Record<string, unknown>
+  assertNoReservedUserEventFields(raw_shape, `BaseEvent.extend(${event_type})`)
+  assertNoUnknownEventPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`)
+  assertNoModelPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`)
+  const shortcut_shape = {
+    ...schemaDefaultsForShortcut(event_type, raw_shape),
+    ...zodFieldsForShortcut(raw_shape),
+  }
+  const full_schema = z.object(shortcut_shape).safeExtend(missingBaseFields(event_type, shortcut_shape)).loose()
+  return {
+    event_schema: full_schema,
+    event_result_type: normalizeEventResultType(raw_shape.event_result_type),
+    event_version: typeof raw_shape.event_version === 'string' ? raw_shape.event_version : undefined,
+  }
+}
+
+function decodeEventSchema(schema: AnyEventSchema, input: unknown): Record<string, unknown> {
+  const decoded = (z as unknown as { decode: (schema: AnyEventSchema, input: unknown) => unknown }).decode(schema, input)
+  if (!isRecord(decoded)) {
+    throw new Error('BaseEvent schema must decode to an object')
+  }
+  return decoded
+}
+
+function encodeEventSchema(schema: AnyEventSchema, input: Record<string, unknown>): Record<string, unknown> {
+  const encoded = (z as unknown as { encode: (schema: AnyEventSchema, input: unknown) => unknown }).encode(schema, input)
+  if (!isRecord(encoded)) {
+    throw new Error('BaseEvent schema must encode to an object')
+  }
+  return encoded
+}
+
 export class BaseEvent {
   // event metadata fields
   event_id!: string // unique uuidv7 identifier for the event
@@ -184,7 +350,7 @@ export class BaseEvent {
   event_slow_timeout?: number | null // optional per-event slow warning threshold in seconds
   event_handler_timeout?: number | null // optional per-event handler timeout override in seconds
   event_handler_slow_timeout?: number | null // optional per-event slow handler warning threshold in seconds
-  event_blocks_parent_completion!: boolean // true only for children explicitly awaited via done()/eventCompleted()
+  event_blocks_parent_completion!: boolean // true only for children explicitly awaited via now()
   event_parent_id!: string | null // id of the parent event that triggered this event, if this event was emitted during handling of another event, else null
   event_path!: string[] // list of bus labels (name#id) that the event has been dispatched to, including the current bus
   event_result_type?: z.ZodTypeAny // optional zod schema to enforce the shape of return values from handlers
@@ -197,15 +363,18 @@ export class BaseEvent {
   event_concurrency?: EventConcurrencyMode | null // concurrency mode for the event as a whole in relation to other events
   event_handler_concurrency?: EventHandlerConcurrencyMode | null // concurrency mode for the handlers within the event
   event_handler_completion?: EventHandlerCompletionMode | null // completion strategy: 'all' (default) waits for every handler, 'first' returns earliest non-undefined result and cancels the rest
+  event_schema?: z.ZodTypeAny
 
   static event_type?: string // class name of the event, e.g. BaseEvent.extend("MyEvent").event_type === "MyEvent"
   static event_version = '0.0.1'
-  static schema = BaseEventSchema // zod schema for the event data fields, used to parse and validate event data when creating a new event
+  static event_result_type?: z.ZodTypeAny
+  static event_schema: AnyEventSchema = BaseEventSchema // generated Zod schema for local TS event data validation; never sent over the wire
 
   // internal runtime state
   event_bus?: EventBus // bus that dispatched this event, also used by event.emit(child)
   _event_original?: BaseEvent // underlying event object that was dispatched, if this is a bus-scoped proxy wrapping it
   _event_dispatch_context?: unknown | null // captured AsyncLocalStorage context at dispatch site, used to restore that context when running handlers
+  _event_fields_set?: Set<string>
 
   _event_completed_signal: Deferred<this> | null
   _lock_for_event_handler: AsyncLock | null
@@ -216,39 +385,48 @@ export class BaseEvent {
     const ctor = this.constructor as typeof BaseEvent & {
       event_version?: string
       event_result_type?: z.ZodTypeAny
+      event_schema?: AnyEventSchema
     }
-    const ctor_defaults = EVENT_CLASS_DEFAULTS.get(ctor) ?? {}
-    const merged_data = {
-      ...ctor_defaults,
-      ...data,
-    } as BaseEventInit<Record<string, unknown>>
+    const explicit_event_fields = new Set(Object.keys(data ?? {}))
+    const merged_data = { ...data } as BaseEventInit<Record<string, unknown>>
     const event_type = merged_data.event_type ?? ctor.event_type ?? ctor.name
     const event_version = merged_data.event_version ?? ctor.event_version ?? '0.0.1'
     const raw_event_result_type = merged_data.event_result_type ?? ctor.event_result_type
     const event_result_type = normalizeEventResultType(raw_event_result_type)
-    const event_id = merged_data.event_id ?? uuidv7()
-    const event_created_at = monotonicDatetime(merged_data.event_created_at)
-    const event_timeout = merged_data.event_timeout ?? null
-    const event_blocks_parent_completion = merged_data.event_blocks_parent_completion ?? false
 
-    const base_data = {
+    const event_schema = ctor.event_schema ?? BaseEventSchema
+    const base_data: Record<string, unknown> = {
       ...merged_data,
-      event_id,
-      event_created_at,
+      event_id: merged_data.event_id ?? uuidv7(),
+      event_created_at: merged_data.event_created_at ?? monotonicDatetime(),
       event_type,
       event_version,
-      event_timeout,
-      event_blocks_parent_completion,
       event_result_type,
     }
+    if (event_schema === BaseEventSchema) {
+      base_data.event_timeout ??= null
+      base_data.event_blocks_parent_completion ??= false
+    }
 
-    const schema = ctor.schema ?? BaseEventSchema
-    const parsed = schema.parse(base_data) as BaseEventData & Record<string, unknown>
+    const parsed = decodeEventSchema(event_schema, base_data) as BaseEventData & Record<string, unknown>
 
     Object.assign(this, parsed)
+    Object.defineProperty(this, 'event_schema', {
+      value: event_schema,
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    })
+    Object.defineProperty(this, '_event_fields_set', {
+      value: explicit_event_fields,
+      writable: true,
+      enumerable: false,
+      configurable: true,
+    })
 
     const parsed_path = (parsed as { event_path?: string[] }).event_path
     this.event_path = Array.isArray(parsed_path) ? [...parsed_path] : []
+    this.event_created_at = monotonicDatetime(parsed.event_created_at)
 
     // load event results from potentially raw objects from JSON to proper EventResult objects
     this.event_results = hydrateEventResults(this, (parsed as { event_results?: unknown }).event_results)
@@ -273,7 +451,7 @@ export class BaseEvent {
         ? (parsed as { event_emitted_by_handler_id: string }).event_emitted_by_handler_id
         : null
 
-    this.event_result_type = event_result_type
+    this.event_result_type = normalizeEventResultType(parsed.event_result_type ?? event_result_type)
 
     this._event_completed_signal = null
     this._lock_for_event_handler = null
@@ -287,6 +465,7 @@ export class BaseEvent {
 
   // main entry point for users to define their own event types
   // BaseEvent.extend("MyEvent", { some_custom_field: z.string(), event_result_type: z.string(), event_timeout: 25, ... }) -> MyEvent
+  static extend<TSchema extends z.ZodObject<z.ZodRawShape>>(event_type: string, event_schema: TSchema): SchemaEventFactory<TSchema, unknown>
   static extend<TShape extends z.ZodRawShape>(event_type: string, shape?: TShape): EventFactory<TShape, ResultSchemaFromShape<TShape>>
   static extend<TShape extends Record<string, unknown>>(
     event_type: string,
@@ -294,32 +473,21 @@ export class BaseEvent {
   ): EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>>
   static extend<TShape extends Record<string, unknown>>(
     event_type: string,
-    shape: TShape = {} as TShape
-  ): EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>> {
-    const raw_shape = shape as Record<string, unknown>
-    assertNoReservedUserEventFields(raw_shape, `BaseEvent.extend(${event_type})`)
-    assertNoUnknownEventPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`)
-    assertNoModelPrefixedFields(raw_shape, `BaseEvent.extend(${event_type})`)
-    const raw_event_result_type = raw_shape.event_result_type
-    const event_result_type = normalizeEventResultType(raw_event_result_type)
-    const event_version = typeof raw_shape.event_version === 'string' ? raw_shape.event_version : undefined
-    const event_defaults = Object.fromEntries(
-      Object.entries(raw_shape).filter(
-        ([key, value]) => key !== 'event_result_type' && key !== 'event_version' && !(value instanceof z.ZodType)
-      )
-    )
-
-    const zod_shape = extractZodShape(raw_shape)
-    const full_schema = BaseEventSchema.extend(zod_shape)
+    shape?: TShape
+  ): EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>> | SchemaEventFactory<AnyEventSchema, unknown> {
+    const built = buildFullEventSchema(event_type, shape ?? {})
+    const full_schema = built.event_schema
+    const event_result_type = built.event_result_type
+    const event_version = built.event_version
 
     // create a new event class that extends BaseEvent and adds the custom fields
     class ExtendedEvent extends BaseEvent {
-      static schema = full_schema as unknown as typeof BaseEvent.schema
+      static event_schema = full_schema
       static event_type = event_type
       static event_version = event_version ?? BaseEvent.event_version
       static event_result_type = event_result_type
 
-      constructor(data: EventInit<ZodShapeFrom<TShape>>) {
+      constructor(data: EventInit<ZodShapeFrom<TShape>> | EventInitFromSchema<AnyEventSchema>) {
         super(data as BaseEventInit<Record<string, unknown>>)
       }
     }
@@ -330,27 +498,40 @@ export class BaseEvent {
       return new ExtendedEvent(data) as FactoryResult
     }
 
-    EventFactory.schema = full_schema as EventSchema<ZodShapeFrom<TShape>>
+    EventFactory.event_schema = full_schema as EventSchema<ZodShapeFrom<TShape>>
     EventFactory.event_type = event_type
     EventFactory.event_version = event_version ?? BaseEvent.event_version
     EventFactory.event_result_type = event_result_type
     EventFactory.class = ExtendedEvent as unknown as new (
       data: EventInit<ZodShapeFrom<TShape>>
     ) => EventWithResultSchema<ResultSchemaFromShape<TShape>> & EventPayload<ZodShapeFrom<TShape>>
-    EventFactory.fromJSON = (data: unknown) => (ExtendedEvent.fromJSON as (data: unknown) => FactoryResult)(data)
+    EventFactory.fromJSON = (data: unknown) => ExtendedEvent.fromJSON(data) as FactoryResult
     EventFactory.prototype = ExtendedEvent.prototype
-    EVENT_CLASS_DEFAULTS.set(ExtendedEvent, event_defaults)
+    EVENT_TYPE_REGISTRY.set(event_type, ExtendedEvent)
 
     return EventFactory as unknown as EventFactory<ZodShapeFrom<TShape>, ResultSchemaFromShape<TShape>>
   }
 
   static fromJSON<T extends typeof BaseEvent>(this: T, data: unknown): InstanceType<T> {
     if (!data || typeof data !== 'object') {
-      const schema = this.schema ?? BaseEventSchema
-      const parsed = schema.parse(data)
+      const event_schema = this.event_schema ?? BaseEventSchema
+      const parsed = decodeEventSchema(event_schema, data)
       return new this(parsed) as InstanceType<T>
     }
     const record = { ...(data as Record<string, unknown>) }
+    if (this === BaseEvent) {
+      const event_type = record.event_type
+      if (typeof event_type === 'string') {
+        const KnownEvent = EVENT_TYPE_REGISTRY.get(event_type)
+        if (KnownEvent) {
+          return KnownEvent.fromJSON(record) as InstanceType<T>
+        }
+      }
+    }
+    const ctor = this as typeof BaseEvent
+    if (this !== BaseEvent && ctor.event_result_type && record.event_result_type !== undefined) {
+      delete record.event_result_type
+    }
     if (record.event_result_type !== undefined && record.event_result_type !== null) {
       record.event_result_type = normalizeEventResultType(record.event_result_type)
     }
@@ -374,7 +555,7 @@ export class BaseEvent {
   toJSON(): BaseEventJSON {
     const record: Record<string, unknown> = {}
     for (const [key, value] of Object.entries(this as unknown as Record<string, unknown>)) {
-      if (key.startsWith('_') || key === 'bus' || key === 'event_bus' || key === 'event_results') continue
+      if (key.startsWith('_') || key === 'bus' || key === 'event_bus' || key === 'event_schema' || key === 'event_results') continue
       if (value === undefined || typeof value === 'function') continue
       record[key] = value
     }
@@ -382,11 +563,45 @@ export class BaseEvent {
       Array.from(this.event_results.entries()).map(([handler_id, result]) => [handler_id, result.toJSON()])
     )
 
-    return {
+    const event_schema = ((this.constructor as typeof BaseEvent).event_schema ?? this.event_schema ?? BaseEventSchema) as AnyEventSchema
+    const encoded = encodeEventSchema(event_schema, {
       ...record,
       event_id: this.event_id,
       event_type: this.event_type,
       event_version: this.event_version,
+      event_result_type: this.event_result_type,
+
+      // static configuration options
+      event_timeout: this.event_timeout,
+      event_slow_timeout: this.event_slow_timeout,
+      event_concurrency: this.event_concurrency,
+      event_handler_concurrency: this.event_handler_concurrency,
+      event_handler_completion: this.event_handler_completion,
+      event_handler_slow_timeout: this.event_handler_slow_timeout,
+      event_handler_timeout: this.event_handler_timeout,
+      event_blocks_parent_completion: this.event_blocks_parent_completion,
+
+      // mutable parent/child/bus tracking runtime state
+      event_parent_id: this.event_parent_id,
+      event_path: this.event_path,
+      event_emitted_by_handler_id: this.event_emitted_by_handler_id,
+      event_pending_bus_count: this.event_pending_bus_count,
+
+      // mutable runtime status and timestamps
+      event_status: this.event_status,
+      event_created_at: this.event_created_at,
+      event_started_at: this.event_started_at ?? null,
+      event_completed_at: this.event_completed_at ?? null,
+
+      ...(Object.keys(event_results).length > 0 ? { event_results } : {}),
+    })
+    delete encoded.event_schema
+
+    return {
+      ...encoded,
+      event_id: this.event_id,
+      event_type: this.event_type,
+      event_version: this.event_version,
       event_result_type: this.event_result_type ? toJsonSchema(this.event_result_type) : this.event_result_type,
 
       // static configuration options
@@ -416,13 +631,15 @@ export class BaseEvent {
     }
   }
 
-  _createSlowEventWarningTimer(): ReturnType<typeof setTimeout> | null {
-    const event_slow_timeout = this.event_slow_timeout ?? this.event_bus?.event_slow_timeout ?? null
-    const event_warn_ms = event_slow_timeout === null ? null : event_slow_timeout * 1000
+  _createSlowEventWarningTimer(
+    event_slow_timeout: number | null = this.event_slow_timeout ?? null,
+    bus_name?: string
+  ): ReturnType<typeof setTimeout> | null {
+    const event_warn_ms = event_slow_timeout === null || event_slow_timeout <= 0 ? null : event_slow_timeout * 1000
     if (event_warn_ms === null) {
       return null
     }
-    const name = this.event_bus?.name ?? 'EventBus'
+    const name = bus_name ?? this.event_bus?.name ?? 'EventBus'
     return setTimeout(() => {
       if (this.event_status === 'completed') {
         return
@@ -528,7 +745,28 @@ export class BaseEvent {
   }
 
   private _isFirstModeWinningResult(entry: EventResult): boolean {
-    return entry.status === 'completed' && entry.result !== undefined && entry.result !== null && !(entry.result instanceof BaseEvent)
+    return BaseEvent._defaultResultInclude(entry.result, entry)
+  }
+
+  private static _defaultResultInclude<TEvent extends BaseEvent>(
+    result: EventResult<TEvent>['result'],
+    event_result: EventResult<TEvent>
+  ): boolean {
+    return (
+      event_result.status === 'completed' &&
+      result !== undefined &&
+      result !== null &&
+      !(result instanceof Error) &&
+      !(result instanceof BaseEvent) &&
+      event_result.error === undefined
+    )
+  }
+
+  private static _includeEventResult<TEvent extends BaseEvent>(
+    include: EventResultInclude<TEvent>,
+    event_result: EventResult<TEvent>
+  ): boolean {
+    return include(event_result.result, event_result)
   }
 
   private _markFirstModeWinnerIfNeeded(original: BaseEvent, entry: EventResult, first_state: { found: boolean }): void {
@@ -543,9 +781,13 @@ export class BaseEvent {
     if (!this.event_bus) {
       throw new Error('event has no bus attached')
     }
-    await this.event_bus.locks._runWithHandlerLock(original, this.event_bus.event_handler_concurrency, async (handler_lock) => {
-      await entry.runHandler(handler_lock)
-    })
+    await this.event_bus.locks._runWithHandlerLock(
+      original,
+      original.event_handler_concurrency ?? this.event_bus.event_handler_concurrency,
+      async (handler_lock) => {
+        await entry.runHandler(handler_lock)
+      }
+    )
   }
 
   // Run all pending handler results for the current bus context.
@@ -562,7 +804,7 @@ export class BaseEvent {
     }
     const resolved_completion = original.event_handler_completion ?? this.event_bus?.event_handler_completion ?? 'all'
     if (resolved_completion === 'first') {
-      if (original._getHandlerLock(this.event_bus?.event_handler_concurrency) !== null) {
+      if (original._getHandlerLock(original.event_handler_concurrency ?? this.event_bus?.event_handler_concurrency ?? 'serial') !== null) {
         for (const entry of pending_results) {
           await this._runHandlerWithLock(original, entry)
           if (!this._isFirstModeWinningResult(entry)) {
@@ -590,7 +832,7 @@ export class BaseEvent {
 
   _getHandlerLock(default_concurrency?: EventHandlerConcurrencyMode): AsyncLock | null {
     const original = this._event_original ?? this
-    const resolved = original.event_handler_concurrency ?? default_concurrency ?? original.event_bus?.event_handler_concurrency ?? 'serial'
+    const resolved = original.event_handler_concurrency ?? default_concurrency ?? 'serial'
     if (resolved === 'parallel') {
       return null
     }
@@ -715,7 +957,7 @@ export class BaseEvent {
       original_child._markCancelled(cancellation_cause)
 
       // Force-complete the child event. In JS we can't stop running async
-      // handlers, but _markCompleted() resolves the done() promise so callers
+      // handlers, but _markCompleted() resolves active waiters so callers
       // aren't blocked waiting for background work to finish. The background
       // handler's eventual _markCompleted/_markError is a no-op (terminal guard).
       if (original_child.event_status !== 'completed') {
@@ -732,11 +974,11 @@ export class BaseEvent {
     }
   }
 
-  // Cancel all handler results for an event except the winner, used by first() mode.
+  // Cancel all handler results for an event except the winner, used by event_handler_completion='first'.
   // Cancels pending handlers immediately, aborts started handlers via _signalAbort(),
   // and cancels any child events emitted by the losing handlers.
   _markRemainingFirstModeResultCancelled(winner: EventResult): void {
-    const cause = new Error('first() resolved: another handler returned a result first')
+    const cause = new Error("event_handler_completion='first' resolved: another handler returned a result first")
     const bus_id = winner.eventbus_id
 
     for (const result of this.event_results.values()) {
@@ -745,7 +987,7 @@ export class BaseEvent {
 
       if (result.status === 'pending') {
         result._markError(
-          new EventHandlerCancelledError(`Cancelled: first() resolved`, {
+          new EventHandlerCancelledError(`Cancelled: event_handler_completion='first' resolved`, {
             event_result: result,
             cause,
           })
@@ -763,7 +1005,7 @@ export class BaseEvent {
 
         // Abort the handler itself
         result._lock?.exitHandlerRun()
-        const aborted_error = new EventHandlerAbortedError(`Aborted: first() resolved`, {
+        const aborted_error = new EventHandlerAbortedError(`Aborted: event_handler_completion='first' resolved`, {
           event_result: result,
           cause,
         })
@@ -848,127 +1090,52 @@ export class BaseEvent {
     }
   }
 
-  // awaitable that triggers immediate (queue-jump) processing of the event on all buses where it is queued
-  // use eventCompleted() to wait for normal queue-order completion without queue-jumping.
-  done(options: EventDoneOptions = {}): Promise<this> {
-    if (!this.event_bus) {
-      return Promise.reject(new Error('event has no bus attached'))
+  private _withEventResultMethods(promise: Promise<this>): EventWaitPromise<this> {
+    const chainable = promise as EventWaitPromise<this>
+    chainable.eventResult = async (options?: EventResultOptions<this>) => {
+      const event = await promise
+      return event.eventResult(options)
     }
-    const original = this._event_original ?? this
-    original._markBlocksParentCompletionIfAwaitedFromEmittingHandler()
-    const raise_if_any = options.raise_if_any ?? true
-    const completion_promise =
-      this.event_status === 'completed' ? Promise.resolve(original as this) : this.event_bus._processEventImmediately(this)
-
-    if (!raise_if_any) {
-      return completion_promise
+    chainable.eventResultsList = async (options?: EventResultOptions<this>) => {
+      const event = await promise
+      return event.eventResultsList(options)
     }
+    return chainable
+  }
 
-    // Always delegate to _processEventImmediately — it walks up the parent event tree
-    // to determine whether we're inside a handler (works cross-bus). If no
-    // ancestor handler is in-flight, it falls back to eventCompleted().
-    return completion_promise.then((completed_event) => {
-      const first_error = completed_event._firstProcessingError()
-      if (first_error !== undefined) {
-        if (first_error instanceof Error) {
-          throw first_error
-        }
-        throw new Error(String(first_error))
-      }
-      return completed_event
-    })
+  private _timeoutPromise<T>(timeout: number | null, message: () => string, fn: () => Promise<T>): Promise<T> {
+    return timeout === null || timeout <= 0 ? fn() : _runWithTimeout(timeout, () => new Error(message()), fn)
   }
 
-  // returns the first non-undefined handler result value, cancelling remaining handlers
-  // when any handler completes. Works with all event_handler_concurrency modes:
-  //   parallel: races all handlers, returns first non-undefined, aborts the rest
-  //   serial: runs handlers sequentially, returns first non-undefined, skips remaining
-  first(): Promise<EventResultType<this> | undefined> {
-    if (!this.event_bus) {
-      return Promise.reject(new Error('event has no bus attached'))
-    }
+  private _orderedEventResults(): EventResult<this>[] {
     const original = this._event_original ?? this
-    original.event_handler_completion = 'first'
-    return this.done({ raise_if_any: false }).then((completed_event) => {
-      const first_error = completed_event._firstProcessingError({ ignore_first_mode_control_errors: true })
-      if (first_error !== undefined) {
-        if (first_error instanceof Error) {
-          throw first_error
-        }
-        throw new Error(String(first_error))
-      }
-      const orig = completed_event._event_original ?? completed_event
-      return Array.from(orig.event_results.values())
-        .filter(
-          (result) =>
-            result.status === 'completed' && result.result !== undefined && result.result !== null && !(result.result instanceof BaseEvent)
-        )
-        .sort((a, b) => compareIsoDatetime(a.completed_at, b.completed_at))
-        .map((result) => result.result as EventResultType<this>)
-        .at(0)
-    })
+    return (Array.from(original.event_results.values()) as EventResult<this>[]).sort((a, b) =>
+      compareIsoDatetime(a.completed_at, b.completed_at)
+    )
   }
 
-  // returns handler result values in event_results insertion order.
-  // equivalent to await event.done(); Array.from(event.event_results.values()).map((entry) => entry.result)
-  eventResultsList(
-    include: EventResultsListInclude<this>,
-    options?: EventResultsListOptions<this>
-  ): Promise<Array<EventResultType<this> | undefined>>
-  eventResultsList(options?: EventResultsListOptions<this>): Promise<Array<EventResultType<this> | undefined>>
-  async eventResultsList(
-    include_or_options?: EventResultsListInclude<this> | EventResultsListOptions<this>,
-    maybe_options?: EventResultsListOptions<this>
-  ): Promise<Array<EventResultType<this> | undefined>> {
-    const default_include: EventResultsListInclude<this> = (_result, event_result) =>
-      event_result.status === 'completed' &&
-      event_result.result !== undefined &&
-      event_result.result !== null &&
-      !(event_result.result instanceof Error) &&
-      !(event_result.result instanceof BaseEvent) &&
-      event_result.error === undefined
-
-    let options: EventResultsListOptions<this>
-    let include: EventResultsListInclude<this>
-    if (typeof include_or_options === 'function') {
-      options = maybe_options ?? {}
-      include = include_or_options
-    } else {
-      options = include_or_options ?? {}
-      include = options.include ?? default_include
-    }
-    const raise_if_any = options.raise_if_any ?? true
-    const raise_if_none = options.raise_if_none ?? true
-
+  private _orderedEventResultsByRegistration(): EventResult<this>[] {
     const original = this._event_original ?? this
-    const resolved_timeout_seconds = options.timeout ?? original.event_timeout ?? this.event_bus?.event_timeout ?? null
-    let completed_event: this
-
-    if (resolved_timeout_seconds === null) {
-      completed_event = await this.done({ raise_if_any: false })
-    } else {
-      completed_event = await _runWithTimeout(
-        resolved_timeout_seconds,
-        () => new Error(`Timed out waiting for ${original.event_type} results after ${resolved_timeout_seconds}s`),
-        () => this.done({ raise_if_any: false })
-      )
-    }
+    return (Array.from(original.event_results.values()) as EventResult<this>[]).sort(
+      (a, b) =>
+        compareIsoDatetime(a.handler.handler_registered_at, b.handler.handler_registered_at) ||
+        compareIsoDatetime(a.started_at, b.started_at) ||
+        a.handler_id.localeCompare(b.handler_id)
+    )
+  }
 
-    const all_results: EventResult<this>[] = Array.from(completed_event.event_results.values())
+  private _collectResultValues(
+    options: EventResultOptions<this> = {},
+    order: 'completion' | 'registration' = 'completion'
+  ): Array<EventResultType<this> | undefined> {
+    const include: EventResultInclude<this> = options.include ?? BaseEvent._defaultResultInclude
+    const raise_if_any = options.raise_if_any ?? true
+    const raise_if_none = options.raise_if_none ?? false
+    const all_results = order === 'registration' ? this._orderedEventResultsByRegistration() : this._orderedEventResults()
     const error_results = all_results.filter((event_result) => event_result.error !== undefined || event_result.result instanceof Error)
+    const included_results = all_results.filter((event_result) => BaseEvent._includeEventResult(include, event_result))
 
-    if (raise_if_any && error_results.length > 0) {
-      if (error_results.length === 1) {
-        const first_error = error_results[0]
-        if (first_error.error instanceof Error) {
-          throw first_error.error
-        }
-        if (first_error.result instanceof Error) {
-          throw first_error.result
-        }
-        throw new Error(String(first_error.error ?? first_error.result))
-      }
-
+    if (error_results.length > 0 && raise_if_any) {
       const errors = error_results.map((event_result) => {
         if (event_result.error instanceof Error) {
           return event_result.error
@@ -978,31 +1145,119 @@ export class BaseEvent {
         }
         return new Error(String(event_result.error ?? event_result.result))
       })
-      throw new AggregateError(
-        errors,
-        `Event ${completed_event.event_type}#${completed_event.event_id.slice(-4)} had ${errors.length} handler error(s)`
-      )
+      if (errors.length === 1) {
+        throw errors[0]
+      }
+      throw new AggregateError(errors, `Event ${this.event_type}#${this.event_id.slice(-4)} had ${errors.length} handler error(s)`)
     }
 
-    const included_results = all_results.filter((event_result) => include(event_result.result, event_result))
     if (raise_if_none && included_results.length === 0) {
       throw new Error(
-        `Expected at least one handler to return a non-null result, but none did: ${completed_event.event_type}#${completed_event.event_id.slice(-4)}`
+        `Expected at least one handler to return a non-null result, but none did: ${this.event_type}#${this.event_id.slice(-4)}`
       )
     }
 
     return included_results.map((event_result) => event_result.result)
   }
 
-  // awaitable that waits for the event to be processed in normal queue order by the _runloop
-  eventCompleted(): Promise<this> {
+  private _hasIncludedResult(options: EventResultOptions<this> = {}): boolean {
+    const include: EventResultInclude<this> = options.include ?? BaseEvent._defaultResultInclude
+    return this._orderedEventResults().some((event_result) => BaseEvent._includeEventResult(include, event_result))
+  }
+
+  private async _waitForFirstResultOrCompletion(options: EventWaitOptions & EventResultOptions<this> = {}): Promise<this> {
     const original = this._event_original ?? this
+    if (options.timeout !== undefined && options.timeout !== null && options.timeout < 0) {
+      throw new Error('timeout must be >= 0 or null')
+    }
+    if (!this.event_bus && original.event_status !== 'completed') {
+      throw new Error('event has no bus attached')
+    }
+    if (original.event_status === 'completed' || this._hasIncludedResult(options)) {
+      return this
+    }
+
+    const waitForResult = async (): Promise<this> => {
+      for (;;) {
+        if (original.event_status === 'completed' || this._hasIncludedResult(options)) {
+          return this
+        }
+        await new Promise((resolve) => setTimeout(resolve, 1))
+      }
+    }
+
+    const timeout = options.timeout ?? null
+    return this._timeoutPromise(timeout, () => `Timed out waiting for ${original.event_type} result after ${timeout}s`, waitForResult)
+  }
+
+  // Active awaitable that triggers immediate (queue-jump) processing of the event on all buses where it is queued.
+  now(options: EventWaitOptions = {}): EventWaitPromise<this> {
+    const original = this._event_original ?? this
+    if (options.timeout !== undefined && options.timeout !== null && options.timeout < 0) {
+      return this._withEventResultMethods(Promise.reject(new Error('timeout must be >= 0 or null')))
+    }
+    if (!this.event_bus && original.event_status !== 'completed') {
+      return this._withEventResultMethods(Promise.reject(new Error('event has no bus attached')))
+    }
     original._markBlocksParentCompletionIfAwaitedFromEmittingHandler()
-    if (this.event_status === 'completed') {
-      return Promise.resolve(this)
+    const resolved_timeout_seconds = options.timeout ?? null
+    const processing =
+      original.event_status === 'completed'
+        ? Promise.resolve(this)
+        : this._timeoutPromise(
+            resolved_timeout_seconds,
+            () => `Timed out waiting for ${original.event_type} completion after ${resolved_timeout_seconds}s`,
+            () => this.event_bus!._processEventImmediately(this)
+          )
+
+    if (options.first_result) {
+      void processing.catch(() => undefined)
+      return this._withEventResultMethods(this._waitForFirstResultOrCompletion(options))
+    }
+
+    return this._withEventResultMethods(processing)
+  }
+
+  // Passive awaitable that waits for normal queue-order processing without forcing execution.
+  wait(options: EventWaitOptions = {}): EventWaitPromise<this> {
+    const original = this._event_original ?? this
+    if (options.timeout !== undefined && options.timeout !== null && options.timeout < 0) {
+      return this._withEventResultMethods(Promise.reject(new Error('timeout must be >= 0 or null')))
+    }
+    if (!this.event_bus && original.event_status !== 'completed') {
+      return this._withEventResultMethods(Promise.reject(new Error('event has no bus attached')))
+    }
+    if (options.first_result) {
+      return this._withEventResultMethods(this._waitForFirstResultOrCompletion(options))
+    }
+    if (original.event_status === 'completed') {
+      return this._withEventResultMethods(Promise.resolve(this))
     }
     this._notifyDoneListeners()
-    return this._event_completed_signal!.promise
+    const timeout = options.timeout ?? null
+    return this._withEventResultMethods(
+      this._timeoutPromise(
+        timeout,
+        () => `Timed out waiting for ${original.event_type} completion after ${timeout}s`,
+        () => this._event_completed_signal!.promise.then(() => this)
+      )
+    )
+  }
+
+  async eventResult(options: EventResultOptions<this> = {}): Promise<EventResultType<this> | undefined> {
+    const original = this._event_original ?? this
+    if (original.event_status === 'pending' && original.event_results.size === 0) {
+      await this.now({ first_result: true })
+    }
+    return this._collectResultValues(options, 'registration').at(0)
+  }
+
+  async eventResultsList(options: EventResultOptions<this> = {}): Promise<Array<EventResultType<this> | undefined>> {
+    const original = this._event_original ?? this
+    if (original.event_status === 'pending' && original.event_results.size === 0) {
+      await this.now({ first_result: false })
+    }
+    return this._collectResultValues(options, 'registration')
   }
 
   _markBlocksParentCompletionIfAwaitedFromEmittingHandler(): void {
@@ -1115,36 +1370,14 @@ export class BaseEvent {
     )
   }
 
-  private _isFirstModeControlError(error: unknown): boolean {
-    if (!(error instanceof EventHandlerCancelledError || error instanceof EventHandlerAbortedError)) {
-      return false
-    }
-    if (error.message.includes('first() resolved')) {
-      return true
-    }
-    return error.cause instanceof Error && error.cause.message.includes('first() resolved')
-  }
-
-  _firstProcessingError(options: { ignore_first_mode_control_errors?: boolean } = {}): unknown | undefined {
-    const ignore_first_mode_control_errors = options.ignore_first_mode_control_errors ?? false
+  _firstProcessingError(): unknown | undefined {
     return Array.from(this.event_results.values())
       .filter((event_result) => event_result.error !== undefined && event_result.completed_at !== null)
-      .filter((event_result) => (ignore_first_mode_control_errors ? !this._isFirstModeControlError(event_result.error) : true))
       .sort((event_result_a, event_result_b) => compareIsoDatetime(event_result_a.completed_at, event_result_b.completed_at))
       .map((event_result) => event_result.error)
       .at(0)
   }
 
-  // Returns the first non-undefined completed handler result, sorted by completion time.
-  // Useful after first() or done() to get the winning result value.
-  get event_result(): EventResultType<this> | undefined {
-    return Array.from(this.event_results.values())
-      .filter((event_result) => event_result.completed_at !== null && event_result.result !== undefined)
-      .sort((event_result_a, event_result_b) => compareIsoDatetime(event_result_a.completed_at, event_result_b.completed_at))
-      .map((event_result) => event_result.result as EventResultType<this>)
-      .at(0)
-  }
-
   _areAllChildrenComplete(visited: Set<string> = new Set()): boolean {
     const original = this._event_original ?? this
     if (visited.has(original.event_id)) {