@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/bus/index.d.mts

@@ -0,0 +1,3994 @@
+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 core/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;
+}
+/**
+ * Describes the call origin of a bus message.
+ *
+ * Set on every context before handlers run; never serialized to wire.
+ * Derivation: `local` is `true` when no transport received the message
+ * (the call originated in this process), `false` when it arrived over
+ * a transport from a remote peer.
+ */
+interface MessageOrigin {
+  /** Whether the message originated locally (not from a remote transport). */
+  readonly local: boolean;
+}
+/**
+ * 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;
+  /**
+   * Where this message originated.
+   *
+   * `local: true` — emitted in this process.
+   * `local: false` — arrived via a transport from a remote caller.
+   *
+   * Always present; never serialized to the wire. Location-sensitive handlers
+   * check this before executing local side-effects.
+   */
+  origin: MessageOrigin;
+  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 core/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
+ * - `signal`: Optional AbortSignal from the originating request
+ * - 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;
+  /** AbortSignal supplied by the originating request, if any. */
+  signal?: AbortSignal;
+  /** 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 core/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 core/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 an event subject as collector-only.
+ *
+ * Collector-only events may be received from a transport and delivered to local
+ * handlers, but the receiving bus must not relay them onward to other
+ * transports. Local emits are also kept local.
+ */
+type CollectorOnlySubjectSchema<T extends EventSchema = EventSchema> = {
+  readonly __collectorOnly: 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;
+};
+/**
+ * Wrapper to set a subject-level default transport routing policy.
+ *
+ * This is weaker than `localSubject()`: the subject remains routable remotely,
+ * but local callers that omit an explicit `transports` option use this default.
+ */
+type DefaultTransportsSubjectSchema<T extends EventSchema | RequestSchema = EventSchema | RequestSchema, Default extends TransportRoutingDefault = TransportRoutingDefault> = {
+  readonly __defaultTransports: Default;
+  readonly schema: T;
+};
+/**
+ * Base schema types (unwrapped).
+ */
+type BaseSubjectSchema = EventSchema | RequestSchema;
+/**
+ * Union of all subject schema types (including metadata wrappers).
+ */
+type SubjectSchema = BaseSubjectSchema | LocalSubjectSchema | CollectorOnlySubjectSchema | ChannelSubjectSchema | DefaultTransportsSubjectSchema;
+type SchemaRecord = Record<string, SubjectSchema>;
+//#endregion
+//#region core/makaio-core/src/types/type-helpers.d.ts
+/**
+ * Unwrap subject schema 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 __collectorOnly: true;
+  readonly schema: infer Inner;
+} ? Inner : S extends {
+  readonly __channel: true;
+  readonly schema: infer Inner;
+} ? Inner : S extends {
+  readonly __defaultTransports: TransportRoutingDefault;
+  readonly schema: infer Inner;
+} ? Inner : S;
+/**
+ * Infer payload type from schema, including subject metadata wrappers.
+ *
+ * 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.
+ *
+ * Subject schema 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,
+ * default transport routing, 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;
+} & (S extends DefaultTransportsSubjectSchema<EventSchema | RequestSchema, infer Default> ? {
+  defaultTransports: Default;
+} : {
+  defaultTransports?: TransportRoutingDefault;
+});
+//#endregion
+//#region core/makaio-core/src/types/subjects.d.ts
+type SubjectRecord<SubjectKeys extends string = string, Payload extends MessagePayload = MessagePayload> = Record<SubjectKeys, Payload>;
+/**
+ * Default transport routing semantics for a subject or namespace.
+ *
+ * - `'all'` — send to all registered transports (the default when omitted).
+ * - `'local-only'` — suppress outbound transport fan-out unless the caller
+ *   explicitly provides a `transports` override. Weaker than `localSubject()`:
+ *   the subject can still be invoked remotely.
+ */
+type TransportRoutingDefault = 'all' | 'local-only';
+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;
+  /**
+   * Default transport routing for bus calls on this subject when the caller
+   * does not provide an explicit `transports` option.
+   *
+   * - `'all'` (default) — send to all registered transports as usual.
+   * - `'local-only'` — suppress transport fan-out unless the caller explicitly
+   *   provides a `transports` override. Weaker than `localSubject()`: the
+   *   subject can still be invoked remotely; only the outbound default is
+   *   suppressed.
+   */
+  defaultTransports?: TransportRoutingDefault;
+};
+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 core/makaio-core/src/types/wildcards.d.ts
+type WildcardSubject = '*';
+type WildcardSubjectDefinition<Namespace extends string = string> = SubjectDefinition<Record<'*', MessagePayload>, WildcardSubject, Namespace>;
+//#endregion
+//#region core/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 core/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 core/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 core/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 core/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 core/makaio-core/src/subject-helpers/is-collector-only-schema.d.ts
+/**
+ * Create a collector-only event schema wrapper.
+ *
+ * Collector-only events are transport-ingestable but not transport-relayable:
+ * a collector bus can receive them from an upstream peer and handle them
+ * locally without pushing them laterally to unrelated peers.
+ * @param schema - The event schema to mark as collector-only.
+ * @returns A CollectorOnlySubjectSchema wrapper.
+ */
+declare function collectorOnlySubject<T extends EventSchema>(schema: T): CollectorOnlySubjectSchema<T>;
+//#endregion
+//#region core/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 core/makaio-core/src/subject-helpers/default-transports-schema.d.ts
+/**
+ * Create a subject schema wrapper with a subject-level default transport policy.
+ *
+ * Use this when one subject should override its namespace's default transport
+ * routing while still remaining remotely invokable when a caller explicitly
+ * targets a transport.
+ * @param schema - The event or request schema to wrap
+ * @param value - Default transport routing policy for this subject
+ * @returns A DefaultTransportsSubjectSchema wrapper
+ * @example
+ * ```typescript
+ * import { defaultTransports } from '@makaio/framework/core';
+ *
+ * const Schemas = {
+ *   internalEvent: defaultTransports(z.object({ id: z.string() }), 'local-only'),
+ * };
+ * ```
+ */
+declare function defaultTransports<T extends EventSchema | RequestSchema, Default extends TransportRoutingDefault>(schema: T, value: Default): DefaultTransportsSubjectSchema<T, Default>;
+//#endregion
+//#region core/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;
+  /**
+   * Default transport routing for all subjects in this namespace when the
+   * caller does not provide an explicit `transports` option.
+   *
+   * Subject-level `defaultTransports` (set via `SubjectDefinitionMeta`) takes
+   * precedence over this namespace-level default when both are set.
+   *
+   * - `'all'` (default when omitted) — send to all registered transports.
+   * - `'local-only'` — suppress outbound transport fan-out by default. Callers
+   *   can still force transport delivery by passing an explicit `transports`
+   *   option. Weaker than `localSubject()`: subjects remain reachable remotely.
+   */
+  readonly defaultTransports?: TransportRoutingDefault;
+  /**
+   * 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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 `collectorOnlySubject()`. */
+  collectorOnly: 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[];
+  /**
+   * Get the full registration record for a subject.
+   * @param subject - Fully-qualified subject identifier (e.g., "adapter.getCapabilities")
+   * @returns Registration record if found, undefined otherwise
+   */
+  getRegisteredSubject(subject: string): RegisteredSubjectSchema | undefined;
+  /**
+   * 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;
+  /**
+   * Check if a subject is collector-only.
+   *
+   * Collector-only events may enter from a transport and run local handlers,
+   * but must not be relayed onward to other transports.
+   * @param subject - Full subject identifier (e.g., "subject-telemetry.fact")
+   * @returns True if the subject was wrapped with `collectorOnlySubject()`
+   */
+  isCollectorOnlySubject(subject: string): boolean;
+  /**
+   * Get the default transport visibility for a subject.
+   *
+   * Returns the namespace-level `defaultTransports` value recorded at
+   * registration time. Subject-level overrides in `SubjectDefinitionMeta`
+   * take precedence and are resolved by `emit()` directly from the subject
+   * definition token.
+   *
+   * Returns `'all'` when no namespace-level default was registered.
+   * @param subject - Fully-qualified subject identifier (e.g., `"session.list"`)
+   * @returns Effective namespace-level default transport visibility
+   */
+  getDefaultTransports(subject: string): "all" | "local-only";
+  /**
+   * 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 core/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 core/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';
+  /**
+   * Optional acknowledgement identifier.
+   * Transports that support dynamic subscription acknowledgements send a
+   * `subscription-ack` after applying the subscription update to their local
+   * routing state.
+   */
+  ackId?: string;
+  /**
+   * 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';
+  /**
+   * Optional acknowledgement identifier.
+   * Transports that support dynamic subscription acknowledgements send a
+   * `subscription-ack` after applying the unsubscription update to their local
+   * routing state.
+   */
+  ackId?: string;
+  /**
+   * 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';
+}
+/**
+ * Acknowledges a dynamic subscribe/unsubscribe control message.
+ *
+ * Complements the initial `subscribe-sync-complete` handshake: the handshake
+ * covers connection startup, while this message confirms one later
+ * subscription change has reached the remote routing state.
+ */
+interface BusSubscriptionAckMessage {
+  type: 'subscription-ack';
+  ackId: string;
+}
+/**
+ * Message types for transport wire protocol.
+ */
+type BusMessage = BusRequestMessage | BusResponseMessage | BusEventMessage | BusBroadcastMessage | BusBroadcastResponseMessage | BusHeartbeatMessage | BusSubscribeMessage | BusUnsubscribeMessage | BusSubscribeSyncCompleteMessage | BusSubscriptionAckMessage;
+/**
+ * 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 core/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 core/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 core/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 core/bus-core/src/types/bus.d.ts
+/**
+ * Production-capable observation record for local bus API entrypoints.
+ *
+ * Unlike `AnyMessageContext`, this is not debug-only and is safe for runtime
+ * services that need to derive sanitized telemetry.
+ */
+interface ObservedBusMessage {
+  readonly type: 'event' | 'request' | 'broadcast';
+  readonly subject: string;
+  readonly namespace: string;
+  readonly payload: unknown;
+  readonly messageId: string;
+  readonly correlationId?: string;
+  readonly transport?: TransportReceiveContext;
+  /** True when the originating bus call was explicitly or inherently local-only. */
+  readonly localOnly?: boolean;
+}
+/**
+ * Observer callback invoked for each local bus API message after validation
+ * has succeeded. Observers must not mutate the payload.
+ */
+type BusMessageObserver = (message: ObservedBusMessage) => void | Promise<void>;
+/**
+ * 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>;
+  /** Production-capable message observers registered via {@link IMakaioBus.observeMessages}. */
+  messageObservers: Set<BusMessageObserver>;
+  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 production-capable local message observer.
+   *
+   * Observers receive local `emit`, `request`, and `broadcast` API calls after
+   * message validation has succeeded. Observers must not mutate the payload.
+   * Unlike `__onAny`, this is not debug-only and is safe for runtime telemetry services.
+   * @param observer - Observer callback.
+   * @returns Cleanup function that unregisters the observer.
+   * @example
+   * ```typescript
+   * const dispose = bus.observeMessages((message) => {
+   *   console.debug(`[${message.type}] ${message.namespace}.${message.subject}`);
+   * });
+   * ```
+   */
+  observeMessages(observer: BusMessageObserver): () => void;
+  /**
+   * 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 core/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 core/bus-core/src/utils/transport-helpers.d.ts
+/**
+ * Singleton frozen origin for messages emitted within the current process.
+ *
+ * Shared across `emit`, `broadcast`, and `dispatch` to avoid a per-message
+ * allocation on the hot path. Both variants are frozen to prevent accidental
+ * mutation since they are module-level constants.
+ */
+declare const LOCAL_ORIGIN: MessageOrigin;
+/**
+ * Singleton frozen origin for messages that arrived via a transport.
+ *
+ * Used by `emit`, `broadcast`, and `dispatch` when a `TransportReceiveContext`
+ * is present (i.e. the message was forwarded from a remote caller).
+ */
+declare const REMOTE_ORIGIN: MessageOrigin;
+/**
+ * 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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/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 core/bus-core/src/methods/on.d.ts
+/**
+ * Wait until a handler registration has propagated to registered transports.
+ *
+ * `on()` still returns a plain cleanup function for public ergonomics, but
+ * remote transports subscribe asynchronously. Callers that publish readiness
+ * based on remote routability can await this helper before proceeding.
+ * @param cleanup - Cleanup function returned by {@link on}.
+ */
+declare function waitForSubscriptionPropagation(cleanup: (() => void) | null | undefined): Promise<void>;
+//#endregion
+//#region core/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 core/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 core/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 core/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 core/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 core/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 core/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
+ * @param ackId - Optional acknowledgement ID for dynamic subscription propagation
+ * @returns Wire-format subscribe message
+ */
+declare function buildSubscribeMessage(subscriptions: Map<string, SubscriptionEntry>, ackId?: string): BusSubscribeMessage;
+/**
+ * Build a BusUnsubscribeMessage for specific subjects and priorities.
+ * @param subjects - Map of subject patterns to priorities being removed
+ * @param ackId - Optional acknowledgement ID for dynamic unsubscription propagation
+ * @returns Wire-format unsubscribe message
+ */
+declare function buildUnsubscribeMessage(subjects: Record<string, number[]>, ackId?: string): BusUnsubscribeMessage;
+//#endregion
+//#region core/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 core/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
+//#region core/contracts/src/canonical-model/selection.d.ts
+/**
+ * Agent selection for `kind: 'canonical-model'`.
+ *
+ * The `model` field carries the canonical model reference string verbatim.
+ * Resolution happens immediately at the `AgentResolutionSubjects.resolve`
+ * chokepoint, so this kind never persists into runtime spawn paths.
+ */
+declare const CanonicalModelSelectionSchema: z.ZodObject<{
+  providerConfigId: z.ZodOptional<z.ZodString>;
+  reasoningEffort: z.ZodOptional<z.ZodEnum<{
+    none: "none";
+    low: "low";
+    medium: "medium";
+    high: "high";
+    "extra-high": "extra-high";
+  }>>;
+  cwd: z.ZodOptional<z.ZodString>;
+  systemPrompt: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    mode: z.ZodLiteral<"append">;
+    content: z.ZodString;
+  }, z.core.$strip>]>>;
+  allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  mcpSessionContext: z.ZodOptional<z.ZodObject<{
+    sessionId: z.ZodString;
+    servers: z.ZodArray<z.ZodObject<{
+      name: z.ZodString;
+      transport: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"stdio">;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        alwaysLoad: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+          name: z.ZodString;
+          permission_policy: z.ZodEnum<{
+            always_allow: "always_allow";
+            always_ask: "always_ask";
+            always_deny: "always_deny";
+          }>;
+        }, z.core.$strip>>>;
+        alwaysLoad: z.ZodOptional<z.ZodBoolean>;
+        type: z.ZodLiteral<"sse">;
+      }, z.core.$strip>, z.ZodObject<{
+        url: z.ZodString;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+          name: z.ZodString;
+          permission_policy: z.ZodEnum<{
+            always_allow: "always_allow";
+            always_ask: "always_ask";
+            always_deny: "always_deny";
+          }>;
+        }, z.core.$strip>>>;
+        alwaysLoad: z.ZodOptional<z.ZodBoolean>;
+        type: z.ZodLiteral<"http">;
+      }, z.core.$strip>], "type">;
+      exposureMode: z.ZodEnum<{
+        direct: "direct";
+        discovery: "discovery";
+      }>;
+    }, z.core.$strip>>;
+    directTools: z.ZodArray<z.ZodObject<{
+      fullName: z.ZodString;
+      originalName: z.ZodString;
+      serverName: z.ZodString;
+      description: z.ZodOptional<z.ZodString>;
+      inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      exposureMode: z.ZodEnum<{
+        direct: "direct";
+        discovery: "discovery";
+        hidden: "hidden";
+      }>;
+      enabled: z.ZodBoolean;
+      enabledBy: z.ZodOptional<z.ZodEnum<{
+        discovery: "discovery";
+        toolset: "toolset";
+      }>>;
+      enabledAt: z.ZodOptional<z.ZodNumber>;
+      exposed: z.ZodBoolean;
+    }, z.core.$strip>>;
+    discoverableTools: z.ZodArray<z.ZodObject<{
+      fullName: z.ZodString;
+      originalName: z.ZodString;
+      serverName: z.ZodString;
+      description: z.ZodOptional<z.ZodString>;
+      inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+      exposureMode: z.ZodEnum<{
+        direct: "direct";
+        discovery: "discovery";
+        hidden: "hidden";
+      }>;
+      enabled: z.ZodBoolean;
+      enabledBy: z.ZodOptional<z.ZodEnum<{
+        discovery: "discovery";
+        toolset: "toolset";
+      }>>;
+      enabledAt: z.ZodOptional<z.ZodNumber>;
+      exposed: z.ZodBoolean;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  allowedDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  kind: z.ZodLiteral<"canonical-model">;
+  model: z.ZodString;
+}, z.core.$loose>;
+type CanonicalModelSelection = z.infer<typeof CanonicalModelSelectionSchema>;
+declare module '@makaio/framework/contracts' {
+  interface AgentSelectionKindMap {
+    'canonical-model': CanonicalModelSelection;
+  }
+}
+//#endregion
+//#region core/contracts/src/skill/schemas.d.ts
+/** Trigger that activated or reinjected a skill. */
+declare const SkillActivationTriggerSchema: z.ZodEnum<{
+  user: "user";
+  auto: "auto";
+  model: "model";
+  reinjection: "reinjection";
+}>;
+/** Why a previously-active skill was removed from runtime state. */
+declare const SkillDeactivationReasonSchema: z.ZodEnum<{
+  user: "user";
+  cwd_changed: "cwd_changed";
+  session_end: "session_end";
+  replaced: "replaced";
+}>;
+type SkillActivationTrigger = z.infer<typeof SkillActivationTriggerSchema>;
+type SkillDeactivationReason = z.infer<typeof SkillDeactivationReasonSchema>;
+//#endregion
+//#region core/contracts/src/skill/types.d.ts
+declare module '@makaio/framework/contracts' {
+  interface SessionEventTypeMap {
+    /** Skill catalog built for a session agent. */
+    'skill.catalog.built': {
+      agentId: string;
+      cwd: string;
+      adapterId?: string;
+      skillNames: string[];
+    };
+    /** Skill activated for a session agent. */
+    'skill.activated': {
+      agentId: string;
+      skillName: string;
+      trigger: SkillActivationTrigger;
+      turnNumber?: number;
+    };
+    /** Skill deactivated for a session agent. */
+    'skill.deactivated': {
+      agentId: string;
+      skillName: string;
+      reason: SkillDeactivationReason;
+    };
+  }
+}
+//#endregion
+//#region core/contracts/src/telemetry/schemas.d.ts
+/**
+ * Scalar attribute value allowed in a telemetry fact.
+ *
+ * Restricted to primitives and homogeneous primitive arrays so that the
+ * telemetry sink can safely serialize without inspecting arbitrary objects.
+ */
+declare const SubjectTelemetryAttributeValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodArray<z.ZodNull>]>;
+/** Inferred TypeScript type for a sanitized attribute value. */
+type SubjectTelemetryAttributeValue = z.infer<typeof SubjectTelemetryAttributeValueSchema>;
+/**
+ * Sanitized bus subject telemetry fact schema.
+ *
+ * A fact captures the observable, non-sensitive metadata of a single bus
+ * message. All payload content is excluded; only correlation handles and
+ * namespace-approved scalar attributes are present.
+ */
+declare const SubjectTelemetryFactSchema: z.ZodObject<{
+  factId: z.ZodString;
+  observedAt: z.ZodNumber;
+  machineId: z.ZodOptional<z.ZodString>;
+  namespace: z.ZodString;
+  subject: z.ZodString;
+  messageType: z.ZodEnum<{
+    request: "request";
+    event: "event";
+    broadcast: "broadcast";
+  }>;
+  direction: z.ZodEnum<{
+    local: "local";
+    outbound: "outbound";
+    inbound: "inbound";
+  }>;
+  messageId: z.ZodString;
+  correlationId: z.ZodOptional<z.ZodString>;
+  attributes: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodBoolean>, z.ZodArray<z.ZodNull>]>>;
+}, z.core.$strict>;
+/** Inferred TypeScript type for a sanitized bus subject telemetry fact. */
+type SubjectTelemetryFact = z.infer<typeof SubjectTelemetryFactSchema>;
+//#endregion
+//#region core/bus-core/src/observability/projector-registry.d.ts
+/**
+ * Map of sanitized scalar attribute values approved for telemetry emission.
+ *
+ * Keys are attribute names; values are restricted to primitives and homogeneous
+ * primitive arrays so that telemetry sinks can safely serialize without
+ * inspecting arbitrary objects. `undefined` values are excluded during merge.
+ */
+type SubjectTelemetryAttributes = Record<string, SubjectTelemetryAttributeValue | undefined>;
+/**
+ * Input provided to a {@link SubjectTelemetryProjector} when projecting
+ * attributes from a bus message payload.
+ */
+interface SubjectTelemetryProjectorInput {
+  /** Raw bus message payload (read-only; must not be mutated). */
+  readonly payload: unknown;
+  /** Bus namespace that owns the observed subject. */
+  readonly namespace: string;
+  /** Subject key within the namespace. */
+  readonly subject: string;
+  /** Bus message type for the observed message. */
+  readonly messageType: 'event' | 'request' | 'broadcast';
+}
+/**
+ * Namespace-owned sidecar projector that extracts sanitized telemetry attributes
+ * from a bus message payload.
+ *
+ * The projector is responsible for ensuring that the returned attributes contain
+ * no sensitive data. Only scalar values ({@link SubjectTelemetryAttributeValue})
+ * should appear in the returned map.
+ */
+interface SubjectTelemetryProjector {
+  /** Namespace that owns this projector. */
+  readonly namespace: string;
+  /** Subject within the namespace that this projector handles. */
+  readonly subject: string;
+  /**
+   * Extract sanitized telemetry attributes from the message payload.
+   * @param input - Message context including payload, namespace, subject, and message type.
+   * @returns Map of attribute key to sanitized scalar value. `undefined` values are omitted.
+   */
+  project(input: SubjectTelemetryProjectorInput): SubjectTelemetryAttributes;
+}
+/**
+ * Registry of namespace-owned sidecar projectors, keyed by `namespace.subject`.
+ *
+ * Projectors may be registered by the namespace owner to provide sanitized
+ * telemetry attributes that cannot be inferred purely from schema observability
+ * metadata (e.g., when the payload contains nested structures that require
+ * domain-specific extraction logic).
+ */
+interface SubjectTelemetryProjectorRegistry {
+  /**
+   * Register a projector for a specific namespace and subject.
+   *
+   * If a projector is already registered for the same key, it is replaced.
+   * @param projector - Projector to register.
+   * @returns Cleanup function that unregisters this projector instance.
+   */
+  register(projector: SubjectTelemetryProjector): () => void;
+  /**
+   * Retrieve the registered projector for a namespace and subject, if any.
+   * @param namespace - Namespace that owns the subject.
+   * @param subject - Subject key within the namespace.
+   * @returns The registered projector, or `undefined` if none is registered.
+   */
+  get(namespace: string, subject: string): SubjectTelemetryProjector | undefined;
+}
+/**
+ * Create a new {@link SubjectTelemetryProjectorRegistry}.
+ *
+ * Maintains a map of projectors keyed by `namespace.subject`. At most one
+ * projector is stored per key; later registrations replace earlier ones.
+ * @returns A new projector registry instance.
+ */
+declare function createSubjectTelemetryProjectorRegistry(): SubjectTelemetryProjectorRegistry;
+//#endregion
+//#region core/bus-core/src/observability/subject-telemetry-projector.d.ts
+/**
+ * Union of the three projectable local bus message types.
+ *
+ * Only messages that enter the bus via the local API (`emit`, `request`,
+ * `broadcast`) are candidates for telemetry projection. Transport-relayed
+ * messages are excluded because their projection is the responsibility of
+ * the originating runtime.
+ */
+type ProjectableBusMessage = BusEventMessage | BusRequestMessage | BusBroadcastMessage;
+/**
+ * Input for {@link projectSubjectTelemetryFacts}.
+ *
+ * Carries all data needed to project a sanitized {@link SubjectTelemetryFact}
+ * from a single observed bus message.
+ */
+interface SubjectTelemetryProjectionInput {
+  /** The observed bus message to project. */
+  readonly message: ProjectableBusMessage;
+  /**
+   * Flow direction of the observed message at the source runtime.
+   * Typically `'local'` for messages that originate and are consumed within
+   * the same process.
+   */
+  readonly direction: 'local' | 'outbound' | 'inbound';
+  /** Wall-clock timestamp in Unix milliseconds at the time of observation. */
+  readonly observedAt: number;
+  /** Optional source machine identifier for multi-node telemetry correlation. */
+  readonly machineId?: string;
+  /**
+   * Namespace registry used to look up the schema for the observed subject.
+   * Obtain via `bus.getContext().namespaceRegistry`.
+   */
+  readonly namespaceRegistry: NamespaceRegistry;
+  /**
+   * Optional sidecar projector registry for namespace-owned attribute extraction.
+   *
+   * When a projector is registered for the message's namespace and subject it
+   * takes precedence over schema-driven projection.
+   */
+  readonly projectorRegistry?: SubjectTelemetryProjectorRegistry;
+}
+/**
+ * Project a single bus message into an array of sanitized
+ * {@link SubjectTelemetryFact} objects.
+ *
+ * Attributes are resolved in the following priority order:
+ * 1. **Sidecar projector**: a namespace-owned projector registered in
+ *    `projectorRegistry` for the message's namespace and subject.
+ * 2. **Schema-driven**: scalar fields projected via `traceAll` or explicit
+ *    `observability.attribute()` / `observability.hidden()` metadata on the
+ *    Zod schema stored in the namespace registry.
+ * 3. **Trace-only**: when neither approach yields attributes, an empty
+ *    `attributes` map is produced (the fact still carries correlation handles).
+ *
+ * The function always returns exactly one fact per call. The array shape
+ * is intentional — downstream aggregation layers may extend this to fan-out
+ * multiple facts from a single message (e.g., per-field count metrics).
+ * @param input - Projection input including the message, direction, timestamp,
+ *   namespace registry, and optional sidecar projector registry.
+ * @returns Array containing exactly one {@link SubjectTelemetryFact}.
+ */
+declare function projectSubjectTelemetryFacts(input: SubjectTelemetryProjectionInput): SubjectTelemetryFact[];
+//#endregion
+//#region core/bus-core/src/observability/projected-telemetry-transport.d.ts
+/**
+ * Configuration options for {@link createProjectedTelemetryTransport}.
+ */
+interface ProjectedTelemetryTransportOptions {
+  /**
+   * Unique name for this transport instance.
+   *
+   * Must be unique within a single bus instance (used as the registry key).
+   */
+  readonly name: string;
+  /**
+   * The underlying transport that receives projected telemetry fact events.
+   *
+   * All projected facts are forwarded to this transport as
+   * `subject-telemetry.fact` events. No raw application payloads are forwarded.
+   */
+  readonly inner: BusTransport;
+  /**
+   * Namespace registry used to resolve schemas for attribute projection.
+   *
+   * Obtain via `bus.getContext().namespaceRegistry`.
+   */
+  readonly namespaceRegistry: NamespaceRegistry;
+  /**
+   * Optional sidecar projector registry for namespace-owned attribute extraction.
+   *
+   * When provided, sidecar projectors registered for a message's namespace and
+   * subject take precedence over schema-driven attribute projection.
+   */
+  readonly projectorRegistry?: SubjectTelemetryProjectorRegistry;
+  /**
+   * Optional source machine identifier embedded in each projected fact.
+   *
+   * When omitted, the `machineId` field is absent from emitted facts.
+   */
+  readonly machineId?: string;
+  /**
+   * Optional clock override for deterministic testing.
+   *
+   * When provided, called instead of `Date.now()` to obtain the `observedAt`
+   * timestamp for each projected fact. Defaults to `Date.now`.
+   * @returns Current Unix timestamp in milliseconds.
+   */
+  readonly now?: () => number;
+}
+/**
+ * Create a one-way outbound transport that projects bus messages into sanitized
+ * {@link SubjectTelemetryFact} events and forwards only those facts upstream.
+ *
+ * ## Behavior
+ *
+ * **Outbound (send):**
+ * - Projectable messages (`event`, `request`, `broadcast`) are projected into
+ *   `subject-telemetry.fact` events via {@link projectSubjectTelemetryFacts}
+ *   and forwarded to `inner.send()`. The raw application payload is never
+ *   forwarded.
+ * - Non-projectable messages (`response`, `subscribe`, `heartbeat`, etc.) are
+ *   silently dropped. This transport is strictly outbound; control and response
+ *   messages must not be relayed to the upstream collector.
+ *
+ * **Inbound (onReceive):**
+ * - The transport registers a receive handler on `inner` but silently drops all
+ *   inbound messages. Control messages (`heartbeat`, `subscribe-ack`,
+ *   `subscribe-sync-complete`) are consumed silently. Application messages
+ *   arriving from upstream are dropped to prevent raw remote data from
+ *   propagating into the local bus.
+ *
+ * Connection and readiness operations delegate to `inner`. Subscription
+ * advertisement is deliberately not forwarded: this transport is telemetry-only
+ * and must not make the upstream collector believe it can route application
+ * subjects back to this runtime.
+ * @param options - Configuration including the inner transport, namespace
+ *   registry, optional machine ID, and optional clock override.
+ * @returns A {@link BusTransport} that emits only projected telemetry facts.
+ */
+declare function createProjectedTelemetryTransport(options: ProjectedTelemetryTransportOptions): BusTransport;
+//#endregion
+export { type BroadcastContext, type BroadcastResult, type BusBroadcastMessage, type BusBroadcastResponseMessage, BusError, type BusEventMessage, type BusHeartbeatMessage, BusLifecycle, type BusMessage, type BusMessageObserver, type BusNamespace, type BusReceiveHandler, type BusRequestMessage, type BusResponseMessage, type BusSubscribeMessage, type BusSubscribeSyncCompleteMessage, type BusSubscriptionAckMessage, 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, LOCAL_ORIGIN, LocalSubjectError, MakaioBus, type MakaioBusContext, NO_HANDLER_ERROR_CODE, type NamespaceRegistrationOptions, NoHandlerError, type ObservedBusMessage, type OnOptions, OnceAbortError, type OptionalResult, type ProjectableBusMessage, type ProjectedTelemetryTransportOptions, REMOTE_ORIGIN, RequestError, type RequestSubjectExtension, type SchemaViolationCallback, type SchemaViolationReport, type ScopedBus, type ScopedBusFor, type SubjectExtension, type SubjectTelemetryAttributes, type SubjectTelemetryProjectionInput, type SubjectTelemetryProjector, type SubjectTelemetryProjectorInput, type SubjectTelemetryProjectorRegistry, type SubscriptionEntry, SystemChannelSchemas, TimeoutError, type TransportRegistration, ValidationError, __resetWarnedSubjects, buildSubscribeMessage, buildUnsubscribeMessage, channelSubject, collectorOnlySubject, createBusContext, createBusInstance, createChannelEndpoint, createExtensionNamespace, createFilteredBus, createProjectedTelemetryTransport, createSubjectTelemetryProjectorRegistry, defaultTransports, defineSubjectExtension, deserializeTransportError, extendSubjectImpl as extendSubject, getFullSubjectForSubjectDefinition, getPath, getSubjectFromBusMessage, handleCorrelationResponse, isNoHandlerErrorForSubject, isRequestSchema, localSubject, matchesAnySubscription, matchesFilter, matchesSubscription, mergeFilters, openChannel, parseBusUrl, projectSubjectTelemetryFacts, serializeTransportError, shouldReceiveMessage, trackMessageCorrelation, waitForSubscriptionPropagation };