@makaio/framework 1.0.0-dev-1779046984397

package/dist/bus/index.d.mts

@@ -0,0 +1,3331 @@
+import * as _$zod from "zod";
+import { ZodType, z } from "zod";
+import { Paths, Simplify, UnknownRecord } from "type-fest";
+import * as _$zod_v4_core0 from "zod/v4/core";
+
+//#region packages/makaio-core/src/types/message.d.ts
+/**
+ * Host-agnostic principal attached by a trusted local transport.
+ *
+ * The framework treats this as opaque metadata. Host code decides what
+ * principal kinds and claims mean.
+ */
+interface PrincipalContext {
+  /** Principal kind, such as `user`, `device`, `machine`, or host-defined values. */
+  readonly kind: string;
+  /** Optional stable principal identifier in the principal namespace. */
+  readonly id?: string;
+  /** Optional opaque claims supplied by the authenticating transport or host policy. */
+  readonly claims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Authenticated peer metadata supplied by a transport connection.
+ */
+interface TransportPeerContext {
+  /** Peer kind, such as `browser`, `machine`, `worker`, or host-defined values. */
+  readonly kind: string;
+  /** Optional transport-level peer identifier. */
+  readonly id?: string;
+  /** Whether the receiving transport authenticated the peer. */
+  readonly authenticated?: boolean;
+  /** Whether the receiving transport established encrypted payload transport. */
+  readonly encrypted?: boolean;
+  /** Optional opaque peer claims. */
+  readonly claims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Trusted context derived locally by the receiving transport.
+ *
+ * This context is never serialized into `BusMessage`; each receiving node must
+ * derive its own context from its own transport/session state.
+ */
+interface TransportReceiveContext {
+  /** Registered bus transport name that received the message. */
+  readonly transportName: string;
+  /** Optional connection/session identifier local to the transport. */
+  readonly connectionId?: string;
+  /** Optional authenticated transport peer. */
+  readonly peer?: TransportPeerContext;
+  /** Optional host-agnostic principal resolved for this connection. */
+  readonly principal?: PrincipalContext;
+}
+/**
+ * Base message context interface for both events and requests.
+ *
+ * Provides common metadata for tracking and correlation:
+ * - `messageId`: Unique identifier for this specific message
+ * - `correlationId`: Optional identifier linking related operations
+ */
+interface BaseMessageContext {
+  /**
+   * Unique identifier for this specific message.
+   * Auto-generated if not provided.
+   *
+   * Used for:
+   * - Message deduplication
+   * - Idempotency checks
+   * - Tracking individual messages in logs
+   */
+  messageId: string;
+  /**
+   * Optional identifier linking related operations.
+   * Propagated through chains of requests/events.
+   *
+   * Used for:
+   * - Distributed tracing
+   * - Causality tracking
+   * - Following a workflow through the system
+   * @example
+   * ```typescript
+   * // Initial request generates correlationId
+   * const result = await request(
+   *   UserSubjects.getUser,
+   *   { userId: '42' },
+   *   { correlationId: 'user-action-123' }
+   * );
+   *
+   * // Handler propagates correlationId to downstream operations
+   * await emit(
+   *   UserSubjects.userLoaded,
+   *   { user: result },
+   *   { correlationId: context.correlationId }
+   * );
+   * ```
+   */
+  correlationId?: string;
+  /**
+   * Trusted context supplied by the local receiving transport.
+   *
+   * Undefined for local calls and for transports that do not supply connection
+   * context. Never trust similarly named fields in payloads or wire messages.
+   */
+  transport?: TransportReceiveContext;
+  isRequest: boolean;
+}
+type EventMessagePayload<Payload extends UnknownRecord = UnknownRecord> = Payload & {
+  request?: never;
+  response?: never;
+};
+type RequestMessagePayload<Request extends UnknownRecord = UnknownRecord, Response extends UnknownRecord = UnknownRecord> = {
+  request: Request;
+  response: Response;
+};
+type MessagePayload = RequestMessagePayload | EventMessagePayload;
+//#endregion
+//#region packages/makaio-core/src/types/context.d.ts
+/**
+ * Context object passed to event handlers when using wildcard patterns.
+ *
+ * Provides:
+ * - `isRequest`: Always false (discriminator for type narrowing)
+ * - `payload`: The event payload
+ * - Message tracking fields from BaseMessage (messageId, correlationId)
+ */
+interface EventContext<Payload> extends BaseMessageContext {
+  /** Discriminator - always false for events */
+  isRequest: false;
+  /** The event payload */
+  payload: Payload;
+  /** The event subject */
+  subject: string;
+}
+/**
+ * Context object passed to request handlers.
+ *
+ * Provides:
+ * - `isRequest`: Always true (discriminator for type narrowing)
+ * - `payload`: The request payload
+ * - `setResult`: Function to set the response value
+ * - `next`: Function to call the next handler in the middleware chain
+ * - `replacePayload`: Function to transform the payload for subsequent handlers
+ * - `identify`: Optional function to identify the handler for broadcast aggregation
+ * - Message tracking fields from BaseMessage (messageId, correlationId)
+ */
+interface RequestContext<Payload, Response> extends BaseMessageContext {
+  /** Discriminator - always true for requests */
+  isRequest: true;
+  /** The request payload */
+  payload: Payload;
+  /** Set the response value (ends the handler chain) */
+  setResult: (result: Response) => void;
+  /**
+   * Read the current result value.
+   *
+   * Returns the value set by `setResult()` in this handler or by a downstream
+   * handler after `await next()`. Undefined until a result has been set.
+   */
+  readonly result: Response | undefined;
+  /**
+   * Shallow-merge additional fields into the current result.
+   *
+   * Only valid for object-typed responses. In the request path the operation
+   * uses spread (immutable); in broadcast mode it uses `Object.assign`
+   * (in-place mutation) so the already-pushed result reference stays current.
+   * If no result has been set yet, starts from an empty object.
+   * @param extension - Fields to merge into the current result
+   */
+  extendResult: (extension: [Response] extends [Record<string, unknown>] ? Partial<Response> : never) => void;
+  /**
+   * Call the next handler in the middleware chain.
+   * If no more handlers exist, throws NoHandlerError.
+   */
+  next: () => Promise<void>;
+  /**
+   * Replace the payload with a new value.
+   * Subsequent handlers in the middleware chain will receive the new payload.
+   * Useful for hooks that need to inject context before the main handler runs.
+   */
+  replacePayload: (newPayload: Payload) => void;
+  /**
+   * Identify this handler for broadcast aggregation.
+   * Only present when called via broadcast() - call before setResult().
+   * @param nodeId - Unique identifier for this handler/node
+   */
+  identify?: (nodeId: string) => void;
+}
+/**
+ * Unified context for wildcard handlers that can match both events and requests.
+ * Use the `isRequest` discriminator to narrow the type.
+ * @example
+ * ```typescript
+ * MakaioBus.on('adapter.*', (context) => {
+ *   if (context.isRequest) {
+ *     // TypeScript knows this is RequestContext
+ *     context.setResult({ handled: true });
+ *   } else {
+ *     // TypeScript knows this is EventContext
+ *     console.debug('Event:', context.payload);
+ *   }
+ * });
+ * ```
+ */
+type WildcardContext<Payload = unknown, Response = unknown> = EventContext<Payload> | RequestContext<Payload, Response>;
+//#endregion
+//#region packages/makaio-core/src/types/filter.d.ts
+type Primitive = string | number | boolean | null;
+/**
+ * Filter operators for payload field matching.
+ * @example
+ * ```typescript
+ * // Equality (implicit)
+ * { agentId: 'agent-123' }
+ *
+ * // Membership
+ * { status: { $in: ['active', 'pending'] } }
+ *
+ * // Not equal
+ * { type: { $ne: 'internal' } }
+ *
+ * // Presence check
+ * { error: { $exists: false } }
+ *
+ * // String prefix/suffix matching
+ * { path: { $startsWith: '.git/' } }
+ * { file: { $endsWith: '.ts' } }
+ * ```
+ */
+type FilterOperator<T extends Primitive = Primitive> = T | {
+  $in: T[];
+} | {
+  $ne: T;
+} | {
+  $exists: boolean;
+} | {
+  $startsWith: string;
+} | {
+  $endsWith: string;
+};
+/**
+ * Untyped payload filter - accepts any string keys.
+ * Use TypedPayloadFilter<T> for type-safe filters.
+ */
+type PayloadFilter = Record<string, FilterOperator>;
+/**
+ * Type-safe payload filter constrained to valid paths of a payload type.
+ *
+ * Uses type-fest's `Paths` to support dotted path notation for nested fields.
+ * @example
+ * ```typescript
+ * interface McpPayload {
+ *   agentId: string;
+ *   raw: { msg: { type: string } };
+ * }
+ *
+ * // Type-safe - validates both top-level and nested paths
+ * const filter: TypedPayloadFilter<McpPayload> = {
+ *   agentId: 'agent-123',
+ *   'raw.msg.type': 'session_configured',  // ✅ valid path
+ *   'raw.msg.typo': 'x',                   // ❌ type error
+ * };
+ * ```
+ */
+type TypedPayloadFilter<T> = { [K in Paths<T> & string]?: FilterOperator };
+//#endregion
+//#region packages/makaio-core/src/types/schema.d.ts
+/**
+ * Schema definition for event subjects (fire-and-forget).
+ * Events have only a payload schema, no response.
+ * The payload is now separate from the context, so no restrictions needed.
+ */
+type EventSchema = z.ZodType;
+/**
+ * Schema definition for request subjects (request-response).
+ * Requests have both a request payload schema and a response schema.
+ */
+type RequestSchema<Request extends ZodType = ZodType, Response extends ZodType = ZodType> = {
+  request: Request;
+  response: Response;
+};
+/**
+ * Wrapper to mark a subject as local-only (never sent to transports).
+ *
+ * Use `localSubject()` from `@makaio/bus-core` to create these.
+ * @example
+ * ```typescript
+ * import { localSubject } from '@makaio/framework/bus';
+ *
+ * const WidgetSchemas = {
+ *   register: localSubject(widgetDefinitionSchema),  // local event
+ *   unregister: localSubject(z.object({ widgetId: z.string() })),
+ * };
+ * ```
+ */
+type LocalSubjectSchema<T extends EventSchema | RequestSchema = EventSchema | RequestSchema> = {
+  readonly __local: true;
+  readonly schema: T;
+};
+/**
+ * Wrapper to mark a subject as channel-only (encrypted point-to-point).
+ *
+ * Channel subjects are rejected by public bus methods and are only
+ * routable through the DirectChannel encrypted transport. Use
+ * `channelSubject()` from `@makaio/bus-core` to create these.
+ * @example
+ * ```typescript
+ * import { channelSubject } from '@makaio/framework/bus';
+ *
+ * const DirectSchemas = {
+ *   message: channelSubject(z.object({ text: z.string() })),
+ *   ping: channelSubject({
+ *     request: z.object({ ts: z.number() }),
+ *     response: z.object({ ts: z.number() }),
+ *   }),
+ * };
+ * ```
+ */
+type ChannelSubjectSchema<T extends EventSchema | RequestSchema = EventSchema | RequestSchema> = {
+  readonly __channel: true;
+  readonly schema: T;
+};
+/**
+ * Base schema types (unwrapped).
+ */
+type BaseSubjectSchema = EventSchema | RequestSchema;
+/**
+ * Union of all subject schema types (including local and channel wrappers).
+ */
+type SubjectSchema = BaseSubjectSchema | LocalSubjectSchema | ChannelSubjectSchema;
+type SchemaRecord = Record<string, SubjectSchema>;
+//#endregion
+//#region packages/makaio-core/src/types/type-helpers.d.ts
+/**
+ * Unwrap LocalSubjectSchema or ChannelSubjectSchema wrappers if present.
+ * Returns the inner schema for wrapped subjects, or the schema as-is otherwise.
+ */
+type UnwrapSchema<S> = S extends {
+  readonly __local: true;
+  readonly schema: infer Inner;
+} ? Inner : S extends {
+  readonly __channel: true;
+  readonly schema: infer Inner;
+} ? Inner : S;
+/**
+ * Infer payload type from schema (handles EventSchema, RequestSchema,
+ * LocalSubjectSchema, and ChannelSubjectSchema).
+ *
+ * For requests:
+ * - Uses z.input for request (what callers pass before validation/defaults)
+ * - Uses z.infer for response (what handlers return after processing)
+ *
+ * This allows schemas with .default() to have optional fields in the caller API
+ * while the response type reflects the validated output.
+ *
+ * LocalSubjectSchema and ChannelSubjectSchema wrappers are automatically
+ * unwrapped before inference.
+ *
+ * Idempotent: Returns already-inferred types as-is.
+ */
+type InferSchemaPayload<S extends SubjectSchema> = InferSchemaPayloadInner<UnwrapSchema<S>>;
+type InferSchemaPayloadInner<S> = S extends {
+  request: infer Req extends z.ZodType;
+  response: infer Res extends z.ZodType;
+} ? {
+  request: z.input<Req>;
+  response: z.infer<Res>;
+} : S extends z.ZodType ? Simplify<z.infer<S>> : unknown;
+/**
+ * Compute all subject meta from the original schema in one place.
+ *
+ * Resolves payload, locality, channel membership, request/event discriminator,
+ * and namespace from a raw SubjectSchema.
+ * @typeParam S - The subject schema type
+ * @typeParam Ns - The namespace string
+ */
+type InferSubjectMeta<S extends SubjectSchema, Ns extends string> = {
+  /** True when the subject is a request-response pair, false for events. */isRequest: UnwrapSchema<S> extends {
+    request: z.ZodType;
+    response: z.ZodType;
+  } ? true : false; /** True when the subject is wrapped with `localSubject()`. */
+  local: S extends LocalSubjectSchema ? true : false; /** True when the subject is wrapped with `channelSubject()`. */
+  channel: S extends ChannelSubjectSchema ? true : false; /** Inferred payload type (request/response pair or event payload). */
+  payload: InferSchemaPayload<S>; /** The namespace this subject belongs to. */
+  namespace: Ns;
+};
+//#endregion
+//#region packages/makaio-core/src/types/subjects.d.ts
+type SubjectRecord<SubjectKeys extends string = string, Payload extends MessagePayload = MessagePayload> = Record<SubjectKeys, Payload>;
+type SubjectRecordFromSchemaRecord<SchemaRecord extends Record<string, SubjectSchema>> = { [K in keyof SchemaRecord & string]: Simplify<InferSchemaPayload<SchemaRecord[K]>> };
+type SubjectDefinitionMeta<Subject extends SubjectRecord = SubjectRecord<'default'>, K extends keyof Subject = keyof Subject, Namespace extends string = string> = {
+  isRequest: Subject extends SubjectRecord<'default'> ? boolean : Subject[K] extends RequestMessagePayload ? true : false;
+  payload: K extends string ? Subject[K] : unknown;
+  namespace: Namespace;
+  /**
+   * If true, this subject is local-only and will never be sent to transports.
+   * Use for subjects whose payloads contain non-serializable data (e.g., React components).
+   */
+  local: boolean;
+  /**
+   * If true, this subject is channel-only and is only routable through the
+   * DirectChannel encrypted point-to-point transport.
+   */
+  channel: boolean;
+};
+type SubjectDefinition<Subject extends SubjectRecord = SubjectRecord, SubjectKey extends keyof Subject = keyof Subject, Namespace extends string = string> = {
+  $meta: SubjectDefinitionMeta<Subject, SubjectKey, Namespace>;
+  subject: SubjectKey;
+};
+type ScopedSubjectDefinition<Namespace extends string = string> = SubjectDefinition<SubjectRecord, keyof SubjectRecord, Namespace>;
+/**
+ * Extract the filterable payload from a MessagePayload.
+ * For requests, returns the request part (what we filter on).
+ * For events, returns the payload as-is.
+ */
+type FilterablePayload<P> = P extends RequestMessagePayload ? P['request'] : P;
+/**
+ * Union of all filterable payloads from a SubjectRecord.
+ */
+type FilterablePayloadsUnion<Subjects extends SubjectRecord> = FilterablePayload<Subjects[keyof Subjects]>;
+/**
+ * Extract keys from ANY member of a union type (distributive).
+ *
+ * For `{ a: 1, b: 2 } | { a: 1, c: 3 }`, returns `'a' | 'b' | 'c'`.
+ */
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+/**
+ * Extract value type for a key from union members that have it.
+ */
+type ValueOfKey<T, K extends PropertyKey> = T extends { [P in K]: infer V } ? V : never;
+/**
+ * Build an object type with ALL keys from ANY union member.
+ *
+ * For `{ type: 'a', id: string } | { type: 'b', name: string }`:
+ * Result = `{ type: 'a' | 'b', id: string, name: string }`
+ *
+ * Allows filtering by any key that exists in any payload.
+ */
+type AllPropertiesOfUnion<T> = { [K in KeysOfUnion<T>]: ValueOfKey<T, K> };
+/**
+ * Union of all filterable payload properties from a SubjectRecord.
+ *
+ * Collects ALL keys from ANY payload, allowing filtering by any field.
+ * Events without a filtered key simply won't match.
+ * @example
+ * ```typescript
+ * // Given subjects with payloads:
+ * // - 'event': { agentId: string, foo: number }
+ * // - 'request': { sessionId: string }
+ *
+ * // FilterablePayloadUnion = { agentId: string, foo: number, sessionId: string }
+ *
+ * // Filter can use any key from any payload
+ * bus.withFilter({ agentId: 'x' }); // ✅ matches events with agentId
+ * bus.withFilter({ sessionId: 'y' }); // ✅ matches requests with sessionId
+ * ```
+ */
+type FilterablePayloadIntersection<Subjects extends SubjectRecord> = Simplify<AllPropertiesOfUnion<FilterablePayloadsUnion<Subjects>>>;
+//#endregion
+//#region packages/makaio-core/src/types/wildcards.d.ts
+type WildcardSubject = '*';
+type WildcardSubjectDefinition<Namespace extends string = string> = SubjectDefinition<Record<'*', MessagePayload>, WildcardSubject, Namespace>;
+//#endregion
+//#region packages/makaio-core/src/types/handler-types.d.ts
+type EventHandler<T> = (context: EventContext<T>) => void | Promise<void>;
+type RequestHandler<Payload, Response> = (context: RequestContext<Payload, Response>) => void | Promise<void>;
+/**
+ * Context provided to __onAny handlers for debugging/testing.
+ * Captures all message metadata regardless of type (event/request/broadcast).
+ */
+interface AnyMessageContext {
+  type: 'event' | 'request' | 'broadcast';
+  subject: string;
+  namespace: string;
+  payload: unknown;
+  messageId: string;
+  correlationId?: string;
+}
+/**
+ * Handler for __onAny - receives all messages (events and requests) across all namespaces.
+ * Used for debugging and testing only.
+ */
+type AnyHandler = (context: AnyMessageContext) => void | Promise<void>;
+/**
+ * Special handler for wildcards that match both events and requests.
+ * @public
+ */
+type WildcardUnifiedHandler = (context: WildcardContext<unknown, unknown>) => void | Promise<void>;
+/**
+ * Resolve the appropriate handler type for a subject pattern (exact or wildcard).
+ *
+ * Handles all subscription patterns:
+ * - Event wildcards (`adapter.*`) → `(payload: unknown) => void | Promise<void>`
+ * - Request wildcards (`adapter.*`) → `(context: RequestContext<unknown, unknown>) => void | Promise<void>`
+ * - Exact request subjects → `RequestHandler<TPayload, TReturnValue>`
+ * - Exact event subjects → `EventHandler<TPayload>`
+ *
+ * This is the primary type used by the `on()` method to resolve handler signatures.
+ * @example
+ * ```typescript
+ * // Event wildcard - unknown payload
+ * type Handler1 = HandlerForPattern<'adapter.*'>;
+ * // (payload: unknown) => void | Promise<void>
+ *
+ * // Exact event subject - typed payload
+ * type Handler2 = HandlerForPattern<'adapter.log'>;
+ * // EventHandler<{ message: string, level: string }>
+ *
+ * // Request wildcard - unknown context
+ * type Handler3 = HandlerForPattern<'adapter.*'>;
+ * // (context: RequestContext<unknown, unknown>) => void | Promise<void>
+ *
+ * // Exact request subject - typed context
+ * type Handler4 = HandlerForPattern<'adapter.getCapabilities'>;
+ * // RequestHandler<{ adapterName: string }, { capabilities: string[] }>
+ * ```
+ */
+/**
+ * Resolve the handler type for a SubjectDefinition.
+ *
+ * Uses indexed access (`T['$meta']['payload']`) instead of nested `extends` with `infer`
+ * to ensure proper type resolution when T is a generic type parameter.
+ */
+type HandlerForSubjectDefinition<T extends SubjectDefinition> = T['subject'] extends WildcardSubject ? WildcardUnifiedHandler : T['$meta']['payload'] extends RequestMessagePayload<infer Request, infer Response> ? RequestHandler<Request, Response> : T['$meta']['payload'] extends EventMessagePayload<infer Payload> ? EventHandler<Payload> : never;
+/**
+ * Extract context type for once() promise return value.
+ *
+ * Uses the same pattern as HandlerForSubjectDefinition for consistency.
+ */
+type ContextForSubjectDefinition<T extends SubjectDefinition> = T['subject'] extends WildcardSubject ? WildcardContext<unknown, unknown> : T['$meta']['payload'] extends RequestMessagePayload<infer Request, infer Response> ? RequestContext<Request, Response> : T['$meta']['payload'] extends EventMessagePayload<infer Payload> ? EventContext<Payload> : never;
+//#endregion
+//#region packages/makaio-core/src/types/result.d.ts
+/**
+ * Result types for optional request handling.
+ *
+ * Used by requestOptional to distinguish between "handler returned data"
+ * and "no handler was registered".
+ */
+/**
+ * Discriminated union for optional request results.
+ *
+ * - `handled: true` - A handler was found and returned data
+ * - `handled: false` - No handler was registered for the subject
+ * @example
+ * ```typescript
+ * const result = await bus.requestOptional(Subjects.getData, { id: '123' });
+ * if (result.handled) {
+ *   console.debug('Got data:', result.data);
+ * } else {
+ *   console.debug('No handler registered for getData');
+ * }
+ * ```
+ */
+type OptionalResult<T> = {
+  handled: true;
+  data: T;
+} | {
+  handled: false;
+};
+//#endregion
+//#region packages/makaio-core/src/subject-helpers/nest-subject-definitions.d.ts
+/**
+ * Recursively nests a flat record of dotted keys into a hierarchical object type.
+ *
+ * ```
+ * { 'assistant.text': SubjectDef, 'agent.tool.started': SubjectDef }
+ * → { assistant: { text: SubjectDef }, agent: { tool: { started: SubjectDef } } }
+ * ```
+ *
+ * Used to expose registered subjects as a nested accessor tree (e.g.
+ * `BootSubjects.service.ready`) without requiring callers to deal with
+ * flat dotted-key strings at the type level.
+ */
+type NestedSubjectDefinitions<T extends Record<string, unknown> = Record<string, SubjectDefinition>> = { [K in ExtractPrefixes<keyof T & string>]: NestByPrefix<T, K> };
+type ExtractPrefixes<Keys extends string> = Keys extends `${infer Prefix}.${string}` ? Prefix : Keys;
+type StripPrefixMap<T, Prefix extends string> = { [K in keyof T as K extends `${Prefix}.${infer Rest}` ? Rest : never]: T[K] };
+type NestByPrefix<T extends Record<string, unknown>, Prefix extends string> = Prefix extends keyof T ? T[Prefix] : NestedSubjectDefinitions<StripPrefixMap<T, Prefix>>;
+/**
+ * Maps a flat schema record to a flat subject-definition record, attaching the
+ * correct `$meta` (namespace, isRequest, local, channel) and `subject` key for
+ * each entry.
+ *
+ * Intermediate type used by {@link nestSubjectDefinitions} before nesting.
+ * @typeParam Domain - Namespace domain string (e.g. `'boot'`)
+ * @typeParam Schemas - Flat record of raw Zod schemas keyed by dotted subject names
+ */
+type FlatSubjectDefinitions<Domain extends string, Schemas extends Record<string, SubjectSchema>> = { [K in keyof Schemas & string]: {
+  $meta: InferSubjectMeta<Schemas[K], Domain>;
+  subject: K;
+} };
+/**
+ * Fully-nested subject accessor tree returned by `registerNamespace`.
+ *
+ * Combines the {@link NestedSubjectDefinitions} hierarchy with a `$all`
+ * wildcard that matches every subject in the namespace. Consumers use this
+ * type to write `SomeNamespace.subjects.foo.bar` instead of raw strings.
+ * @typeParam RecordOfSubjectDefinitions - Flat record of subject definitions
+ * @typeParam Domain - Namespace domain string used for `$all` wildcard typing
+ */
+type BusSubjects<RecordOfSubjectDefinitions extends Record<string, unknown> = Record<string, SubjectDefinition>, Domain extends string = string> = NestedSubjectDefinitions<RecordOfSubjectDefinitions> & {
+  $all: WildcardSubjectDefinition<Domain>;
+};
+/**
+ * Gets the fully qualified subject name in namespace.subject format.
+ * @param subject - The subject definition to format
+ * @returns The full subject string in the format "namespace.subject"
+ */
+declare function getFullSubjectForSubjectDefinition(subject: SubjectDefinition): string;
+//#endregion
+//#region packages/makaio-core/src/subject-helpers/is-request-schema.d.ts
+/**
+ * Type guard to check if a schema is a request schema.
+ * @param schema - The schema to check
+ * @returns True if the schema is a RequestSchema, false otherwise
+ */
+declare function isRequestSchema(schema: SubjectSchema): schema is RequestSchema;
+//#endregion
+//#region packages/makaio-core/src/subject-helpers/is-local-schema.d.ts
+/**
+ * Create a local-only subject schema wrapper.
+ *
+ * Local subjects are never sent to transports (SharedWorker, WebSocket, etc.).
+ * Use this for subjects whose payloads contain non-serializable data like
+ * React components or functions.
+ * @param schema - The event or request schema to mark as local
+ * @returns A LocalSubjectSchema wrapper
+ * @example
+ * ```typescript
+ * import { localSubject } from '@makaio/framework/core';
+ *
+ * const WidgetSchemas = {
+ *   // Local event - contains React component, can't be serialized
+ *   register: localSubject(widgetDefinitionSchema),
+ *
+ *   // Local request - response contains functions
+ *   getRenderer: localSubject({
+ *     request: z.object({ widgetId: z.string() }),
+ *     response: z.object({ render: z.function() }),
+ *   }),
+ * };
+ * ```
+ */
+declare function localSubject<T extends EventSchema | RequestSchema>(schema: T): LocalSubjectSchema<T>;
+//#endregion
+//#region packages/makaio-core/src/subject-helpers/is-channel-schema.d.ts
+/**
+ * Create a channel-only subject schema wrapper.
+ *
+ * Channel subjects are rejected by public bus methods and are only
+ * routable through the DirectChannel encrypted point-to-point transport.
+ * Use this for subjects that must never travel over the public bus.
+ * @param schema - The event or request schema to mark as channel-only
+ * @returns A ChannelSubjectSchema wrapper
+ * @example
+ * ```typescript
+ * import { channelSubject } from '@makaio/framework/core';
+ *
+ * const DirectSchemas = {
+ *   // Channel event - encrypted, point-to-point only
+ *   message: channelSubject(z.object({ text: z.string() })),
+ *
+ *   // Channel request - encrypted request-response pair
+ *   ping: channelSubject({
+ *     request: z.object({ ts: z.number() }),
+ *     response: z.object({ ts: z.number() }),
+ *   }),
+ * };
+ * ```
+ */
+declare function channelSubject<T extends EventSchema | RequestSchema>(schema: T): ChannelSubjectSchema<T>;
+//#endregion
+//#region packages/makaio-core/src/bus-namespace-definition.d.ts
+/**
+ * Report passed to the {@link NamespaceRegistrationOptions} `onSchemaViolation` callback
+ * when lenient validation detects a schema mismatch.
+ *
+ * Canonical owner: `@makaio/core`. `@makaio/bus-core` imports this type from core.
+ */
+interface SchemaViolationReport {
+  /** Fully-qualified subject key (e.g., `"adapter:claude-code.sdk.event"`) */
+  subject: string;
+  /** Raw payload that failed validation */
+  payload: unknown;
+  /** Individual Zod issues from the failed parse */
+  issues: unknown[];
+}
+/**
+ * Options controlling runtime schema validation for a registered bus namespace.
+ *
+ * - `strict` (default) — throw `ValidationError` on schema mismatch
+ * - `lenient` — invoke `onSchemaViolation` callback, then deliver the event anyway
+ * - `skip` — no validation at all (for cross-Zod-version scenarios, e.g., SDK bundles Zod v3)
+ *
+ * Canonical owner: `@makaio/core`. `@makaio/bus-core` imports this type from core,
+ * not the other way around. Single source of truth — no mirroring.
+ */
+type NamespaceRegistrationOptions = {
+  busValidationMode?: 'strict';
+} | {
+  busValidationMode: 'lenient';
+  onSchemaViolation: (report: SchemaViolationReport) => void;
+} | {
+  busValidationMode: 'skip';
+};
+/**
+ * A declarative bus namespace definition.
+ *
+ * Created by {@link createBusNamespace}. Carries typed subject tokens for
+ * immediate use in bus operations, plus the original schemas for deferred
+ * registration at boot time via `MakaioBus.registerNamespace()`.
+ *
+ * Does not include `scopedBus()` — that method requires a bus instance and
+ * is available on the `BusNamespace` object returned by `registerNamespace()`.
+ * @typeParam Domain - Namespace domain string (e.g. `'adapter'`, `'session'`)
+ * @typeParam Schemas - Schema record mapping subject keys to Zod schemas
+ */
+interface BusNamespaceDefinition<Domain extends string = string, Schemas extends Record<string, SubjectSchema> = Record<string, SubjectSchema>> {
+  /** Namespace domain string (e.g., `'adapter'`, `'session'`) */
+  readonly name: Domain;
+  /**
+   * Typed subject tokens for bus operations — no registration needed to use
+   * these for `bus.on()`, `bus.emit()`, or `bus.request()`.
+   */
+  readonly subjects: BusSubjects<FlatSubjectDefinitions<Domain, Schemas>, Domain>;
+  /** Original Zod schemas — carried for deferred registration */
+  readonly schemas: Schemas;
+  /** Registration options (validation mode, violation callback) */
+  readonly options?: NamespaceRegistrationOptions;
+  /**
+   * Phantom field for type inference of filterable payload shape.
+   *
+   * Never set at runtime. Exists solely so TypeScript can infer the
+   * `FilterPayload` type parameter from the schema record without an
+   * explicit annotation at every callsite.
+   * @internal
+   */
+  readonly __filterPayload?: FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>;
+}
+/**
+ * Namespace definition shape required for runtime registration.
+ *
+ * Structurally derived from {@link BusNamespaceDefinition} with the typed
+ * subject tree erased to `unknown`. Composition-root catalogs and extension
+ * manifests only need the namespace name, schemas, options, and the runtime
+ * subject tokens; keeping this structural type separate lets those catalogs
+ * contain heterogeneous namespace definitions without widening every subject
+ * tree to an unsafe index signature.
+ */
+type RegistrableBusNamespaceDefinition = Omit<BusNamespaceDefinition, 'subjects' | '__filterPayload'> & {
+  /** Runtime subject token tree created by `createBusNamespace`. */readonly subjects: unknown;
+};
+//#endregion
+//#region packages/makaio-core/src/errors/index.d.ts
+/**
+ * Base error class for all Makaio-related errors.
+ */
+declare class MakaioError extends Error {
+  readonly subject?: string | undefined;
+  constructor(message: string, subject?: string | undefined);
+}
+//#endregion
+//#region packages/bus-core/src/extend-subject.d.ts
+/**
+ * Additional fields to add to a request subject's request and/or response schemas.
+ * Omit either key to leave that side unchanged.
+ */
+interface RequestSubjectExtension {
+  request?: Record<string, z.ZodType>;
+  response?: Record<string, z.ZodType>;
+}
+/**
+ * Additional fields to add to an event subject's payload schema.
+ */
+type EventSubjectExtension = Record<string, z.ZodType>;
+/**
+ * Infers the correct extension shape based on whether the subject is a request or event.
+ */
+type SubjectExtension<SD extends SubjectDefinition> = SD['$meta']['isRequest'] extends true ? RequestSubjectExtension : EventSubjectExtension;
+type ExtendWithInput<Original, Ext extends Record<string, z.ZodType>> = Omit<Original, keyof Ext> & { [K in keyof Ext as undefined extends z.input<Ext[K]> ? never : K]: z.input<Ext[K]> } & { [K in keyof Ext as undefined extends z.input<Ext[K]> ? K : never]?: z.input<Ext[K]> };
+type ExtendWithInfer<Original, Ext extends Record<string, z.ZodType>> = Omit<Original, keyof Ext> & { [K in keyof Ext as undefined extends z.infer<Ext[K]> ? never : K]: z.infer<Ext[K]> } & { [K in keyof Ext as undefined extends z.infer<Ext[K]> ? K : never]?: z.infer<Ext[K]> };
+type ExtendedRequestPayload<OrigPayload, Ext extends RequestSubjectExtension> = {
+  request: Ext['request'] extends Record<string, z.ZodType> ? ExtendWithInput<OrigPayload extends {
+    request: infer R;
+  } ? R : never, Ext['request']> : OrigPayload extends {
+    request: infer R;
+  } ? R : never;
+  response: Ext['response'] extends Record<string, z.ZodType> ? ExtendWithInfer<OrigPayload extends {
+    response: infer R;
+  } ? R : never, Ext['response']> : OrigPayload extends {
+    response: infer R;
+  } ? R : never;
+};
+/**
+ * A SubjectDefinition with overridden `$meta.payload` — preserves all other metadata.
+ */
+type ExtendedSubjectDefinition<SD extends SubjectDefinition, Ext extends SubjectExtension<SD>> = {
+  subject: SD['subject'];
+  $meta: {
+    namespace: SD['$meta']['namespace'];
+    isRequest: SD['$meta']['isRequest'];
+    local: SD['$meta']['local'];
+    channel: SD['$meta']['channel'];
+    payload: SD['$meta']['isRequest'] extends true ? Ext extends RequestSubjectExtension ? ExtendedRequestPayload<SD['$meta']['payload'], Ext> : SD['$meta']['payload'] : Ext extends Record<string, z.ZodType> ? ExtendWithInfer<SD['$meta']['payload'], Ext> : SD['$meta']['payload'];
+  };
+};
+/**
+ * Pure declaration of a subject extension.
+ *
+ * This keeps TypeScript's widened subject inference available to importers
+ * without mutating the runtime namespace registry at module import time.
+ * The owning package must call {@link DefinedSubjectExtension.register} during
+ * its activation lifecycle, after the base namespace has been registered.
+ */
+interface DefinedSubjectExtension<SD extends SubjectDefinition, Ext extends SubjectExtension<SD>> {
+  /** Subject definition with widened payload inference. */
+  readonly subject: ExtendedSubjectDefinition<SD, Ext>;
+  /**
+   * Register the extension against the runtime bus namespace registry.
+   * @param bus - Bus instance whose namespace registry receives the extension.
+   * @returns The same subject definition with widened payload inference.
+   */
+  register(bus: Pick<IMakaioBus, 'extendSubject'>): ExtendedSubjectDefinition<SD, Ext>;
+}
+/**
+ * Declare a subject extension without registering it immediately.
+ *
+ * Use this for product or extension modules that export typed subjects but
+ * cannot safely mutate the namespace registry at import time. Registration
+ * remains explicit via the returned `register()` method.
+ * @param subject - Base subject definition to widen.
+ * @param extension - Additional Zod fields for the subject payload.
+ * @returns A declaration containing the widened subject and activation-time registration hook.
+ */
+declare function defineSubjectExtension<SD extends SubjectDefinition, Ext extends SubjectExtension<SD>>(subject: SD, extension: Ext): DefinedSubjectExtension<SD, Ext>;
+/**
+ * Extend a registered bus subject's schema with additional fields.
+ *
+ * Called on the bus context directly. Adds new fields to the Zod schema for
+ * dev-mode validation and widens the TypeScript payload type. Successive calls
+ * accumulate fields — two packages can independently extend the same subject
+ * with different field names. If two extensions add the same field name,
+ * the later call's definition wins (Zod `.extend()` semantics).
+ *
+ * The returned value is the same runtime object — only the TypeScript type widens.
+ * @param context - Bus context containing the namespace registry
+ * @param subject - The SubjectDefinition to extend
+ * @param extensions - Additional Zod fields to add
+ * @returns The same SubjectDefinition with wider TypeScript types
+ */
+declare function extendSubjectImpl<SD extends SubjectDefinition, Ext extends SubjectExtension<SD>>(context: MakaioBusContext, subject: SD, extensions: Ext): ExtendedSubjectDefinition<SD, Ext>;
+//#endregion
+//#region packages/bus-core/src/types/interceptor.d.ts
+/**
+ * Context provided to interceptor handlers.
+ *
+ * Interceptors run BEFORE event handlers (not request handlers), allowing:
+ * - Payload transformation via `replacePayload()`
+ * - Event blocking via `stopPropagation()`
+ * - Sequential execution in priority order (highest first)
+ *
+ * Note: Interceptors only work with event subjects. For request/response
+ * flow interception, use middleware instead.
+ */
+interface InterceptorContext<P, S = string> {
+  readonly subject: S;
+  readonly payload: P;
+  readonly messageId: string;
+  readonly correlationId: string | undefined;
+  /**
+   * Stop propagation of this message.
+   * Subsequent interceptors and all handlers will NOT be called.
+   */
+  stopPropagation(): void;
+  /**
+   * Replace the payload with a new value.
+   * Subsequent interceptors and handlers will receive the new payload.
+   */
+  replacePayload(newPayload: P): void;
+  /**
+   * Explicitly continue to the next interceptor (optional).
+   * Continuation is implicit if neither stopPropagation() nor next() is called.
+   */
+  next(): void;
+}
+/**
+ * Handler function for interceptors.
+ * Receives an InterceptorContext and may optionally return a Promise.
+ */
+type InterceptorHandler<P> = (ctx: InterceptorContext<P>) => void | Promise<void>;
+/**
+ * Options for registering an interceptor.
+ */
+interface InterceptOptions {
+  /**
+   * Priority for interceptor execution order.
+   * Higher values run first. Default: 0
+   */
+  priority?: number;
+  /**
+   * Optional filter to conditionally invoke this interceptor.
+   * Uses the same filter syntax as on() handlers.
+   */
+  filter?: PayloadFilter;
+}
+/**
+ * Entry stored in the interceptor registry.
+ * Similar to HandlerEntry but specific to interceptors.
+ */
+interface InterceptorEntry<H> {
+  handler: H;
+  priority: number;
+}
+//#endregion
+//#region packages/bus-core/src/methods/once.d.ts
+/**
+ * Options for the Promise-based once() method.
+ */
+type OnceOptions<T extends SubjectDefinition> = {
+  /** Timeout in milliseconds - rejects promise if event not received within this time */timeoutMs?: number;
+  /**
+   * Declarative payload filter for smart-routing.
+   *
+   * Applied both locally and can be sent to transports for server-side filtering.
+   * Replaces the old function-based filter for serialization support.
+   * @example
+   * ```typescript
+   * await bus.once(Subjects.message, {
+   *   filter: {
+   *     agentId: 'agent-123',
+   *     'raw.msg.type': 'session_configured',
+   *   }
+   * });
+   * ```
+   */
+  filter?: TypedPayloadFilter<T['$meta']['payload']>; /** AbortSignal to cancel waiting */
+  signal?: AbortSignal;
+};
+/**
+ * Error thrown when `once()` rejects because its `AbortSignal` was
+ * triggered. Consumers that intentionally abort a pending listener can use
+ * `instanceof OnceAbortError` to distinguish the expected rejection from real
+ * failures.
+ */
+declare class OnceAbortError extends Error {
+  constructor();
+}
+//#endregion
+//#region packages/bus-core/src/scoped-bus-base.d.ts
+/**
+ * Minimal shared surface common to {@link ScopedBus} and {@link IFilteredBus}.
+ * @typeParam Namespace - The namespace domain string (e.g. `'adapter:codex-mcp'`)
+ */
+interface IScopedBusBase<Namespace extends string> {
+  readonly namespace: Namespace;
+  /**
+   * Register an event or request handler.
+   * @param subject - Subject definition to listen on
+   * @param handler - Handler function to invoke
+   * @param options - Optional subscription options (filter, priority, etc.)
+   * @returns Unsubscribe function
+   */
+  on<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, handler: HandlerForSubjectDefinition<Subject>, options?: OnOptions): () => void;
+  /**
+   * Register an interceptor that runs BEFORE handlers.
+   * @param subject - Subject definition to intercept
+   * @param handler - Interceptor handler function
+   * @param options - Optional intercept options (filter, priority, etc.)
+   * @returns Unsubscribe function
+   */
+  intercept<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, handler: InterceptorHandler<Subject['$meta']['payload']>, options?: InterceptOptions): () => void;
+  /**
+   * Register a one-time handler (callback version).
+   * @param subject - Subject definition to listen on once
+   * @param handler - Handler function invoked at most once
+   * @returns Unsubscribe function
+   */
+  once<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, handler: HandlerForSubjectDefinition<Subject>): () => void;
+  /**
+   * Wait for an event (promise version).
+   * @param subject - Subject definition to await
+   * @param options - Optional filter and timeout options
+   * @returns Promise resolving to the event context
+   */
+  once<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, options?: OnceOptions<Subject>): Promise<ContextForSubjectDefinition<Subject>>;
+  /**
+   * Emit an event.
+   * @param subject - Subject definition to emit on
+   * @param payload - Event payload matching the subject schema
+   * @returns Promise resolving when all handlers have been notified
+   */
+  emit<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, payload: Subject['$meta']['payload']): Promise<void>;
+  /**
+   * Make a request (throws if no handler is registered).
+   * @param subject - Subject definition for the request
+   * @param payload - Request payload matching the subject schema
+   * @returns Promise resolving to the response payload
+   */
+  request<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, payload: Subject['$meta']['payload']['request']): Promise<Subject['$meta']['payload']['response']>;
+  /**
+   * Make an optional request (returns `OptionalResult` instead of throwing
+   * when no handler is registered).
+   * @param subject - Subject definition for the request
+   * @param payload - Request payload matching the subject schema
+   * @returns Promise resolving to an `OptionalResult` wrapper
+   */
+  requestOptional<Subject extends ScopedSubjectDefinition<Namespace>>(subject: Subject, payload: Subject['$meta']['payload']['request']): Promise<OptionalResult<Subject['$meta']['payload']['response']>>;
+}
+//#endregion
+//#region packages/bus-core/src/filtered-bus.d.ts
+/**
+ * Filtered bus that applies a base filter to all subscriptions.
+ *
+ * Created via `ScopedBus.withFilter()` or `FilteredBus.withFilter()`.
+ * @typeParam Namespace - The namespace domain string
+ * @typeParam Subjects - SubjectRecord for payload types (unused, for type consistency)
+ * @typeParam FilterPayload - Pre-computed filter payload type for type-safe withFilter
+ */
+interface IFilteredBus<Namespace extends string = string, Subjects = unknown, FilterPayload = unknown> extends IScopedBusBase<Namespace> {
+  /**
+   * Get the current base filter.
+   */
+  getFilter(): PayloadFilter | undefined;
+  /**
+   * Create a new FilteredBus with additional filter conditions merged in.
+   * Later filters override earlier ones for the same path.
+   *
+   * When FilterPayload is known, filter keys are automatically type-checked.
+   * @param filter - Additional filter conditions to merge
+   * @returns New FilteredBus with merged filter
+   * @example
+   * ```typescript
+   * // Type-safe filtering - keys validated against FilterPayload
+   * const agentBus = bus.withFilter({ agentId: 'agent-123' }); // ✅
+   * const badBus = bus.withFilter({ unknownKey: 'x' });        // ❌ Error
+   *
+   * // Explicit type override
+   * interface CustomPayload { agentId: string; status: string }
+   * const strictBus = bus.withFilter<CustomPayload>({ agentId: 'agent-123' });
+   * ```
+   */
+  withFilter(filter: TypedPayloadFilter<FilterPayload>): IFilteredBus<Namespace, Subjects, FilterPayload>;
+}
+/**
+ * Create a filtered bus instance.
+ * @param context - Bus context
+ * @param namespace - Namespace for validation
+ * @param baseFilter - Base filter to apply to all subscriptions
+ * @returns FilteredBus instance
+ */
+declare function createFilteredBus<Namespace extends string, Subjects = unknown, FilterPayload = unknown>(context: MakaioBusContext, namespace: Namespace, baseFilter?: PayloadFilter): IFilteredBus<Namespace, Subjects, FilterPayload>;
+//#endregion
+//#region packages/bus-core/src/scoped-bus.d.ts
+/**
+ * Scoped bus with namespace isolation and type-safe filtering.
+ * @typeParam Namespace - The namespace domain string (e.g., 'adapter:codex-mcp')
+ * @typeParam Subjects - SubjectRecord for payload types (used by on/once/emit)
+ * @typeParam FilterPayload - Pre-computed intersection of all filterable payloads.
+ *                            When provided, withFilter constrains filter keys to this type.
+ */
+type ScopedBus<Namespace extends string, Subjects = SubjectRecord, FilterPayload = unknown> = IScopedBusBase<Namespace> & {
+  /**
+   * Create a filtered bus with a base payload filter.
+   *
+   * The filter is automatically applied to all `on()` and `once()` calls.
+   *
+   * When FilterPayload is known (via BusNamespace.scopedBus()), filter keys are
+   * automatically constrained to the intersection of all subject payloads.
+   * @param filter - Base filter to apply to all subscriptions
+   * @returns FilteredBus with the specified filter
+   * @example
+   * ```typescript
+   * // Type-safe filtering - keys auto-inferred from pre-computed FilterPayload
+   * const scopedBus = await CodexMcpNamespace.scopedBus();
+   * scopedBus.withFilter({ agentId: this.agentId }); // ✅ agentId validated
+   * scopedBus.withFilter({ unknownKey: 'x' });       // ❌ Error - unknown key
+   *
+   * // Explicit type override still works
+   * interface CustomPayload { agentId: string; sessionId: string }
+   * scopedBus.withFilter<CustomPayload>({ agentId: 'x' });
+   * ```
+   */
+  withFilter(filter: TypedPayloadFilter<FilterPayload>): IFilteredBus<Namespace, Subjects, FilterPayload>;
+  /**
+   * Get the bus context for advanced use cases.
+   */
+  getContext(): MakaioBusContext;
+};
+//#endregion
+//#region packages/bus-core/src/types/namespace.d.ts
+/**
+ * A registered bus namespace with domain, subjects, and pre-computed filter payload type.
+ * @typeParam Domain - The namespace domain string (e.g., 'adapter:codex-mcp')
+ * @typeParam Subjects - The subject record mapping subject keys to payload types
+ * @typeParam FilterPayload - Pre-computed intersection of all filterable payloads for type-safe withFilter
+ * @typeParam Schemas - The original schema record; drives narrow literal types on subjects.$meta (e.g., local: false)
+ */
+type BusNamespace<Domain extends string = string, Subjects extends SubjectRecord | BusSubjects = SubjectRecord, FilterPayload = unknown, Schemas extends Record<string, SubjectSchema> = Record<string, SubjectSchema>> = {
+  name: Domain;
+  subjects: BusSubjects<FlatSubjectDefinitions<Domain, Schemas>, Domain>;
+  scopedBus(context?: MakaioBusContext): Promise<ScopedBus<Domain, Subjects, FilterPayload>>;
+  /**
+   * Phantom property for type extraction. Never accessed at runtime.
+   * Enables `ExtractFilterPayload<T>` to infer the FilterPayload type parameter
+   * without relying on complex nested generic inference.
+   */
+  readonly __filterPayload?: FilterPayload;
+};
+/**
+ * Derive a ScopedBus type from a BusNamespace, preserving Domain, Subjects, and FilterPayload.
+ * @example
+ * ```typescript
+ * const MyNamespace = MakaioBus.registerNamespace('myDomain', { ... });
+ * export type MyBus = ScopedBusFor<typeof MyNamespace>;
+ * // Equivalent to: ScopedBus<'myDomain', { ...subjects... }, FilterPayload>
+ * ```
+ */
+type ScopedBusFor<T> = T extends BusNamespace<infer D, infer S, infer F, infer _Sc> ? ScopedBus<D, S extends SubjectRecord ? S : SubjectRecord, F> : never;
+//#endregion
+//#region packages/bus-core/src/registries/namespace-registry.d.ts
+/**
+ * Callback invoked when a schema violation is detected in lenient mode.
+ * @param report - Violation details including subject, payload, and Zod issues
+ */
+type SchemaViolationCallback = (report: SchemaViolationReport) => void;
+/**
+ * Validation mode for a namespace's bus payloads.
+ *
+ * - `strict` — throw ValidationError on schema mismatch (default)
+ * - `lenient` — invoke onSchemaViolation callback, then continue (event still delivered)
+ * - `skip` — no validation at all (for Zod version conflicts, e.g., SDK bundles Zod v3)
+ */
+type BusValidationMode = 'strict' | 'lenient' | 'skip';
+/**
+ * Resolved validation config for a namespace's bus payloads.
+ */
+interface ValidationConfig {
+  /** Active validation mode */
+  mode: BusValidationMode;
+  /** Callback for lenient-mode violations (undefined for strict/skip) */
+  onViolation?: SchemaViolationCallback;
+}
+/**
+ * Runtime schema metadata for one registered bus subject.
+ */
+interface RegisteredSubjectSchema {
+  /** Namespace passed to `registerNamespace()`. */
+  namespace: string;
+  /** Subject key inside the namespace's schema record. */
+  subject: string;
+  /** Fully-qualified subject key in `namespace.subject` form. */
+  fullSubject: string;
+  /** Unwrapped event or request schema used by runtime validation. */
+  schema: BaseSubjectSchema;
+  /** Whether the subject was registered through `localSubject()`. */
+  local: boolean;
+  /** Whether the subject was registered through `channelSubject()`. */
+  channel: boolean;
+}
+/**
+ * Creates the namespace registry used by a bus context.
+ *
+ * Maintains a runtime map of registered namespaces and their subject schemas,
+ * enabling schema lookup, request-subject detection, local-subject detection,
+ * and validation configuration for namespaces that bundle incompatible Zod versions.
+ * @returns Namespace registry with registerNamespace, getSchema, listRegisteredSubjects,
+ *   isRequestSubject, isLocalSubject, getValidationConfig, and (test-only) __resetNamespaces methods
+ */
+declare const createNamespaceRegistry: () => {
+  /**
+   * Register a namespace in the runtime registry.
+   *
+   * Accepts a {@link BusNamespaceDefinition} created by `createBusNamespace()` from
+   * `@makaio/core`. The FilterPayload type parameter is computed eagerly from the
+   * schemas, enabling type-safe filtering via `withFilter()`.
+   * @param definition - Namespace definition created by `createBusNamespace()`
+   * @returns The registered namespace with `scopedBus()` and pre-computed FilterPayload type
+   */
+  registerNamespace<Domain extends string, Schemas extends Record<string, SubjectSchema>>(definition: BusNamespaceDefinition<Domain, Schemas>): BusNamespace<Domain, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Schemas>;
+  /**
+   * Register multiple namespaces in a single call.
+   *
+   * Iterates `definitions` and calls `registerNamespace()` for each. Useful
+   * at composition roots to register a catalog of namespace definitions in one
+   * statement:
+   *
+   * ```typescript
+   * MakaioBus.registerNamespaces(FrameworkContractNamespaces);
+   * ```
+   * @param definitions - Array of namespace definitions to register
+   */
+  registerNamespaces(definitions: readonly RegistrableBusNamespaceDefinition[]): void;
+  /**
+   * Get the schema for a registered subject.
+   * Returns the unwrapped schema (LocalSubjectSchema and ChannelSubjectSchema wrappers are removed during registration).
+   * @param subject - Subject identifier (e.g., "adapter.getCapabilities")
+   * @returns Schema if found, undefined otherwise
+   */
+  getSchema(subject: string | SubjectDefinition): BaseSubjectSchema | undefined;
+  /**
+   * List all registered subjects with their runtime schema metadata.
+   * @returns Registered subjects sorted by fully-qualified subject key
+   */
+  listRegisteredSubjects(): RegisteredSubjectSchema[];
+  /**
+   * Check if a subject is registered as a request subject.
+   * @param subject - Subject identifier
+   * @returns True if subject exists and is a request schema
+   */
+  isRequestSubject(subject: string): boolean;
+  /**
+   * Check if a subject was registered as a local-only subject.
+   *
+   * Local subjects must never be routed over transports. The `__local` flag
+   * is stripped by `unwrapSchema`, so locality is tracked in a separate set
+   * populated at registration time.
+   * @param subject - Full subject identifier (e.g., "widget.register")
+   * @returns True if the subject was wrapped with `localSubject()`
+   */
+  isLocalSubject(subject: string): boolean;
+  /**
+   * Get the validation configuration for a subject.
+   *
+   * Looks up the namespace from the subject's prefix and returns
+   * the registered mode and optional violation callback.
+   * @param subject - Full subject identifier (e.g., "adapter:claude-code.sdk.event")
+   * @returns Validation config, or `{ mode: 'strict' }` if none registered
+   */
+  getValidationConfig(subject: string): ValidationConfig;
+  /**
+   * Additively extend a registered subject's schema with new fields.
+   *
+   * For request subjects, extends the request and/or response ZodObject via `.extend()`.
+   * For event subjects, extends the event ZodObject directly.
+   * Successive calls accumulate fields; if a later extension redefines an existing key, the later definition wins (Zod `.extend()` semantics).
+   * @param fullSubjectKey - Fully-qualified key (e.g., "session.list")
+   * @param additionalFields - For request subjects: `{ request?, response? }` each a record
+   *   of Zod field definitions. For event subjects: a flat record of Zod field definitions.
+   * @throws Error if the subject is not registered or the existing schema is not a ZodObject
+   */
+  extendSubjectSchema(fullSubjectKey: string, additionalFields: z.ZodRawShape | {
+    request?: z.ZodRawShape;
+    response?: z.ZodRawShape;
+  }): void;
+  /**
+   * Reset all registered namespaces (for testing only).
+   * @internal
+   */
+  __resetNamespaces: (() => void) | undefined;
+};
+type NamespaceRegistry = ReturnType<typeof createNamespaceRegistry>;
+//#endregion
+//#region packages/bus-core/src/registries/transport-registry.d.ts
+interface BusTransportRegistry extends Record<string, BusTransport> {}
+type BusTransportKeys = keyof BusTransportRegistry;
+/**
+ * Creates the transport registry used by a bus context.
+ *
+ * Manages connected transports, handles inbound message routing (events,
+ * requests, broadcasts), and relays messages to other registered transports.
+ * @param context - Bus context that owns this registry
+ * @returns Transport registry with registerTransport, getTransport, all,
+ *   names, and getPendingReady methods
+ */
+/**
+ * Callback interface for transport lifecycle event emission.
+ *
+ * Set on the transport registry by the bus after construction so that
+ * connect/disconnect transitions emit `BusLifecycle.connected` /
+ * `BusLifecycle.disconnected` automatically for every registered transport.
+ */
+interface TransportLifecycleEmitter {
+  /**
+   * Called when a transport establishes a connection.
+   * @param transportName - Name of the connected transport.
+   */
+  onConnected(transportName: string): void;
+  /**
+   * Called when a transport loses connection unexpectedly.
+   * @param transportName - Name of the disconnected transport.
+   */
+  onDisconnected(transportName: string): void;
+}
+declare const createTransportRegistry: (context: MakaioBusContext) => {
+  registerTransport<K extends BusTransportKeys>(name: K, transport: BusTransportRegistry[K]): TransportRegistration;
+  getTransport<K extends BusTransportKeys>(name: K): BusTransportRegistry[K] | undefined;
+  all(): BusTransport[];
+  names(): BusTransportKeys[];
+  /**
+   * Return all unresolved transport `ready` promises for dispatch-level gating.
+   *
+   * Use `Promise.all(registry.getPendingReady())` to await full initialization.
+   * @returns Array of pending ready promises (empty when all transports are ready)
+   */
+  getPendingReady(): Promise<void>[];
+  /**
+   * Set the lifecycle emitter used to publish `BusLifecycle.connected` /
+   * `BusLifecycle.disconnected` events whenever a transport connects or
+   * disconnects.
+   *
+   * Called once by the owning bus after construction. Subsequent transport
+   * registrations automatically pick up the emitter through the closure.
+   * @param emitter - Lifecycle emitter to install.
+   */
+  setLifecycleEmitter(emitter: TransportLifecycleEmitter): void;
+};
+type TransportRegistry = ReturnType<typeof createTransportRegistry>;
+//#endregion
+//#region packages/bus-core/src/types/transports.d.ts
+/**
+ * Subscribe message for client subscription management.
+ *
+ * Supports both subject-based filtering (wildcards) and payload-based filtering
+ * (declarative filter specs). Both are applied server-side for smart-routing.
+ *
+ * Priority arrays enable cross-transport priority-based dispatch: the receiver
+ * uses the arrays to populate its remote handler registry so that dispatch can
+ * consider handler priorities across process boundaries.
+ * @example
+ * ```typescript
+ * // Request handler with priorities
+ * { type: 'subscribe', subjects: { 'ui.navigate': [100, 200] } }
+ *
+ * // Event-only handler (no priority-based dispatch)
+ * { type: 'subscribe', subjects: { 'session.created': [] } }
+ * ```
+ */
+interface BusSubscribeMessage {
+  type: 'subscribe';
+  /**
+   * Subjects and their handler priorities.
+   * Keys are subject patterns (can include wildcards like `'adapter.*'`).
+   * Values are arrays of handler priorities registered for that subject.
+   * An empty array indicates event-only handlers with no priority-based dispatch.
+   */
+  subjects: Record<string, number[]>;
+  /**
+   * Optional payload filters per subject.
+   * Key is the subject pattern, value is the filter to apply.
+   * Messages are only forwarded if payload matches the filter.
+   * @example
+   * ```typescript
+   * {
+   *   subjects: { 'mcp.event': [] },
+   *   filters: {
+   *     'mcp.event': { agentId: 'agent-123' }
+   *   }
+   * }
+   * ```
+   */
+  filters?: Record<string, PayloadFilter>;
+}
+/**
+ * Unsubscribe message for client subscription management.
+ *
+ * Priority arrays enable ref-counted unsubscription: the receiver removes only
+ * the listed handler priorities from its remote handler registry rather than
+ * wiping the entire subject entry.
+ */
+interface BusUnsubscribeMessage {
+  type: 'unsubscribe';
+  /**
+   * Subjects and the handler priorities being removed.
+   * Keys are subject patterns.
+   * Values are the specific priorities being unregistered (for ref-counting).
+   * An empty array removes the subject entirely (no handlers remain).
+   */
+  subjects: Record<string, number[]>;
+}
+/**
+ * Subscribe-sync-complete handshake message.
+ *
+ * Sent by the bus to a newly registered transport after the current handler
+ * subscriptions have been pushed. The recipient resolves its `ready` promise
+ * upon receipt, signalling that priority-based request dispatch may safely
+ * route through the transport.
+ */
+interface BusSubscribeSyncCompleteMessage {
+  type: 'subscribe-sync-complete';
+}
+/**
+ * Message types for transport wire protocol.
+ */
+type BusMessage = BusRequestMessage | BusResponseMessage | BusEventMessage | BusBroadcastMessage | BusBroadcastResponseMessage | BusHeartbeatMessage | BusSubscribeMessage | BusUnsubscribeMessage | BusSubscribeSyncCompleteMessage;
+/**
+ * Handler invoked by transports when a bus message arrives.
+ *
+ * The optional receive context is trusted local metadata supplied by the
+ * receiving transport. It must not be serialized or relayed to other nodes.
+ */
+type BusReceiveHandler = (message: BusMessage, context?: TransportReceiveContext) => Promise<void>;
+/**
+ * Heartbeat message for connection keep-alive.
+ */
+interface BusHeartbeatMessage {
+  type: 'heartbeat';
+  timestamp: number;
+}
+/**
+ * Request message sent over transport.
+ */
+interface BusRequestMessage {
+  type: 'request';
+  subject: string;
+  namespace: string;
+  payload: unknown;
+  correlationId: string;
+  messageId: string;
+  /**
+   * Caller-specified request timeout in milliseconds.
+   *
+   * Propagated across relay hops so intermediate transport registries use the
+   * same timeout policy as the original caller.
+   * A value of `0` means no automatic timeout.
+   */
+  timeout?: number;
+  /**
+   * Priority cursor for cross-transport priority-based dispatch.
+   *
+   * When set, dispatch considers only handlers with a priority strictly below
+   * this value, enabling the chain to continue from where a previous hop left off.
+   * Omitted on the first dispatch hop (meaning start from the highest priority).
+   */
+  priority?: number;
+  /**
+   * Absolute dispatch deadline as a Unix timestamp in milliseconds (`Date.now() + timeout`).
+   *
+   * Set on the first dispatch hop and propagated through all subsequent hops so
+   * that each hop can compute its remaining time budget without relying on the
+   * original timeout value alone.
+   */
+  deadline?: number;
+}
+/**
+ * Structured error payload for transport responses.
+ */
+interface BusTransportError {
+  /** Human-readable error message */
+  message: string;
+  /** Error code for programmatic handling (e.g., 'IMPORT_CONFLICT') */
+  code?: string;
+  /**
+   * Subject this error pertains to.
+   * Preserved for {@link NoHandlerError} so that `isNoHandlerErrorForSubject`
+   * can match without fragile message-string comparisons after a
+   * serialize → deserialize round-trip.
+   */
+  subject?: string;
+  /** Additional error data (e.g., conflicts, orphans) */
+  data?: Record<string, unknown>;
+}
+/**
+ * Response message sent over transport.
+ */
+interface BusResponseMessage {
+  type: 'response';
+  correlationId: string;
+  result?: unknown;
+  error?: BusTransportError;
+}
+/**
+ * Event message sent over transport.
+ */
+interface BusEventMessage {
+  type: 'event';
+  subject: string;
+  namespace: string;
+  payload: unknown;
+  messageId: string;
+  correlationId?: string;
+}
+/**
+ * Broadcast request message sent over transport.
+ *
+ * Unlike regular requests (single response), broadcasts expect
+ * multiple responses aggregated into an array.
+ */
+interface BusBroadcastMessage {
+  type: 'broadcast';
+  subject: string;
+  namespace: string;
+  payload: unknown;
+  correlationId: string;
+  messageId: string;
+  /**
+   * Caller-specified broadcast timeout in milliseconds.
+   *
+   * Propagated across relay hops so relayed broadcast collection preserves the
+   * original caller timeout contract.
+   * A value of `0` means no automatic timeout.
+   */
+  timeout?: number;
+}
+/**
+ * Broadcast response message sent over transport.
+ *
+ * Contains an array of results from all handlers that responded.
+ */
+interface BusBroadcastResponseMessage {
+  type: 'broadcast-response';
+  correlationId: string;
+  results?: Array<{
+    nodeId: string;
+    payload: unknown;
+  }>;
+  error?: BusTransportError;
+}
+/**
+ * Transport interface for bus communication.
+ *
+ * Transports handle serialization, wire protocol, and connection management
+ * for cross-process communication.
+ * @example
+ * ```typescript
+ * class WebSocketTransport implements BusTransport {
+ *   readonly name = 'websocket';
+ *
+ *   async send(message: BusMessage): Promise<void> {
+ *     this.ws.send(JSON.stringify(message));
+ *   }
+ *
+ *   onReceive(handler: BusReceiveHandler): () => void {
+ *     const listener = (data) => {
+ *       const message = JSON.parse(data) as BusMessage;
+ *       const context: TransportReceiveContext = { transportName: this.name };
+ *       void handler(message, context);
+ *     };
+ *     this.ws.on('message', listener);
+ *     return () => this.ws.off('message', listener);
+ *   }
+ *
+ *   async connect(): Promise<void> {
+ *     await this.ws.connect();
+ *   }
+ *
+ *   async disconnect(): Promise<void> {
+ *     await this.ws.close();
+ *   }
+ * }
+ * ```
+ */
+interface BusTransport {
+  /**
+   * Unique transport name used as the registry key.
+   *
+   * The name is used by `IMakaioBus.registerTransport()` to key the transport
+   * in the internal registry. It must be unique within a single bus instance.
+   * Implementations should declare this as a `readonly` literal or class field.
+   * @example
+   * ```typescript
+   * class MyTransport implements BusTransport {
+   *   readonly name = 'my-transport';
+   * }
+   * ```
+   */
+  name: string;
+  /**
+   * Send a message over the transport.
+   *
+   * **Behavior by message type:**
+   * - **Requests** (`BusRequestMessage`): Returns the response payload from the handler.
+   * Throws error if no clients available to handle request (server mode).
+   * - **Events** (`BusEventMessage`): Returns delivery status boolean.
+   * - `true`: Delivered to at least one recipient
+   * - `false`: No recipients available (not an error)
+   * - **Other messages** (heartbeat, subscribe, etc.): Returns `true` if sent successfully.
+   *
+   * **Error handling:**
+   * - Throws when transport is disconnected
+   * - Throws when sending requests with no connected clients (server mode only)
+   * - Never throws for events - returns `false` instead
+   *
+   * **Timeout contract:**
+   * The `timeout` value flows from the caller's `bus.request({ timeout })` option
+   * through the dispatch layer to the transport's correlation tracker.
+   * A value of `0` means no automatic timeout — the promise stays open until
+   * resolved or rejected externally (e.g. by the caller's own AbortSignal).
+   * @param message - Message to send
+   * @param timeout - Correlation timeout in milliseconds; `0` means no automatic timeout
+   * @returns Promise resolving to response payload (requests) or delivery status (events/other)
+   * @example
+   * ```typescript
+   * // Request: type-safe response handling
+   * const request: BusRequestMessage = {
+   *   type: 'request',
+   *   subject: 'user.get',
+   *   namespace: 'api',
+   *   payload: { id: 123 },
+   *   correlationId: 'req-1',
+   *   messageId: 'msg-1',
+   * };
+   * const response = await transport.send(request, 5000); // response: unknown
+   *
+   * // Event: delivery status
+   * const event: BusEventMessage = {
+   *   type: 'event',
+   *   subject: 'user.created',
+   *   namespace: 'api',
+   *   payload: { id: 123 },
+   *   messageId: 'evt-1',
+   * };
+   * const delivered = await transport.send(event, 0); // delivered: boolean
+   * if (!delivered) {
+   *   console.warn('Event not delivered - no subscribers');
+   * }
+   * ```
+   */
+  send<TMessage extends BusMessage>(message: TMessage, timeout?: number): Promise<TMessage extends BusRequestMessage ? unknown : TMessage extends BusBroadcastMessage ? Array<{
+    nodeId: string;
+    payload: unknown;
+  }> : boolean>;
+  /**
+   * Optional: cancel/cleanup pending correlation state for an in-flight request.
+   *
+   * Used when the caller aborts while the transport-level correlation promise is
+   * still pending (e.g. timeout `0` + AbortSignal). Implementations should reject
+   * and remove the correlation entry if present.
+   * @param correlationId - Correlation ID to cancel
+   * @param error - Optional cancellation error to propagate
+   */
+  cancelRequest?(correlationId: string, error?: Error): void;
+  /**
+   * Register a handler for incoming messages.
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  onReceive(handler: BusReceiveHandler): () => void;
+  /**
+   * Connect the transport.
+   */
+  connect(): Promise<void>;
+  /**
+   * Disconnect the transport.
+   */
+  disconnect(): Promise<void>;
+  /**
+   * Optional: Trigger an immediate reconnection attempt, bypassing any backoff wait.
+   *
+   * If the transport is currently waiting in an exponential-backoff delay, calling
+   * this wakes it immediately so a new connection attempt starts without waiting.
+   * If reconnection is disabled on the transport, a one-shot connect attempt is made.
+   * No-op when the transport is already connected.
+   * @returns Promise that resolves when the attempt is initiated or completes
+   */
+  reconnect?(): Promise<void>;
+  /**
+   * Optional: Promise that resolves when the transport is fully operational
+   * (end-to-end, including remote handler availability).
+   *
+   * Resolved after the bus has sent the initial subscribe sync to the transport
+   * and the transport has received the {@link BusSubscribeSyncCompleteMessage}
+   * handshake. Before this resolves, `remoteRequestHandlers` for this transport
+   * may be incomplete and requests should not be routed through it.
+   *
+   * Transports that do not implement `ready` are considered immediately ready.
+   * @remarks
+   * Transports that do not implement `onNewReadySession` are single-use:
+   * after `disconnect()` completes, a later `connect()` call has undefined
+   * behavior. Reconnectable transports must call `onNewReadySession` each time
+   * they create a new `ready` promise so the registry can update its gating.
+   */
+  ready?: Promise<void>;
+  /**
+   * Optional callback set by the transport registry during registration.
+   * Transports that support reconnection call this at the start of each
+   * new session so the registry can track the new ready promise for
+   * dispatch gating.
+   * @param promise - The new ready promise for the current session
+   */
+  onNewReadySession?: (promise: Promise<void>) => void;
+  /**
+   * Optional callback set by the transport registry during registration.
+   * Called each time the transport establishes a connection (initial or reconnect),
+   * after authentication and subscription replay are complete.
+   */
+  onConnected?: () => void;
+  /**
+   * Optional callback set by the transport registry during registration.
+   * Called when the transport loses its connection unexpectedly.
+   * Not called on an explicit `disconnect()`.
+   */
+  onDisconnected?: () => void;
+  /**
+   * Optional: Synchronous readiness check for transport-level gating.
+   *
+   * When implemented and returning `false`, the bus skips this transport
+   * for outbound sends (requests, broadcasts, events). The transport
+   * continues to receive inbound messages via `onReceive`.
+   *
+   * Complements the async `ready` promise: `isReady()` enables non-blocking
+   * skip decisions in hot paths, while `ready` supports await-based flows.
+   * @returns `true` if the transport can send messages, `false` otherwise
+   */
+  isReady?(): boolean;
+  /**
+   * Optional: Report which subjects this transport is interested in.
+   * Enables transport-level filtering for efficiency.
+   *
+   * If not implemented, the transport will receive all messages (broadcast mode).
+   * If implemented, only messages matching the subscription patterns will be sent.
+   *
+   * Patterns can include wildcards (e.g., 'adapter.*' matches 'adapter.log', 'adapter.init', etc.)
+   * @returns Set of subscription patterns (can include wildcards)
+   */
+  getSubscriptions?(): Set<string>;
+  /**
+   * Subscribe to a subject for smart-routing.
+   *
+   * Transports use this to track which subjects have active handlers,
+   * enabling targeted message delivery instead of broadcast.
+   *
+   * When `priorities` is provided the transport should include the priority
+   * information in the next outbound subscribe wire message for this subject,
+   * enabling cross-transport priority-based dispatch on the remote side.
+   * Calling this method again with a new `priorities` array replaces the
+   * previously advertised set for that subject (re-subscribe semantics).
+   *
+   * Transports that do not need subscription management (e.g. local-only
+   * loopback transports) should provide a no-op implementation.
+   * @param subject - Subject pattern to subscribe to (can include wildcards)
+   * @param filter - Optional payload filter for fine-grained routing
+   * @param priorities - Handler priorities registered for this subject; an empty
+   *   array signals event-only handlers that do not participate in priority dispatch
+   */
+  subscribe(subject: string, filter?: PayloadFilter, priorities?: number[]): Promise<void>;
+  /**
+   * Unsubscribe from a subject.
+   *
+   * Called when the last handler for a subject is removed, allowing the
+   * transport to stop routing messages for that subject.
+   *
+   * Transports that do not need subscription management should provide a
+   * no-op implementation.
+   * @param subject - Subject pattern to unsubscribe from
+   */
+  unsubscribe(subject: string): Promise<void>;
+  /**
+   * Receive aggregated broadcast results from the transport registry.
+   *
+   * Called by the transport registry after executing local handlers and relaying
+   * to other transports for a broadcast that arrived from this transport via
+   * `onReceive`. Replaces the legacy `send({ type: 'broadcast-response' })`
+   * side-channel when implemented.
+   *
+   * Transports that manage their own peer-level fan-out (e.g., ServerTransport
+   * with multiple WebSocket clients) implement this to receive registry results
+   * without abusing the `send()` contract.
+   * @param correlationId - Correlation ID of the originating broadcast
+   * @param results - Aggregated results from local handlers and relay transports
+   * @param error - Optional structured error when broadcast processing failed;
+   * results may be empty or partial in this case
+   */
+  onBroadcastResults?(correlationId: string, results: ReadonlyArray<{
+    nodeId: string;
+    payload: unknown;
+  }>, error?: BusTransportError): void;
+}
+//#endregion
+//#region packages/bus-core/src/methods/broadcast.d.ts
+/**
+ * Result from a single handler in a broadcast.
+ * @typeParam T - Response payload type
+ */
+interface BroadcastResult<T> {
+  /** Handler identifier (set via ctx.identify() in handler, or 'anonymous' if not set) */
+  nodeId: string;
+  /** Response payload from the handler */
+  payload: T;
+}
+/**
+ * Extended request context for broadcast handlers.
+ * Adds identify() method to tag responses with a node identifier.
+ */
+interface BroadcastContext<Request, Response> extends RequestContext<Request, Response> {
+  /**
+   * Identify this handler for broadcast aggregation.
+   * Call before setResult() to tag the response with a nodeId.
+   * @param nodeId - Unique identifier for this handler/node
+   */
+  identify: (nodeId: string) => void;
+}
+//#endregion
+//#region packages/bus-core/src/types/options.d.ts
+/**
+ * Default request timeout in milliseconds.
+ *
+ * Shared policy constant used when callers omit `RequestOptions.timeout`.
+ */
+declare const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+/**
+ * Options for subscribing to events/requests via on().
+ */
+interface OnOptions {
+  /**
+   * Explicit handler registry target for wildcard subjects.
+   *
+   * Exact subjects derive their registry from the subject schema. Wildcard
+   * subjects can match both events and requests, so callers that know their
+   * intent can pin the registration to event-only or request-only. Omit this
+   * option to preserve the historical ambiguous wildcard behavior.
+   */
+  handlerKind?: 'event' | 'request' | 'both';
+  /**
+   * Declarative payload filter for smart-routing.
+   *
+   * Applied both locally (before handler invocation) and can be sent
+   * to transports for server-side filtering.
+   *
+   * All conditions are ANDed together.
+   * @example
+   * ```typescript
+   * bus.on(Subjects.message, handler, {
+   *   filter: {
+   *     agentId: 'agent-123',
+   *     status: { $in: ['active', 'pending'] },
+   *   }
+   * });
+   * ```
+   */
+  filter?: PayloadFilter;
+  /**
+   * Handler priority for middleware-style ordering.
+   *
+   * Higher values run earlier. Default is 0.
+   * Handlers with equal priority preserve registration order.
+   * @example
+   * ```typescript
+   * // Authentication runs first (highest priority)
+   * bus.on(Subjects.request, authHandler, { priority: 100 });
+   *
+   * // Logging runs next
+   * bus.on(Subjects.request, logHandler, { priority: 50 });
+   *
+   * // Business logic runs last (default priority)
+   * bus.on(Subjects.request, businessHandler);
+   * ```
+   */
+  priority?: number;
+}
+/**
+ * Options for emitting events.
+ *
+ * Extends BaseMessage to provide message tracking.
+ * All fields are optional - defaults will be auto-generated.
+ */
+interface EmitOptions {
+  /**
+   * Unique identifier for this event.
+   * Auto-generated if not provided.
+   */
+  messageId?: string;
+  /**
+   * Optional correlation ID for linking related operations.
+   * Useful for tracking events as part of a larger workflow.
+   */
+  correlationId?: string;
+  /**
+   * Optional set of transport keys to send this event over.
+   * If not specified, the event will be emitted locally and relayed to all ready transports.
+   * Can be provided as a Set or Array of transport names.
+   */
+  transports?: Set<BusTransportKeys> | Array<BusTransportKeys>;
+}
+/**
+ * Options for making requests.
+ *
+ * Extends EmitOptions with request-specific settings like timeout.
+ */
+interface RequestOptions extends EmitOptions {
+  /**
+   * Timeout in milliseconds. Defaults to DEFAULT_REQUEST_TIMEOUT_MS (60 seconds) if not specified.
+   * Use `0` for no automatic timeout — the request stays open until resolved,
+   * rejected, or cancelled via the `signal` AbortSignal.
+   */
+  timeout?: number;
+  /**
+   * AbortSignal to cancel the request.
+   *
+   * When aborted, the request will reject with an AbortError.
+   * This allows callers to cancel long-running requests when they're
+   * no longer needed (e.g., user typing invalidates previous autocomplete).
+   * @example
+   * ```typescript
+   * const controller = new AbortController();
+   * const result = MakaioBus.request(Subject, payload, {
+   *   signal: controller.signal,
+   * });
+   * // Later, if needed:
+   * controller.abort();
+   * ```
+   */
+  signal?: AbortSignal;
+}
+//#endregion
+//#region packages/bus-core/src/types/handler-entry.d.ts
+/**
+ * Handler entry with priority for middleware-style ordering.
+ * Higher priority values run earlier in the handler chain.
+ */
+interface HandlerEntry<H> {
+  handler: H;
+  priority: number;
+}
+//#endregion
+//#region packages/bus-core/src/types/bus.d.ts
+/**
+ * Internal bus context containing handler registries and shared state.
+ *
+ * Enables creation of isolated bus instances (e.g., for testing) by providing
+ * separate handler maps per instance.
+ *
+ * Handler arrays are sorted by priority (highest first), with registration order
+ * preserved for handlers with equal priority.
+ */
+interface MakaioBusContext {
+  eventHandlers: Map<string, Array<HandlerEntry<EventHandler<unknown>>>>;
+  requestHandlers: Map<string, Array<HandlerEntry<RequestHandler<unknown, unknown>>>>;
+  interceptorHandlers: Map<string, Array<InterceptorEntry<InterceptorHandler<unknown>>>>;
+  anyHandlers: Set<AnyHandler>;
+  transportRegistry: TransportRegistry;
+  namespaceRegistry: NamespaceRegistry;
+  /** Remote handler priorities from subscribe messages; keyed by subject pattern. */
+  remoteRequestHandlers: Map<string, Array<{
+    transport: string;
+    priority: number;
+  }>>;
+  /**
+   * Set of transport names that have subscribed to each subject with event-only handlers
+   * (i.e. subscribe messages whose priority array was empty).
+   *
+   * Tracked separately from `remoteRequestHandlers` because event-only subscriptions
+   * produce no priority entries yet must still influence advertised-state decisions:
+   * if a remote has event-only handlers for a subject, peers should still receive a
+   * `subscribe` (with an empty priority array) rather than an `unsubscribe`.
+   */
+  remoteEventHandlers: Map<string, Set<string>>;
+}
+/**
+ * Result of registering a transport on the bus.
+ */
+interface TransportRegistration {
+  /** Remove the transport from the registry and purge its remote handler entries. */
+  unregister: () => void;
+  /**
+   * Resolves when initial subscribe synchronization is complete and requests
+   * can safely route through this transport. Resolves immediately for
+   * transports that do not implement `ready`.
+   */
+  ready: Promise<void>;
+}
+/**
+ * Options for {@link IMakaioBus.connect}.
+ */
+interface ConnectOptions {
+  /**
+   * Whether to await subscribe-sync readiness after connecting (default: `true`).
+   *
+   * When `true`, `connect()` resolves only after all transports have completed
+   * the subscribe-sync handshake (`transport.ready`), guaranteeing
+   * `remoteRequestHandlers` is fully populated before any request dispatch.
+   *
+   * Set to `false` to resolve as soon as sockets are open. Useful when the
+   * caller needs the socket open for a custom handshake before subscribe-sync.
+   * @defaultValue true
+   */
+  awaitReady?: boolean;
+}
+type IMakaioBus<NamespaceDomain extends string | unknown = unknown, Subjects extends SubjectDefinition = SubjectDefinition, StrictNamespace = {
+  $meta: {
+    namespace: NamespaceDomain extends string ? NamespaceDomain : string;
+  };
+}> = {
+  namespace: NamespaceDomain;
+  /**
+   * Register an event or request handler.
+   *
+   * **Events:** Fire-and-forget - multiple handlers can listen and execute in parallel.
+   * **Requests:** Request-response with middleware support - handlers form a chain.
+   *
+   * **Wildcard Support:** Use `.$all` property on subjects to match all subjects in a namespace.
+   * Wildcard handlers receive `unknown` payload and must use type guards.
+   * @param subject - SubjectDefinition object (exact or wildcard)
+   * @param handler - Handler function (EventHandler for events, RequestHandler for requests)
+   * @returns Unsubscribe function
+   * @example Basic event handler with typed payload
+   * ```typescript
+   * const { subjects: AgentSubjects } = MakaioBus.registerNamespace('agent', {
+   *   started: z.object({ agentId: z.string() }),
+   * });
+   *
+   * const unsubscribe = on(AgentSubjects.started, (context) => {
+   *   context.payload.agentId; // ✅ string - fully typed
+   *   console.debug('Agent started:', context.payload.agentId);
+   * });
+   * ```
+   * @example Wildcard handlers for namespace-level events
+   * ```typescript
+   * // Matches all subjects in namespace
+   * on(AgentSubjects.$all, (context) => {
+   *   context.payload; // unknown - must use type guards
+   *   if ('agentId' in context.payload) {
+   *     console.debug('Any agent event:', context.payload.agentId);
+   *   }
+   * });
+   * ```
+   * @example Request handler with typed request/response
+   * ```typescript
+   * const { subjects: AgentSubjects } = MakaioBus.registerNamespace('agent', {
+   *   toolApprove: {
+   *     request: z.object({ toolName: z.string() }),
+   *     response: z.object({ approved: z.boolean() }),
+   *   },
+   * });
+   *
+   * on(AgentSubjects.toolApprove, (context) => {
+   *   const { toolName } = context.payload; // ✅ fully typed
+   *   context.setResult({ approved: true });
+   * });
+   * ```
+   * @example Middleware pattern for request chain
+   * ```typescript
+   * on(AgentSubjects.toolApprove, async (context) => {
+   *   console.debug('Before approval');
+   *   await context.next();
+   *   console.debug('After approval');
+   * });
+   * ```
+   */
+  on<Subject extends Subjects & StrictNamespace, IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : Subject, handler: Subject extends SubjectDefinition ? HandlerForSubjectDefinition<Subject> : never, options?: OnOptions): () => void; /** Register an interceptor that runs BEFORE handlers (payload transform, blocking, priority). */
+  intercept<Subject extends Subjects & StrictNamespace>(subject: Subject, handler: InterceptorHandler<Subject['$meta']['payload']>, options?: InterceptOptions): () => void;
+  /**
+   * Register a one-time event or request handler that auto-unsubscribes after first invocation.
+   *
+   * Wraps the `on()` method to automatically unsubscribe after the handler fires once.
+   * The handler is removed BEFORE being invoked to prevent re-entrance issues if the
+   * handler triggers the same event.
+   *
+   * **Events:** Fire-and-forget - handler executes once then auto-unsubscribes.
+   * **Requests:** Request-response - handler executes once then auto-unsubscribes.
+   *
+   * **Wildcard Support:** Like `on()`, supports `.$all` property for namespace-level patterns.
+   * @param subject - SubjectDefinition object (exact or wildcard)
+   * @param handler - Handler function (EventHandler for events, RequestHandler for requests)
+   * @returns Unsubscribe function for manual cleanup if needed
+   * @example Basic one-time event handler
+   * ```typescript
+   * const { subjects: AgentSubjects } = MakaioBus.registerNamespace('agent', {
+   *   started: z.object({ agentId: z.string() }),
+   * });
+   *
+   * once(AgentSubjects.started, (context) => {
+   *   context.payload.agentId; // ✅ string - fully typed
+   *   console.debug('Agent started once:', context.payload.agentId);
+   * });
+   *
+   * await emit(AgentSubjects.started, { agentId: 'agent-123' }); // Handler fires
+   * await emit(AgentSubjects.started, { agentId: 'agent-456' }); // Handler does NOT fire
+   * ```
+   * @example Manual unsubscribe before first fire
+   * ```typescript
+   * const unsubscribe = once(AgentSubjects.started, (context) => {
+   *   console.debug('This will never run');
+   * });
+   *
+   * unsubscribe(); // Manually unsubscribe before event fires
+   * await emit(AgentSubjects.started, { agentId: 'agent-123' }); // Handler does NOT fire
+   * ```
+   * @example Wildcard handler for one-time namespace monitoring
+   * ```typescript
+   * once(AgentSubjects.$all, (context) => {
+   *   context.payload; // unknown - must use type guards
+   *   console.debug('First agent event:', context.payload);
+   * });
+   * ```
+   * @example One-time request handler
+   * ```typescript
+   * const { subjects: AgentSubjects } = MakaioBus.registerNamespace('agent', {
+   *   toolApprove: {
+   *     request: z.object({ toolName: z.string() }),
+   *     response: z.object({ approved: z.boolean() }),
+   *   },
+   * });
+   *
+   * once(AgentSubjects.toolApprove, (context) => {
+   *   const { toolName } = context.payload; // ✅ fully typed
+   *   context.setResult({ approved: true });
+   * });
+   *
+   * await request(AgentSubjects.toolApprove, { toolName: 'deleteFile' }); // Handler fires
+   * await request(AgentSubjects.toolApprove, { toolName: 'createFile' }); // Handler does NOT fire
+   * ```
+   */
+  once<Subject extends Subjects & StrictNamespace, IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : Subject, handler: Subject extends SubjectDefinition ? HandlerForSubjectDefinition<Subject> : never): () => void;
+  /**
+   * Wait for an event to occur, returning a Promise.
+   *
+   * Note: Request subjects are not supported with the promise version of once().
+   * Use the callback version for request handlers: `once(subject, handler)`
+   * @param subject - Event SubjectDefinition object (exact or wildcard)
+   * @param options - Options object with: timeoutMs (reject after timeout), filter (only resolve when filter returns true), signal (AbortSignal to cancel waiting)
+   * @returns Promise that resolves with the event context
+   * @example Simple await
+   * ```typescript
+   * const ctx = await bus.once(Subjects.init);
+   * console.debug('Event received:', ctx.payload);
+   * ```
+   * @example With timeout
+   * ```typescript
+   * try {
+   *   const ctx = await bus.once(Subjects.init, { timeoutMs: 5000 });
+   * } catch (err) {
+   *   if (err instanceof OnceTimeoutError) {
+   *     console.debug('Timed out waiting for event');
+   *   }
+   * }
+   * ```
+   * @example With filter (waits for matching event)
+   * ```typescript
+   * const ctx = await bus.once(Subjects.message, {
+   *   filter: (payload) => payload.sessionId === expectedId
+   * });
+   * // Resolves only when a message with matching sessionId is received
+   * ```
+   * @example With AbortSignal
+   * ```typescript
+   * const controller = new AbortController();
+   * const promise = bus.once(Subjects.init, { signal: controller.signal });
+   * controller.abort(); // Cancels the wait
+   * ```
+   */
+  once<Subject extends Subjects & StrictNamespace, IsRequest = Subject['$meta']['isRequest'], IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : IsRequest extends false ? Subject : never, options?: Subject extends SubjectDefinition ? OnceOptions<Subject> : never): Promise<Subject extends SubjectDefinition ? Parameters<HandlerForSubjectDefinition<Subject>>[0] : never>;
+  /**
+   * Emit an event to all registered handlers.
+   *
+   * Events are fire-and-forget - all handlers execute in parallel.
+   * Handler errors are logged but don't stop other handlers from executing.
+   *
+   * **Note:** You cannot emit to wildcard patterns. Use concrete subject keys only.
+   * Handlers registered with wildcards will still receive the event if it matches.
+   * @param subject - Concrete event subject (wildcards not allowed)
+   * @param payload - Event payload
+   * @param options - Emit options (messageId, correlationId, transports)
+   *
+   * ## Transport Routing
+   * - `transports: undefined` - Send to ALL registered transports (default)
+   * - `transports: []` - Local only, don't send to any transports
+   * - `transports: ['ws', 'nats']` - Send only to specified transports
+   * @example
+   * ```typescript
+   * const { subjects: AgentSubjects } = MakaioBus.registerNamespace('agent', {
+   *   started: z.object({ agentId: z.string() }),
+   * });
+   *
+   * // Send to all transports (default)
+   * await emit(AgentSubjects.started, { agentId: 'agent-123' });
+   *
+   * // Local only, no transports
+   * await emit(
+   *   AgentSubjects.started,
+   *   { agentId: 'agent-123' },
+   *   { transports: [] }
+   * );
+   *
+   * // Send to specific transports
+   * await emit(
+   *   AgentSubjects.started,
+   *   { agentId: 'agent-123' },
+   *   { transports: ['websocket'] }
+   * );
+   *
+   * // With tracking IDs:
+   * await emit(
+   *   AgentSubjects.started,
+   *   { agentId: 'agent-123' },
+   *   { correlationId: 'user-action-123' }
+   * );
+   * ```
+   */
+  emit<Subject extends Subjects & StrictNamespace, IsRequest = Subject['$meta']['isRequest'], IsWildcard = (Subject['subject'] extends WildcardSubject ? true : false), IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : IsRequest extends false ? IsWildcard extends false ? Subject : never : never, payload: Subject['$meta']['payload'], options?: EmitOptions): Promise<void>;
+  /**
+   * Execute a request and wait for a response.
+   *
+   * Requests follow a middleware chain pattern - handlers are called in order
+   * until one calls setResult() or all handlers complete.
+   *
+   * **Note:** You cannot request via wildcard patterns. Use concrete subject keys only.
+   * Handlers registered with wildcards will still match if the subject matches their pattern.
+   * @param subject - Concrete request subject (wildcards not allowed)
+   * @param payload - Request payload
+   * @param options - Request options (timeout, correlationId, transports)
+   * @returns Response value
+   * @throws \{NoHandlerError\} If no handler is registered
+   * @throws \{TimeoutError\} If request times out
+   * @throws \{ValidationError\} If payload validation fails
+   * @throws \{RequestError\} If handler throws an error
+   *
+   * ## Transport Routing
+   * - `transports: undefined` - Send to ALL registered transports (default)
+   * - `transports: []` - Local only, don't send to any transports
+   * - `transports: ['ws', 'nats']` - Send only to specified transports
+   * @example
+   * ```typescript
+   * // ✅ Concrete subject
+   * const result = await request(
+   *   AgentSubjects.toolApprove,
+   *   { toolName: 'deleteFile', args: {}, toolCallId: 'call_123' },
+   *   { timeout: 10000 }
+   * );
+   * console.debug(result.approved);
+   *
+   * // ❌ Cannot use wildcards
+   * // await request('agent.*', { ... }); // Type error
+   *
+   * // With specific transports
+   * const result = await request(
+   *   AgentSubjects.toolApprove,
+   *   { toolName: 'deleteFile', args: {}, toolCallId: 'call_123' },
+   *   { transports: ['websocket'], timeout: 10000 }
+   * );
+   * ```
+   */
+  request<Subject extends Subjects & StrictNamespace, IsRequest = Subject['$meta']['isRequest'], IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : IsRequest extends true ? Subject : never, payload: Subject['$meta']['payload']['request'], options?: RequestOptions): Promise<IsRequest extends true ? Subject['$meta']['payload']['response'] : never>;
+  /**
+   * Execute a request, returning a discriminated union instead of throwing for missing handlers.
+   *
+   * Use for optional services. Only NoHandlerError is caught - other errors propagate.
+   * @see {@link OptionalResult} for return type details
+   */
+  requestOptional<Subject extends Subjects & StrictNamespace, IsRequest = Subject['$meta']['isRequest'], IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : IsRequest extends true ? Subject : never, payload: Subject['$meta']['payload']['request'], options?: RequestOptions): Promise<OptionalResult<IsRequest extends true ? Subject['$meta']['payload']['response'] : never>>;
+  /**
+   * Execute a broadcast request and collect responses from ALL handlers.
+   *
+   * Unlike `request()` which uses a middleware chain and returns the first result,
+   * `broadcast()` executes all handlers in parallel and aggregates their responses.
+   *
+   * Use for discovery patterns where multiple nodes may respond (e.g., fs.listSources).
+   *
+   * **Note:** You cannot broadcast via wildcard patterns. Use concrete subject keys only.
+   * Handlers registered with wildcards will still match if the subject matches their pattern.
+   *
+   * **Handler Usage:**
+   * Handlers should call `ctx.identify(nodeId)` before `ctx.setResult()` to tag their response.
+   * If `identify()` is not called, the response is tagged as 'anonymous'.
+   * @param subject - Concrete request subject (wildcards not allowed)
+   * @param payload - Request payload
+   * @param options - Request options (timeout, correlationId)
+   * @returns Array of \{ nodeId, payload \} responses from all handlers
+   * @example
+   * ```typescript
+   * // Discover all filesystem sources from all nodes
+   * const results = await MakaioBus.broadcast(FileSystemSubjects.listSources, \{\});
+   * // results: [
+   * //   \{ nodeId: 'local', payload: \{ sources: [...] \} \},
+   * //   \{ nodeId: 'container-1', payload: \{ sources: [...] \} \},
+   * // ]
+   *
+   * // Aggregate sources
+   * const allSources = results.flatMap(r => r.payload.sources);
+   * ```
+   */
+  broadcast<Subject extends Subjects & StrictNamespace, IsRequest = Subject['$meta']['isRequest'], IsChannel = Subject['$meta']['channel']>(subject: IsChannel extends true ? never : IsRequest extends true ? Subject : never, payload: Subject['$meta']['payload']['request'], options?: RequestOptions): Promise<BroadcastResult<IsRequest extends true ? Subject['$meta']['payload']['response'] : never>[]>;
+  scoped: <Domain extends string, Subjects extends SubjectRecord, F, Sc extends Record<string, SubjectSchema>>(input: BusNamespace<Domain, Subjects, F, Sc>, context?: MakaioBusContext) => ScopedBus<Domain>;
+  /**
+   * Create a filtered bus with a base payload filter.
+   *
+   * The filter is automatically applied to all `on()` and `once()` calls.
+   *
+   * Optionally provide a type parameter for type-safe filter keys.
+   * @param filter - Base filter to apply to all subscriptions
+   * @returns FilteredBus with the specified filter
+   * @example
+   * ```typescript
+   * // Untyped (loose) - any keys allowed
+   * const agentBus = MakaioBus.withFilter({ agentId: this.agentId });
+   *
+   * // Type-safe filter keys
+   * interface AgentPayload { agentId: string; sessionId: string }
+   * const strictBus = MakaioBus.withFilter<AgentPayload>({ agentId: 'x' });
+   * ```
+   */
+  withFilter: <Payload = unknown>(filter: [unknown] extends [Payload] ? PayloadFilter : TypedPayloadFilter<Payload>) => IFilteredBus<NamespaceDomain extends string ? NamespaceDomain : string>;
+  /**
+   * Register a handler that receives ALL messages (events and requests) across all namespaces.
+   *
+   * **Debugging/Testing Only:** Noops in production (process.env.NODE_ENV === 'production').
+   * Useful for logging, debugging, and test assertions that need visibility into all bus activity.
+   *
+   * Handler receives complete metadata: type, subject, namespace, payload, messageId, correlationId.
+   * @param handler - Function to invoke for every message
+   * @returns Unsubscribe function (noop in production)
+   * @example
+   * ```typescript
+   * const unsubscribe = bus.__onAny((context) => {
+   *   console.debug(`[${context.type}] ${context.namespace}:${context.subject}`, context.payload);
+   * });
+   * ```
+   */
+  __onAny: (handler: AnyHandler) => () => void;
+  __resetHandlers?: () => void;
+  /**
+   * Register a transport by its name property.
+   *
+   * Convenience method that delegates to `getContext().transportRegistry.registerTransport()`.
+   * The transport's `name` property is used as the registry key.
+   * @param transport - Transport to register
+   * @returns Registration object with `unregister` and `ready` promise
+   */
+  registerTransport(transport: BusTransport): TransportRegistration;
+  /**
+   * Unregister a transport by name.
+   *
+   * No-op if no transport is registered under that name.
+   * @param name - Transport name to unregister
+   */
+  unregisterTransport(name: string): void;
+  /**
+   * Disconnect all registered transports and clear the transport map.
+   *
+   * Convenience method for tearing down a bus instance. The inverse of
+   * passing `transports` to `createBusInstance()` or calling
+   * `registerTransport()` individually.
+   */
+  disconnect(): void;
+  /**
+   * Trigger an immediate reconnection attempt on all disconnected transports.
+   *
+   * Delegates to each transport's `reconnect()` method if available. For
+   * transports with exponential-backoff reconnection (e.g. WebSocket), this
+   * wakes the backoff sleep and returns once the attempt is *initiated* — not
+   * once the connection is established. For one-shot transports it resolves
+   * after the connect attempt completes. Failures are logged but do not reject
+   * this promise. No-op when all transports are already connected.
+   */
+  reconnect(): Promise<void>;
+  /**
+   * Resolves when all transports registered at connect-time have completed
+   * subscribe-sync. If {@link connect} was called with the default `awaitReady: true`,
+   * this is already resolved when `connect()` returns. If `awaitReady: false` was used,
+   * await this to ensure readiness before dispatching requests.
+   *
+   * Resolves immediately if no transports are registered or `connect()` has not been called.
+   */
+  readonly ready: Promise<void>;
+  /**
+   * Connect all registered transports and optionally await subscribe-sync readiness.
+   *
+   * Calls `transport.connect()` on every transport registered by this bus instance.
+   * If any transport fails to connect, all transports are disconnected and unregistered
+   * (rollback) before the error is re-thrown. Pass `{ awaitReady: false }` to resolve
+   * as soon as sockets are open without waiting for the subscribe-sync handshake.
+   * Concurrent calls are safe — a second in-flight call awaits the same promise. Once
+   * sockets are open, subsequent calls are no-ops unless a prior
+   * `connect({ awaitReady: false })` left the readiness handshake pending; in that case,
+   * default `connect()` still awaits `bus.ready`.
+   * @param options - Connection options (see {@link ConnectOptions})
+   * @throws If any transport's `connect()` or `ready` promise rejects (after rollback)
+   */
+  connect(options?: ConnectOptions): Promise<void>;
+  getContext(): MakaioBusContext;
+  /**
+   * Register a namespace from a `BusNamespaceDefinition` created by `createBusNamespace()`.
+   *
+   * Returns a `BusNamespace` that extends the definition with a `scopedBus()` method.
+   * @param definition - Namespace definition created by `createBusNamespace()` from `@makaio/core`
+   * @returns Registered namespace with `scopedBus()` and pre-computed FilterPayload type
+   */
+  registerNamespace<Domain extends string, Schemas extends Record<string, SubjectSchema>>(definition: BusNamespaceDefinition<Domain, Schemas>): BusNamespace<Domain, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Schemas>;
+  /**
+   * Register multiple namespaces in a single call.
+   *
+   * Convenience wrapper for composition roots that register a catalog of namespaces at boot:
+   * ```typescript
+   * MakaioBus.registerNamespaces(FrameworkContractNamespaces);
+   * ```
+   * @param definitions - Array of namespace definitions to register
+   */
+  registerNamespaces(definitions: readonly RegistrableBusNamespaceDefinition[]): void; /** Get the schema for a registered subject, or undefined if not found. */
+  getSchema<T extends SubjectDefinition>(subject: T | string): SubjectSchema | undefined;
+  /**
+   * Extend a registered subject's schema with additional fields.
+   *
+   * Adds new root-level fields to the Zod schema used for dev-mode validation and
+   * widens the TypeScript payload type. Successive calls accumulate — two packages
+   * can independently extend the same subject without overwriting each other.
+   *
+   * The returned value is the same runtime SubjectDefinition object — only the
+   * TypeScript type is widened. Bus routing is unaffected.
+   * @param subject - SubjectDefinition from a registered namespace
+   * @param extensions - For request subjects: `{ request?: { field: z.string() }, response?: {...} }`.
+   *   For event subjects: `{ field: z.string() }` (flat record of additional Zod fields).
+   * @returns The same SubjectDefinition with wider TypeScript types
+   */
+  extendSubject<SD extends Subjects & StrictNamespace, Ext extends SubjectExtension<SD>>(subject: SD, extensions: Ext): ExtendedSubjectDefinition<SD, Ext>;
+};
+//#endregion
+//#region packages/bus-core/src/utils/transport.d.ts
+/**
+ * Detects a "no handler" error for a specific request subject.
+ *
+ * Works for both in-process {@link NoHandlerError} instances and deserialized
+ * errors that carry a `code` + `subject` after a transport round-trip.
+ * The `subject` field is preserved by transport error serialization, so no
+ * fragile message-string matching is needed.
+ * @param error - Error from a relayed request or transport response
+ * @param fullSubject - Full request subject key (namespace.subject)
+ * @returns True when the error indicates no local handler for this subject
+ */
+declare function isNoHandlerErrorForSubject(error: unknown, fullSubject: string): boolean;
+/**
+ * Extracts the full subject key from a bus message.
+ *
+ * Combines the namespace and subject into the full subject key format
+ * (namespace.subject) used for handler lookups and subscription matching.
+ * Returns null if the message doesn't contain the required fields.
+ * @param message - Bus message (event or request)
+ * @returns Full subject key in format "namespace.subject", or null if fields are missing
+ * @example
+ * ```typescript
+ * const message: BusMessage = {
+ *   type: 'event',
+ *   subject: 'log',
+ *   namespace: 'adapter',
+ *   payload: { message: 'Hello' },
+ *   messageId: 'msg-123',
+ * };
+ *
+ * const fullSubject = getSubjectFromBusMessage(message);
+ * // Returns: "adapter.log"
+ * ```
+ */
+declare function getSubjectFromBusMessage(message: BusMessage): string | null;
+/**
+ * Reconstruct an Error from a structured transport error payload.
+ *
+ * Preserves `code` and arbitrary `data` properties so callers can
+ * inspect them for programmatic error handling.
+ * @param transportError - The structured error received over the wire
+ * @returns An Error with `code` and data properties attached
+ */
+declare function deserializeTransportError(transportError: BusTransportError): Error;
+//#endregion
+//#region packages/bus-core/src/utils/payload-filter.d.ts
+/**
+ * Get a nested value from an object using dot-notation path.
+ * @param obj - Object to traverse
+ * @param path - Dot-notation path (e.g., 'raw.msg.type')
+ * @returns Value at path, or undefined if not found
+ * @example
+ * ```typescript
+ * const obj = { raw: { msg: { type: 'event' } } };
+ * getPath(obj, 'raw.msg.type'); // 'event'
+ * getPath(obj, 'raw.missing'); // undefined
+ * ```
+ */
+declare function getPath(obj: unknown, path: string): unknown;
+/**
+ * Check if a payload matches all filter conditions.
+ *
+ * All conditions are ANDed together - all must match for the filter to pass.
+ * @param payload - Message payload to check
+ * @param filter - Filter specification with field paths and operators
+ * @returns true if payload matches all filter conditions
+ * @example
+ * ```typescript
+ * const payload = {
+ *   agentId: 'agent-123',
+ *   raw: { msg: { type: 'session_configured' } },
+ *   status: 'active',
+ * };
+ *
+ * // All conditions must match
+ * matchesFilter(payload, {
+ *   agentId: 'agent-123',
+ *   'raw.msg.type': 'session_configured',
+ * }); // true
+ *
+ * // With operators
+ * matchesFilter(payload, {
+ *   status: { $in: ['active', 'pending'] },
+ * }); // true
+ *
+ * matchesFilter(payload, {
+ *   error: { $exists: false },
+ * }); // true (no error field)
+ * ```
+ */
+declare function matchesFilter(payload: unknown, filter: PayloadFilter): boolean;
+/**
+ * Merge two payload filters together.
+ *
+ * Later filter values override earlier ones for the same path.
+ * @param base - Base filter
+ * @param override - Filter to merge in (overrides base)
+ * @returns Merged filter
+ */
+declare function mergeFilters(base: PayloadFilter | undefined, override: PayloadFilter | undefined): PayloadFilter | undefined;
+//#endregion
+//#region packages/bus-core/src/utils/url-config.d.ts
+/**
+ * Bus URL configuration utilities.
+ *
+ * Provides consistent parsing of bus URL environment variables across
+ * all consumers (Electron, Vite configs, etc.) with correct handling of:
+ *
+ * - Default localhost development URLs (explicit port 6252)
+ * - User-provided production URLs (preserve protocol defaults like wss:// to 443)
+ */
+/**
+ * Parsed bus URL configuration.
+ */
+interface BusUrlConfig {
+  /**
+   * The full URL href for client connections.
+   * For default localhost, includes explicit port.
+   * For user-provided URLs, preserves original (protocol defaults intact).
+   */
+  href: string;
+  /**
+   * The port number for server binding.
+   * - For default localhost: 6252
+   * - For user-provided URLs with explicit port: that port
+   * - For user-provided URLs without port: undefined (use protocol default)
+   */
+  port: number | undefined;
+  /**
+   * Whether this is the default localhost URL (no env var set).
+   */
+  isDefault: boolean;
+}
+/**
+ * Parses the bus URL from environment variable with correct default handling.
+ *
+ * Key behaviors:
+ * - No env var: Returns default `ws://localhost:6252/bus` with explicit port 6252
+ * - Env var with explicit port: Uses that port
+ * - Env var without port (e.g., `wss://bus.example.com/bus`): Preserves URL as-is,
+ * returns `port: undefined` so protocol defaults (443 for wss://) are respected
+ * @param envValue - The value of MAKAIO_BUS_URL environment variable (or undefined)
+ * @returns Parsed configuration with href, port, and isDefault flag
+ * @example
+ * ```typescript
+ * // No env var - local development
+ * const config = parseBusUrl(undefined);
+ * // { href: 'ws://localhost:6252/bus', port: 6252, isDefault: true }
+ *
+ * // Production with explicit port
+ * const config = parseBusUrl('wss://bus.example.com:9000/bus');
+ * // { href: 'wss://bus.example.com:9000/bus', port: 9000, isDefault: false }
+ *
+ * // Production with protocol default port
+ * const config = parseBusUrl('wss://bus.example.com/bus');
+ * // { href: 'wss://bus.example.com/bus', port: undefined, isDefault: false }
+ * ```
+ */
+declare function parseBusUrl(envValue: string | undefined): BusUrlConfig;
+//#endregion
+//#region packages/bus-core/src/utils/subscription-matching.d.ts
+/**
+ * Subscription pattern matching utilities.
+ *
+ * Supports exact matches, subject wildcards (e.g., 'adapter.*'),
+ * and namespace wildcards (e.g., 'adapter:*').
+ *
+ * ## Pattern Matching Decision Tree
+ *
+ * ```
+ * Pattern ends with...?
+ * │
+ * ├─ No asterisk (e.g., 'adapter.log')
+ * │  └─ Exact match: subject === pattern
+ * │
+ * ├─ ':*' (e.g., 'adapter:*', 'adapter:claudeCode:*')
+ * │  └─ Namespace wildcard: matches child namespace subjects
+ * │     • 'adapter:*' matches 'adapter:claudeCode.log'
+ * │     • 'adapter:*' matches 'adapter:claudeCode:sdk.thinking'
+ * │     • 'adapter:*' does NOT match 'adapter.log' (no child namespace)
+ * │
+ * └─ '.*' (e.g., 'adapter.*', 'adapter:claudeCode.*')
+ *    └─ Subject wildcard: matches subjects in specific namespace
+ *       • 'adapter.*' matches 'adapter.log', 'adapter.error'
+ *       • 'adapter.*' does NOT match 'adapter:claudeCode.log'
+ *       • 'adapter:claudeCode.*' matches 'adapter:claudeCode.log'
+ * ```
+ *
+ * ## Colon vs Dot Semantics
+ *
+ * - **Colon (`:`)** = namespace hierarchy boundary
+ *   - `adapter:claudeCode` is a child namespace of `adapter`
+ *   - Wildcard `:*` crosses this boundary
+ *
+ * - **Dot (`.`)** = subject separator within namespace
+ *   - `adapter.log` is a subject in the `adapter` namespace
+ *   - Wildcard `.*` enumerates subjects, doesn't cross namespace boundaries
+ */
+/**
+ * Check if a subject matches a subscription pattern.
+ *
+ * Patterns can be:
+ * - Exact match: 'adapter:claudeCode.log' matches only 'adapter:claudeCode.log'
+ * - Subject wildcard: 'adapter:claudeCode.*' matches 'adapter:claudeCode.log', 'adapter:claudeCode.initialized'
+ * - Namespace wildcard: 'adapter:*' matches subjects from child namespaces
+ * @param subject - Subject to match (e.g., 'adapter:claudeCode:sdk.thinking')
+ * @param pattern - Subscription pattern (e.g., 'adapter:*', 'adapter:claudeCode.*', 'adapter:claudeCode.log')
+ * @returns true if subject matches pattern
+ * @example
+ * ```typescript
+ * // Exact match
+ * matchesSubscription('adapter.log', 'adapter.log')
+ * // → true
+ *
+ * // Subject wildcard - matches subjects in namespace
+ * matchesSubscription('adapter.log', 'adapter.*')
+ * // → true
+ * matchesSubscription('adapter.initialized', 'adapter.*')
+ * // → true
+ * matchesSubscription('adapter:claudeCode.log', 'adapter.*')
+ * // → false (different namespace - adapter:claudeCode vs adapter)
+ *
+ * // Namespace wildcard - matches child namespaces
+ * matchesSubscription('adapter:claudeCode.initialized', 'adapter:*')
+ * // → true (claudeCode is child of adapter)
+ * matchesSubscription('adapter:claudeCode:sdk.thinking', 'adapter:*')
+ * // → true (sdk is descendant of adapter)
+ * matchesSubscription('adapter:gpt.initialized', 'adapter:*')
+ * // → true (gpt is child of adapter)
+ *
+ * // Multi-level namespace wildcard
+ * matchesSubscription('adapter:claudeCode:sdk.thinking', 'adapter:claudeCode:*')
+ * // → true (sdk is child of adapter:claudeCode)
+ * matchesSubscription('adapter:gpt.initialized', 'adapter:claudeCode:*')
+ * // → false (different branch)
+ * ```
+ */
+declare function matchesSubscription(subject: string, pattern: string): boolean;
+/**
+ * Check if a subject matches any pattern in a collection.
+ * @param subject - Subject to match
+ * @param patterns - Collection of subscription patterns
+ * @returns true if subject matches at least one pattern
+ * @example
+ * ```typescript
+ * matchesAnySubscription('adapter.log', new Set(['adapter.*', 'agent.*']))
+ * // → true (matches 'adapter.*')
+ *
+ * matchesAnySubscription('adapter:claudeCode.initialized', new Set(['adapter:*']))
+ * // → true (matches 'adapter:*')
+ *
+ * matchesAnySubscription('session.started', new Set(['adapter.*', 'adapter:*']))
+ * // → false (no match)
+ *
+ * matchesAnySubscription('adapter.log', new Set())
+ * // → false (empty patterns)
+ * ```
+ */
+declare function matchesAnySubscription(subject: string, patterns: Iterable<string>): boolean;
+//#endregion
+//#region packages/bus-core/src/errors/bus-error.d.ts
+/**
+ * Base error class for all bus-related errors.
+ */
+declare class BusError extends MakaioError {
+  readonly subject?: string | undefined;
+  /**
+   * @param message - Human-readable error description
+   * @param subject - Fully-qualified subject name (namespace.subject) for the failed operation
+   */
+  constructor(message: string, subject?: string | undefined);
+}
+//#endregion
+//#region packages/bus-core/src/errors/channel-auth-error.d.ts
+/**
+ * Thrown when channel authentication fails during the handshake.
+ * Indicates the provided token does not match the endpoint's expected token.
+ */
+declare class ChannelAuthError extends BusError {
+  /**
+   * @param endpoint - The endpoint name that failed authentication
+   */
+  constructor(endpoint: string);
+}
+//#endregion
+//#region packages/bus-core/src/errors/channel-closed-error.d.ts
+/**
+ * Thrown when an operation is attempted on a closed DirectChannel.
+ * All pending requests are rejected with this error when a channel closes.
+ */
+declare class ChannelClosedError extends BusError {
+  /**
+   * @param channelId - The identifier of the channel that is closed
+   */
+  constructor(channelId: string);
+}
+//#endregion
+//#region packages/bus-core/src/errors/channel-only-error.d.ts
+/**
+ * Thrown when a channel-only subject is used directly on the public bus.
+ * Channel subjects must be routed through a DirectChannel, not the public bus API.
+ */
+declare class ChannelOnlyError extends BusError {
+  /**
+   * @param subject - The channel-only subject that was used on the public bus
+   */
+  constructor(subject: string);
+}
+//#endregion
+//#region packages/bus-core/src/errors/local-subject-error.d.ts
+/**
+ * Thrown when a remote peer attempts to invoke a local-only subject over a
+ * transport. Local subjects are never serializable and must not be routed
+ * across process or network boundaries.
+ */
+declare class LocalSubjectError extends BusError {
+  /**
+   * @param subject - The local-only subject that was invoked remotely
+   */
+  constructor(subject: string);
+}
+//#endregion
+//#region packages/bus-core/src/errors/no-handler-error.d.ts
+/**
+ * Stable error code for "no handler registered" failures.
+ */
+declare const NO_HANDLER_ERROR_CODE: "NO_HANDLER";
+/**
+ * Error thrown when no handler is registered for a request.
+ */
+declare class NoHandlerError extends BusError {
+  readonly code: "NO_HANDLER";
+  /**
+   * @param subject - Fully-qualified subject name for which no handler was found
+   */
+  constructor(subject: string);
+}
+//#endregion
+//#region packages/bus-core/src/errors/request-error.d.ts
+/**
+ * Generic error thrown when a request fails for any other reason.
+ */
+declare class RequestError extends BusError {
+  readonly cause?: Error | undefined;
+  /**
+   * @param subject - Fully-qualified subject name for the failed request
+   * @param message - Human-readable description of the failure
+   * @param cause - Underlying error thrown by the handler, if any
+   */
+  constructor(subject: string, message: string, cause?: Error | undefined);
+}
+//#endregion
+//#region packages/bus-core/src/errors/timeout-error.d.ts
+/**
+ * Error thrown when a request times out.
+ */
+declare class TimeoutError extends BusError {
+  readonly timeoutMs: number;
+  /**
+   * @param subject - Fully-qualified subject name for the timed-out request
+   * @param timeoutMs - Timeout duration in milliseconds that was exceeded
+   */
+  constructor(subject: string, timeoutMs: number);
+}
+//#endregion
+//#region packages/bus-core/src/errors/validation-error.d.ts
+/**
+ * Error thrown when payload validation fails.
+ */
+declare class ValidationError extends BusError {
+  readonly zodError: z.ZodError;
+  /**
+   * @param subject - Fully-qualified subject name for which validation failed
+   * @param zodError - Zod validation error containing the individual issue details
+   */
+  constructor(subject: string, zodError: z.ZodError);
+}
+//#endregion
+//#region packages/bus-core/src/bus.d.ts
+/**
+ * Creates a new bus context containing handler registries and shared state.
+ *
+ * Used internally by createBusInstance to manage event and request handlers.
+ * Can be used to create isolated bus instances (e.g., for testing) by providing
+ * separate handler maps per instance.
+ * @returns A new MakaioBusContext instance with empty handler registries
+ */
+declare const createBusContext: () => MakaioBusContext;
+/**
+ * Options for creating a bus instance.
+ */
+interface CreateBusOptions<Namespace extends string | undefined = undefined> {
+  /** Pre-created context. Omit for a fresh one. */
+  context?: MakaioBusContext;
+  /** Namespace scope (e.g. 'adapter:claudeCode'). */
+  namespace?: Namespace;
+  /** Transports to register immediately after creation. */
+  transports?: BusTransport[];
+}
+/**
+ * Creates a new bus instance with optional context, namespace isolation, and transports.
+ *
+ * The bus instance provides methods for type-safe event emission, request/response
+ * patterns, handler registration, and namespace management. Handlers use
+ * SubjectDefinition objects (not strings) for full type safety and schema validation.
+ * @param options - Optional creation options. `context` defaults to a fresh `createBusContext()`.
+ * `namespace` scopes the instance (e.g. `'adapter:claudeCode'`). `transports` are registered
+ * immediately after creation.
+ * @returns A new IMakaioBus instance with methods for on, emit, request, scoped, and schema management
+ */
+declare function createBusInstance<Namespace extends string | undefined = undefined>(options?: CreateBusOptions<Namespace>): IMakaioBus<Namespace>;
+/**
+ * Main bus instance with unified API for events and request/response flows.
+ *
+ * Provides a singleton bus that manages schema-backed messaging with type-safe
+ * subjects, namespace isolation, and transport routing. Use this as the central
+ * coordination point for all cross-component communication.
+ *
+ * **Core Methods:**
+ * - `registerNamespace()` - Register typed subjects with Zod schemas
+ * - `on()` - Subscribe to events or requests with typed handlers
+ * - `emit()` - Fire-and-forget event broadcasting
+ * - `request()` - Request-response with middleware chain
+ * - `scoped()` - Create namespace-scoped bus instance
+ *
+ * **Key Features:**
+ * - Type-safe SubjectDefinition objects (no raw strings)
+ * - Runtime validation in development (Zod schemas)
+ * - Wildcard pattern matching with `.$all`
+ * - Transport-backed remote messaging
+ * - Hierarchical namespace support (e.g., `adapter:claudeCode`)
+ * - Middleware chains for request processing
+ * @example Basic usage
+ * ```typescript
+ * import { MakaioBus } from '@makaio/framework/bus';
+ * import { z } from 'zod';
+ *
+ * // Register namespace with typed subjects
+ * const { subjects } = MakaioBus.registerNamespace('agent', {
+ *   started: z.object({ agentId: z.string() }),
+ *   toolApprove: {
+ *     request: z.object({ toolName: z.string() }),
+ *     response: z.object({ approved: z.boolean() }),
+ *   },
+ * });
+ *
+ * // Subscribe to events
+ * MakaioBus.on(subjects.started, (context) => {
+ *   console.debug('Agent started:', context.payload.agentId);
+ * });
+ *
+ * // Emit events
+ * await MakaioBus.emit(subjects.started, { agentId: 'agent-123' });
+ *
+ * // Handle requests
+ * MakaioBus.on(subjects.toolApprove, (context) => {
+ *   context.setResult({ approved: true });
+ * });
+ *
+ * // Make requests
+ * const result = await MakaioBus.request(subjects.toolApprove, {
+ *   toolName: 'deleteFile',
+ * });
+ * ```
+ */
+declare const MakaioBus: IMakaioBus;
+//#endregion
+//#region packages/bus-core/src/channel/types.d.ts
+/**
+ * Encrypted point-to-point communication channel over the bus.
+ *
+ * Provides a bus-compatible interface (on, once, emit, request) where all
+ * payloads are encrypted with a shared AES-256-GCM key derived via ECDH.
+ * Observers, middleware, and transport loggers only see opaque `{ iv, data }` payloads.
+ * Channel messages ride the normal bus transport layer unless the caller
+ * explicitly constrains routing via the underlying bus configuration.
+ */
+interface IDirectChannel {
+  /** Unique channel identifier (used in channel-scoped subject namespaces). */
+  readonly channelId: string;
+  /**
+   * Register an event or request handler on this channel.
+   * The handler receives decrypted payloads — encryption is transparent.
+   * @param subject - Subject definition (channel or non-channel subjects both accepted)
+   * @param handler - Handler function matching the subject's schema
+   * @param options - Handler options (priority, etc.)
+   * @returns Unsubscribe function
+   */
+  on<Subject extends SubjectDefinition>(subject: Subject, handler: HandlerForSubjectDefinition<Subject>, options?: OnOptions): () => void;
+  /**
+   * Register a one-time handler that auto-unsubscribes after first invocation.
+   * @param subject - Subject definition
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  once<Subject extends SubjectDefinition>(subject: Subject, handler: HandlerForSubjectDefinition<Subject>): () => void;
+  /**
+   * Fire-and-forget encrypted event to the peer.
+   * @param subject - Subject definition
+   * @param payload - Event payload (will be encrypted before dispatch)
+   */
+  emit<Subject extends SubjectDefinition>(subject: Subject, payload: Subject['$meta']['payload']): Promise<void>;
+  /**
+   * Encrypted request-response to the peer.
+   * @param subject - Subject definition (must be a request subject)
+   * @param payload - Request payload (will be encrypted before dispatch)
+   * @param options - Request options (timeout, etc.)
+   * @returns Decrypted response
+   * @throws \{ChannelClosedError\} If the channel is closed
+   * @throws \{NoHandlerError\} If the peer has no handler for this subject
+   */
+  request<Subject extends SubjectDefinition>(subject: Subject, payload: Subject['$meta']['payload']['request'], options?: {
+    timeout?: number;
+  }): Promise<Subject['$meta']['payload']['response']>;
+  /**
+   * Encrypted request-response, returns `handled: false` instead of throwing NoHandlerError.
+   * @param subject - Subject definition (must be a request subject)
+   * @param payload - Request payload
+   * @param options - Request options
+   * @returns OptionalResult wrapping the response
+   */
+  requestOptional<Subject extends SubjectDefinition>(subject: Subject, payload: Subject['$meta']['payload']['request'], options?: {
+    timeout?: number;
+  }): Promise<OptionalResult<Subject['$meta']['payload']['response']>>;
+  /**
+   * Close the channel. Notifies peer, rejects pending requests,
+   * unsubscribes all handlers, and discards the shared encryption key.
+   */
+  close(): void;
+}
+/**
+ * Options for creating a channel endpoint.
+ */
+interface ChannelEndpointOptions {
+  /** Capability token that clients must present to open this channel. */
+  token: string;
+}
+/**
+ * A registered channel endpoint that accepts incoming connections.
+ */
+interface ChannelEndpoint {
+  /** The endpoint name (e.g., 'credentials'). */
+  readonly name: string;
+  /** The capability token clients need to open this channel. */
+  readonly token: string;
+  /** Unregister the endpoint, preventing new connections. */
+  close(): void;
+}
+//#endregion
+//#region packages/bus-core/src/channel/system-namespace.d.ts
+/**
+ * Schema for the system.channel.open handshake request.
+ *
+ * This is the only public-bus subject the channel system introduces.
+ * The handshake includes a capability token that acts as a bearer
+ * credential. Public keys are not secret, but the token grants channel
+ * access and should only travel over trusted transports. Callers should
+ * prefer `transports: []` for same-process channels.
+ */
+declare const SystemChannelSchemas: {
+  'channel.open': {
+    request: z.ZodObject<{
+      endpoint: z.ZodString;
+      token: z.ZodString;
+      clientPubKey: z.ZodString;
+      transports: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      channelId: z.ZodString;
+      endpointPubKey: z.ZodString;
+    }, z.core.$strip>;
+  };
+};
+//#endregion
+//#region packages/bus-core/src/channel/channel-endpoint.d.ts
+/**
+ * Register a channel endpoint that accepts encrypted point-to-point connections.
+ *
+ * Listens for `system.channel.open` requests. When a request arrives for this
+ * endpoint name with the correct token:
+ * 1. Performs the ECDH key exchange (generates a keypair, derives the shared secret).
+ * 2. Instantiates an {@link IDirectChannel} for the endpoint side.
+ * 3. Calls `callback` so the endpoint can register its channel-scoped handlers.
+ * 4. Returns the channel ID and the endpoint public key to the client.
+ *
+ * Multiple endpoints can coexist on the same bus context; each handles only
+ * requests whose `payload.endpoint` matches its own name.
+ * @param context - Bus context to register the endpoint handler on
+ * @param endpointName - Logical name for this endpoint (e.g., 'credentials')
+ * @param callback - Called with the new {@link IDirectChannel} once the handshake
+ *   is complete; use this to register channel handlers before the client receives
+ *   the handshake response
+ * @param options - Endpoint options including the shared capability token
+ * @returns A {@link ChannelEndpoint} handle whose `close()` unregisters the endpoint
+ */
+declare function createChannelEndpoint(context: MakaioBusContext, endpointName: string, callback: (channel: IDirectChannel) => void, options: ChannelEndpointOptions): ChannelEndpoint;
+/**
+ * Open an encrypted point-to-point channel to a registered endpoint.
+ *
+ * Performs the ECDH handshake via `system.channel.open`:
+ * 1. Generates an ephemeral ECDH keypair.
+ * 2. Sends the client public key and capability token to the endpoint.
+ * 3. Receives the channel ID and endpoint public key.
+ * 4. Derives the shared AES-256-GCM key from the client private key and endpoint
+ *    public key.
+ * 5. Returns a `IDirectChannel` ready for encrypted communication.
+ *
+ * By default the handshake is dispatched over all registered transports so the
+ * endpoint can reside in a different process. Pass `transports: []` to restrict
+ * the handshake (and the resulting channel) to the local process only — this is
+ * the correct choice whenever both sides are guaranteed to share the same bus
+ * context (e.g., credential service and its same-process callers).
+ * @param context - Bus context to use for the handshake request
+ * @param endpointName - Logical name of the endpoint to connect to
+ * @param options - Connection options including the shared capability token and
+ *   an optional transport allowlist (`transports: []` for local-only)
+ * @returns Resolved `IDirectChannel` once the handshake completes
+ * @throws \{RequestError\} If the handshake fails — for authentication failures, the
+ *   cause is a \{ChannelAuthError\}
+ * @throws \{NoHandlerError\} If no endpoint with the given name is registered
+ */
+declare function openChannel(context: MakaioBusContext, endpointName: string, options: {
+  token: string;
+  transports?: ReadonlyArray<BusTransportKeys>;
+}): Promise<IDirectChannel>;
+//#endregion
+//#region packages/bus-core/src/utils/correlation-tracker.d.ts
+/**
+ * Correlation tracker for request-response matching.
+ *
+ * Manages pending requests with timeout handling and automatic cleanup.
+ */
+/**
+ * Tracks correlation IDs for request-response matching.
+ *
+ * Provides automatic timeout handling and cleanup for pending requests.
+ * @example
+ * ```typescript
+ * const tracker = new CorrelationTracker();
+ *
+ * // Track a request with 5 second timeout
+ * const promise = tracker.track('correlation-123', 5000);
+ *
+ * // Later, resolve when response arrives
+ * tracker.resolve('correlation-123', { data: 'result' });
+ *
+ * // Or reject on error
+ * tracker.reject('correlation-123', new Error('Failed'));
+ * ```
+ */
+declare class CorrelationTracker {
+  private pending;
+  private static readonly DEFAULT_ABORT_MESSAGE;
+  /**
+   * Create a new correlation tracker.
+   */
+  constructor();
+  /**
+   * Track a pending request.
+   *
+   * Returns a promise that resolves when the response arrives or rejects on timeout.
+   * When `timeout` is `0`, no automatic timeout is set — the promise stays open
+   * until `resolve()` or `reject()` is called externally (e.g. by the caller's
+   * own `AbortSignal` or `pTimeout` wrapper).
+   * @param correlationId - Correlation ID for the request
+   * @param timeout - Timeout in milliseconds; `0` means no automatic timeout
+   * @param signal - Optional AbortSignal to cancel and cleanup the pending entry
+   * @returns Promise that resolves with the response result
+   */
+  track(correlationId: string, timeout: number, signal?: AbortSignal): Promise<unknown>;
+  /**
+   * Convert AbortSignal reasons into Error instances while preserving reason detail.
+   * @param signal - Abort signal associated with the pending request.
+   * @returns Normalized abort error preserving the original reason when available.
+   */
+  private getAbortError;
+  /**
+   * Resolve a pending request.
+   *
+   * Clears the timeout and removes the request from tracking.
+   * @param correlationId - Correlation ID for the request
+   * @param result - Response result
+   */
+  resolve(correlationId: string, result: unknown): void;
+  /**
+   * Reject a pending request.
+   *
+   * Clears the timeout and removes the request from tracking.
+   * @param correlationId - Correlation ID for the request
+   * @param error - Error to reject with
+   */
+  reject(correlationId: string, error: Error): void;
+  /**
+   * Cancel a pending request and remove its correlation entry.
+   * @param correlationId - Correlation ID for the request
+   * @param error - Optional cancellation error
+   */
+  cancel(correlationId: string, error?: Error): void;
+  /**
+   * Clean up all pending requests.
+   *
+   * Clears all timeouts and rejects all pending requests with a disconnection error.
+   */
+  cleanup(): void;
+}
+//#endregion
+//#region packages/bus-core/src/lifecycle-schemas.d.ts
+/** Payload emitted when a transport establishes or re-establishes a connection. */
+type ConnectedPayload = {
+  transport: string;
+};
+/** Payload emitted when a transport loses connection unexpectedly. */
+type DisconnectedPayload = {
+  transport: string;
+};
+//#endregion
+//#region packages/bus-core/src/lifecycle.d.ts
+/**
+ * Bus-level lifecycle subjects for subscribing to transport connection state changes.
+ *
+ * All subjects are local-only: they are never relayed across transports, as they
+ * describe the local bus's own connection state.
+ *
+ * Registration happens per-context inside `createBus()`.
+ * @example
+ * ```typescript
+ * import { BusLifecycle } from '@makaio/framework/bus';
+ *
+ * MakaioBus.on(BusLifecycle.connected, ({ payload }) => {
+ *   console.log('Transport connected:', payload.transport);
+ * });
+ *
+ * MakaioBus.on(BusLifecycle.disconnected, ({ payload }) => {
+ *   console.warn('Transport disconnected:', payload.transport);
+ * });
+ * ```
+ */
+declare const BusLifecycle: BusSubjects<FlatSubjectDefinitions<"bus:lifecycle", {
+  connected: LocalSubjectSchema<_$zod.ZodObject<{
+    transport: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+  disconnected: LocalSubjectSchema<_$zod.ZodObject<{
+    transport: _$zod.ZodString;
+  }, _$zod_v4_core0.$strip>>;
+}>, "bus:lifecycle">;
+//#endregion
+//#region packages/bus-core/src/extension-namespace-types.d.ts
+/**
+ * Extension point for extension namespace extensions.
+ *
+ * Use declaration merging to add extension-specific metadata or capabilities:
+ * @example
+ * ```typescript
+ * // In an extension package
+ * declare module '@makaio/framework/bus' {
+ *   interface ExtensionNamespaceExtensions {
+ *     customMetadata?: {
+ *       version: string;
+ *       author: string;
+ *     };
+ *   }
+ * }
+ * ```
+ */
+interface ExtensionNamespaceExtensions {}
+/**
+ * Extension namespace combines a pure bus namespace definition with
+ * extensible extension-specific properties.
+ *
+ * Wraps BusNamespaceDefinition with:
+ * - Automatic 'extension:' prefix for domain naming
+ * - Extension point for extension metadata via declaration merging
+ * @typeParam N - Extension name (without 'extension:' prefix)
+ * @typeParam Subjects - Subject record type from schemas
+ * @typeParam FilterPayload - Filter payload type for type-safe filtering
+ * @typeParam Ext - Extension type preserving specific metadata types
+ * @typeParam Schemas - Original schema record; drives narrow literal types on subjects.$meta
+ */
+interface ExtensionNamespace<N extends string = string, _Subjects extends SubjectRecord = SubjectRecord, _FilterPayload = unknown, Ext extends ExtensionNamespaceExtensions = ExtensionNamespaceExtensions, Schemas extends SchemaRecord = SchemaRecord> extends BusNamespaceDefinition<`extension:${N}`, Schemas> {
+  /**
+   * Extension name (without 'extension:' prefix).
+   */
+  readonly domain: N;
+  /**
+   * Extension properties added via declaration merging.
+   * @see ExtensionNamespaceExtensions
+   */
+  readonly extensions: Ext;
+}
+/**
+ * Configuration for creating an extension namespace.
+ * @typeParam Schemas - Schema record type for bus subjects
+ * @typeParam Ext - Extension type preserving specific metadata types
+ */
+interface ExtensionNamespaceConfig<Schemas extends SchemaRecord, Ext extends ExtensionNamespaceExtensions = ExtensionNamespaceExtensions> {
+  /**
+   * Bus subject schemas for extension operations.
+   * Can include both request-response and event schemas.
+   */
+  schemas: Schemas;
+  /**
+   * Extension properties (populated by declaration merging).
+   * @see ExtensionNamespaceExtensions
+   */
+  extensions?: Ext;
+}
+/**
+ * Infer the extension namespace type from config.
+ * @typeParam N - Extension name without the `extension:` prefix
+ * @typeParam Schemas - Schema record type for bus subjects
+ * @typeParam Ext - Extension type preserving specific metadata types
+ */
+type ExtensionNamespaceFromConfig<N extends string, Schemas extends SchemaRecord, Ext extends ExtensionNamespaceExtensions = ExtensionNamespaceExtensions> = ExtensionNamespace<N, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Ext, Schemas>;
+//#endregion
+//#region packages/bus-core/src/utils/transport-helpers.d.ts
+/**
+ * Check if a client/tab wants to receive a message based on subscriptions and filters.
+ *
+ * **Filtering logic:**
+ * - No subscriptions = receive all (default broadcast mode)
+ * - With subscriptions: check if message subject matches any subscription pattern
+ * - Apply payload filters if the client has filters for this subject
+ * @param subject - The message subject (if any)
+ * @param payload - The message payload (if any)
+ * @param subscriptions - Set of subscription patterns
+ * @param filters - Map of payload filters per subject
+ * @returns true if the client should receive the message
+ */
+declare function shouldReceiveMessage(subject: string | undefined, payload: unknown, subscriptions: Set<string>, filters: Map<string, PayloadFilter>): boolean;
+/**
+ * Handle response messages for correlation tracking.
+ *
+ * Processes both regular response and broadcast-response messages,
+ * resolving or rejecting the corresponding correlation promise.
+ * @param message - Decoded bus message
+ * @param correlations - Correlation tracker instance
+ * @returns true if the message was a response and was handled
+ */
+declare function handleCorrelationResponse(message: BusMessage, correlations: CorrelationTracker): boolean;
+/**
+ * Track correlation for request/broadcast messages and return appropriate result type.
+ *
+ * **Behavior by message type:**
+ * - Request: Returns promise tracking correlation (resolves to response payload)
+ * - Broadcast: Returns promise tracking correlation (resolves to array of results)
+ * - Other: Returns true immediately (no correlation tracking needed)
+ *
+ * **Timeout semantics:**
+ * Pass `0` to disable automatic timeout — the correlation entry stays open
+ * until resolved or rejected externally. All callers must supply an explicit
+ * value; there is no default so callers cannot accidentally rely on a hidden timeout.
+ * @param message - Bus message to process
+ * @param correlations - Correlation tracker instance
+ * @param timeout - Timeout in milliseconds; `0` means no automatic timeout
+ * @param signal - Optional AbortSignal forwarded to correlation tracking cleanup
+ * @returns Promise resolving to response data, broadcast results, or boolean
+ */
+declare function trackMessageCorrelation<TMessage extends BusMessage>(message: TMessage, correlations: CorrelationTracker, timeout: number, signal?: AbortSignal): Promise<TMessage extends BusRequestMessage ? unknown : TMessage extends BusBroadcastMessage ? Array<{
+  nodeId: string;
+  payload: unknown;
+}> : boolean>;
+/**
+ * Serialize an error into a transport-safe structure.
+ *
+ * Preserves `subject` alongside `code` so that `isNoHandlerErrorForSubject`
+ * can match deserialized errors without fragile message-string comparisons.
+ * @param error - The error to serialize
+ * @returns Structured error payload
+ */
+declare function serializeTransportError(error: unknown): BusTransportError;
+//#endregion
+//#region packages/bus-core/src/subscribe-message.d.ts
+/**
+ * Per-subject subscription state tracked locally on a client transport.
+ */
+interface SubscriptionEntry {
+  /** Optional payload filter for server-side smart-routing. */
+  filter?: PayloadFilter;
+  /** Handler priorities registered for this subject. Empty array = event-only. */
+  priorities: number[];
+}
+/**
+ * Build a BusSubscribeMessage from local subscription state.
+ * @param subscriptions - Map of subject patterns to their subscription entries
+ * @returns Wire-format subscribe message
+ */
+declare function buildSubscribeMessage(subscriptions: Map<string, SubscriptionEntry>): BusSubscribeMessage;
+/**
+ * Build a BusUnsubscribeMessage for specific subjects and priorities.
+ * @param subjects - Map of subject patterns to priorities being removed
+ * @returns Wire-format unsubscribe message
+ */
+declare function buildUnsubscribeMessage(subjects: Record<string, number[]>): BusUnsubscribeMessage;
+//#endregion
+//#region packages/bus-core/src/create-extension-namespace.d.ts
+type Whitespace = ' ' | '\n' | '\r' | '\t' | '\v' | '\f' | '\u00A0' | '\u1680' | '\u2000' | '\u2001' | '\u2002' | '\u2003' | '\u2004' | '\u2005' | '\u2006' | '\u2007' | '\u2008' | '\u2009' | '\u200A' | '\u2028' | '\u2029' | '\u202F' | '\u205F' | '\u3000' | '\uFEFF';
+type TrimLeft<T extends string> = T extends `${Whitespace}${infer Rest}` ? TrimLeft<Rest> : T;
+type TrimRight<T extends string> = T extends `${infer Rest}${Whitespace}` ? TrimRight<Rest> : T;
+type Trim<T extends string> = string extends T ? string : TrimLeft<TrimRight<T>>;
+/**
+ * Creates an extension namespace with typed subject definitions.
+ *
+ * Pure wrapper around {@link createBusNamespace} that:
+ * - Automatically prepends 'extension:' to the domain name
+ * - Provides extension point for extension-specific metadata via declaration merging
+ * - Preserves type-safe filtering capabilities
+ * @param extensionName - Extension name (e.g., 'terminal' becomes 'extension:terminal')
+ * @param config - Namespace configuration with schemas and optional extensions
+ * @returns Extension namespace with typed subjects and extensions
+ * @example
+ * ```typescript
+ * // Basic usage (bus-only)
+ * const TerminalExtension = createExtensionNamespace('terminal', {
+ *   schemas: {
+ *     spawn: { request: z.object({ cwd: z.string() }), response: z.object({ terminalId: z.string() }) },
+ *     output: z.object({ terminalId: z.string(), data: z.string() }),
+ *   },
+ * });
+ *
+ * // With custom extension (after importing extension package)
+ * const MyExtension = createExtensionNamespace('my-extension', {
+ *   schemas: { ... },
+ *   extensions: {
+ *     customMetadata: { version: '1.0.0' },
+ *   },
+ * });
+ * ```
+ */
+declare function createExtensionNamespace<N extends string, Schemas extends SchemaRecord, Ext extends ExtensionNamespaceExtensions = ExtensionNamespaceExtensions>(extensionName: N, config: ExtensionNamespaceConfig<Schemas, Ext>): ExtensionNamespace<Trim<N>, SubjectRecordFromSchemaRecord<Schemas>, FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>, Ext, Schemas>;
+//#endregion
+//#region packages/bus-core/src/utils/warn-unregistered.d.ts
+/**
+ * Reset the warned-subjects set between test runs.
+ * @internal
+ * @returns Reset function in test mode, undefined otherwise
+ */
+declare const __resetWarnedSubjects: (() => void) | undefined;
+//#endregion
+export { type BroadcastContext, type BroadcastResult, type BusBroadcastMessage, type BusBroadcastResponseMessage, BusError, type BusEventMessage, type BusHeartbeatMessage, BusLifecycle, type BusMessage, type BusNamespace, type BusReceiveHandler, type BusRequestMessage, type BusResponseMessage, type BusSubscribeMessage, type BusSubscribeSyncCompleteMessage, type BusTransport, type BusTransportError, type BusTransportKeys, type BusTransportRegistry, type BusUnsubscribeMessage, type BusUrlConfig, type BusValidationMode, ChannelAuthError, ChannelClosedError, type ChannelEndpoint, type ChannelEndpointOptions, ChannelOnlyError, type ConnectOptions, type ConnectedPayload, CorrelationTracker, DEFAULT_REQUEST_TIMEOUT_MS, type DefinedSubjectExtension, type DisconnectedPayload, type EventSubjectExtension, type ExtendedSubjectDefinition, type ExtensionNamespace, type ExtensionNamespaceConfig, type ExtensionNamespaceExtensions, type ExtensionNamespaceFromConfig, type IDirectChannel, type IFilteredBus, type IMakaioBus, type InterceptorContext, LocalSubjectError, MakaioBus, type MakaioBusContext, NO_HANDLER_ERROR_CODE, type NamespaceRegistrationOptions, NoHandlerError, type OnOptions, OnceAbortError, type OptionalResult, RequestError, type RequestSubjectExtension, type SchemaViolationCallback, type SchemaViolationReport, type ScopedBus, type ScopedBusFor, type SubjectExtension, type SubscriptionEntry, SystemChannelSchemas, TimeoutError, type TransportRegistration, ValidationError, __resetWarnedSubjects, buildSubscribeMessage, buildUnsubscribeMessage, channelSubject, createBusContext, createBusInstance, createChannelEndpoint, createExtensionNamespace, createFilteredBus, defineSubjectExtension, deserializeTransportError, extendSubjectImpl as extendSubject, getFullSubjectForSubjectDefinition, getPath, getSubjectFromBusMessage, handleCorrelationResponse, isNoHandlerErrorForSubject, isRequestSchema, localSubject, matchesAnySubscription, matchesFilter, matchesSubscription, mergeFilters, openChannel, parseBusUrl, serializeTransportError, shouldReceiveMessage, trackMessageCorrelation };