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

package/dist/core/index.d.mts

@@ -0,0 +1,1263 @@
+import { ZodType, z } from "zod";
+import { Paths, Simplify, UnknownRecord } from "type-fest";
+
+//#region core/makaio-core/src/types/config-storage.d.ts
+/**
+ * Storage interface for config persistence.
+ *
+ * Generic interface allowing type-safe implementations with different
+ * config types. Simple file-based storage for bootstrap configuration.
+ * @typeParam TConfig - Type for configuration (defaults to unknown)
+ * @example Node.js file-based implementation
+ * ```typescript
+ * import type { Config } from '@makaio/framework/contracts';
+ *
+ * class FileConfigStorage implements IConfigStorage<Config> {
+ *   async getConfig(): Promise<Config> {
+ *     const content = await fs.readFile('~/.makaio/config.json', 'utf-8');
+ *     return ConfigSchema.parse(JSON.parse(content));
+ *   }
+ *
+ *   async saveConfig(config: Config): Promise<void> {
+ *     await fs.writeFile('~/.makaio/config.json', JSON.stringify(config, null, 2));
+ *   }
+ * }
+ * ```
+ * @example In-memory implementation for testing
+ * ```typescript
+ * class MemoryConfigStorage implements IConfigStorage<Config> {
+ *   private config: Config = { mode: 'local', adapters: [] };
+ *
+ *   async getConfig() { return this.config; }
+ *   async saveConfig(config: Config) { this.config = config; }
+ * }
+ * ```
+ */
+interface IConfigStorage<TConfig = unknown> {
+  /**
+   * Get the current config, or default if missing.
+   * @returns The config object
+   */
+  getConfig(): Promise<TConfig>;
+  /**
+   * Save the config.
+   * @param config - The config object to save
+   */
+  saveConfig(config: TConfig): Promise<void>;
+}
+//#endregion
+//#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 };
+/**
+ * Type guard to check if a value is a filter operator object.
+ * @param value - The filter operator value to check
+ * @returns True if the value is a filter operator object with $in, $ne, $exists, $startsWith, or $endsWith
+ */
+declare function isOperatorObject(value: FilterOperator): value is {
+  $in: Primitive[];
+} | {
+  $ne: Primitive;
+} | {
+  $exists: boolean;
+} | {
+  $startsWith: string;
+} | {
+  $endsWith: string;
+};
+//#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;
+};
+/** Extract payload (event payload or request/response pair) */
+type ExtractInternalSubjectPayload<T extends SubjectDefinition> = T['$meta']['payload'];
+/** Extract subject payload  */
+type ExtractSubjectPayload<T extends SubjectDefinition> = ExtractInternalSubjectPayload<T> extends RequestMessagePayload ? ExtractInternalSubjectPayload<T>['request'] : ExtractInternalSubjectPayload<T>;
+/** Extract response payload (request subjects only) */
+type ExtractSubjectResponse<T extends SubjectDefinition> = ExtractInternalSubjectPayload<T> extends RequestMessagePayload ? ExtractInternalSubjectPayload<T>['response'] : never;
+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>>>;
+/**
+ * Compute FilterPayload directly from a schema record.
+ *
+ * This bypasses SubjectRecordFromSchemaRecord and computes directly from schemas,
+ * which TypeScript can evaluate because Schemas is concrete at registration time.
+ */
+type FilterPayloadFromSchemas<Schemas extends Record<string, SubjectSchema>> = Simplify<AllPropertiesOfUnion<{ [K in keyof Schemas]: FilterablePayload<InferSchemaPayload<Schemas[K]>> }[keyof Schemas]>>;
+//#endregion
+//#region core/makaio-core/src/types/wildcards.d.ts
+type WildcardSubject = '*';
+declare const WildcardSubjectKey = "*";
+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/types/bus-like.d.ts
+type EventSubjectLike = SubjectDefinition & {
+  readonly $meta: {
+    readonly isRequest: false;
+    readonly channel: false;
+  };
+};
+type RequestSubjectLike = SubjectDefinition & {
+  readonly $meta: {
+    readonly isRequest: true;
+    readonly channel: false;
+    readonly payload: RequestMessagePayload;
+  };
+};
+/**
+ * Minimal structural bus seam for contracts-owned helpers.
+ *
+ * This deliberately does not re-model `@makaio/bus-core`'s generic overloads.
+ * Bus-core owns the full magic inference surface; this type only covers the
+ * event/request calls that contract helper APIs make without importing bus-core.
+ */
+interface MakaioBusLike {
+  /** Emit an event. */
+  emit<Subject extends EventSubjectLike>(subject: Subject, payload: Subject['$meta']['payload']): Promise<void>;
+  /** Send a request and await a response. */
+  request<Subject extends RequestSubjectLike>(subject: Subject, payload: Subject['$meta']['payload']['request']): Promise<Subject['$meta']['payload']['response']>;
+}
+//#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>;
+};
+/**
+ * Nests flat dotted subject keys into a hierarchical structure.
+ * @param namespace - The domain/namespace for the subject definitions
+ * @param flat - Flat record of subject schemas with dotted keys
+ * @param namespaceDefaultTransports - Optional namespace-level transport default
+ *   propagated to each subject's `$meta.defaultTransports` unless the subject
+ *   schema is wrapped with `defaultTransports()`.
+ * @returns Nested subject definitions with hierarchical structure and a $all wildcard
+ */
+declare function nestSubjectDefinitions<Domain extends string, T extends Record<string, SubjectSchema>>(namespace: Domain, flat: T, namespaceDefaultTransports?: TransportRoutingDefault): NestedSubjectDefinitions<FlatSubjectDefinitions<Domain, T>> & {
+  $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
+/**
+ * Check if a schema is wrapped as a local subject.
+ * @param schema - The schema to check
+ * @returns True if the schema is a LocalSubjectSchema wrapper
+ */
+declare function isLocalSchema(schema: SubjectSchema): schema is LocalSubjectSchema;
+/**
+ * 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
+/**
+ * Check if a schema is wrapped as a collector-only subject.
+ * @param schema - The schema to check.
+ * @returns True if the schema is a CollectorOnlySubjectSchema wrapper.
+ */
+declare function isCollectorOnlySchema(schema: SubjectSchema): schema is CollectorOnlySubjectSchema;
+/**
+ * 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
+/**
+ * Check if a schema is wrapped as a channel subject.
+ * @param schema - The schema to check
+ * @returns True if the schema is a ChannelSubjectSchema wrapper
+ */
+declare function isChannelSchema(schema: SubjectSchema): schema is ChannelSubjectSchema;
+/**
+ * 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
+/**
+ * Check if a schema carries a subject-level default transport routing policy.
+ * @param schema - The schema to check
+ * @returns True if the schema is a DefaultTransportsSubjectSchema wrapper
+ */
+declare function isDefaultTransportsSchema(schema: SubjectSchema): schema is DefaultTransportsSubjectSchema;
+/**
+ * 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/subject-helpers/unwrap-schema.d.ts
+/**
+ * Unwrap any subject schema wrapper to get the inner schema.
+ * Returns the schema as-is if not wrapped.
+ * @param schema - The schema to unwrap
+ * @returns The inner EventSchema or RequestSchema
+ */
+declare function unwrapSchema(schema: SubjectSchema): EventSchema | RequestSchema;
+//#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;
+};
+/**
+ * Options for {@link createBusNamespace}.
+ *
+ * Extends each variant of {@link NamespaceRegistrationOptions} with an optional
+ * `defaultTransports` field so callers can pass both validation mode and routing
+ * default in a single options object.
+ */
+type CreateBusNamespaceOptions = NamespaceRegistrationOptions & {
+  /**
+   * Default transport routing for every subject 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.
+   */
+  defaultTransports?: TransportRoutingDefault;
+};
+/**
+ * Creates a bus namespace definition with typed subject tokens.
+ *
+ * Pure function — no side-effects, no bus singleton mutation. The returned
+ * definition can be used immediately for bus operations (`bus.on()`,
+ * `bus.emit()`, etc.) and registered later at boot time via
+ * `MakaioBus.registerNamespace(definition)`.
+ * @param name - Namespace domain string (e.g., `'adapter'`, `'session'`)
+ * @param schemas - Schema record mapping subject keys to Zod schemas
+ * @param options - Optional registration and routing options
+ * @returns Namespace definition with typed subject tokens and carried schemas
+ * @example
+ * ```typescript
+ * import { createBusNamespace } from '@makaio/framework/core';
+ * import { AdapterSchemas } from './schemas.js';
+ *
+ * export const AdapterNamespace = createBusNamespace('adapter', AdapterSchemas);
+ * export const AdapterSubjects = AdapterNamespace.subjects;
+ * ```
+ */
+declare function createBusNamespace<Domain extends string, Schemas extends Record<string, SubjectSchema>>(name: Domain, schemas: Schemas, options?: CreateBusNamespaceOptions): BusNamespaceDefinition<Domain, Schemas>;
+//#endregion
+//#region core/makaio-core/src/context/index.d.ts
+/**
+ * Platform identifier for tool execution context.
+ * Used to determine platform-specific behavior in tools.
+ */
+type Platform = 'posix' | 'windows';
+/**
+ * Execution context passed to tool implementations.
+ *
+ * Provides tools with essential runtime information about the execution environment,
+ * including working directory, environment variables, platform, and cancellation support.
+ * @example
+ * ```typescript
+ * const result = await tool.execute(input, {
+ *   cwd: '/path/to/project',
+ *   env: { NODE_ENV: 'development' },
+ *   platform: 'posix',
+ *   signal: abortController.signal,
+ * });
+ * ```
+ */
+interface MakaioContext {
+  /** Working directory for tool execution */
+  cwd: string;
+  /** Read-only environment variables available to the tool */
+  env: Readonly<Record<string, string>>;
+  /** Platform identifier for cross-platform compatibility */
+  platform: Platform;
+  /** Optional abort signal for cancellation support */
+  signal?: AbortSignal;
+  /** Optional constraints that tools can check for specific behaviors */
+  constraints?: Record<string, unknown>;
+  /** Session ID for the current execution context */
+  sessionId?: string;
+  /** Subagent ID if running as a subagent */
+  subagentId?: string;
+  /** Current nesting depth in subagent hierarchy (0 = root) */
+  subagentDepth?: number;
+}
+/**
+ * Creates a MakaioContext with sensible defaults and optional overrides.
+ *
+ * Default behavior:
+ * - `cwd`: Uses process.cwd() or '/' in non-Node environments
+ * - `env`: Sanitized process.env (filters undefined values)
+ * - `platform`: Auto-detected from process.platform
+ * @param overrides - Optional partial context to merge with defaults
+ * @returns Complete MakaioContext ready for tool execution
+ * @example
+ * ```typescript
+ * // Create context with all defaults
+ * const ctx = createMakaioContext();
+ *
+ * // Override specific values
+ * const ctx = createMakaioContext({
+ *   cwd: '/custom/path',
+ *   signal: abortController.signal,
+ * });
+ * ```
+ */
+declare function createMakaioContext(overrides?: Partial<MakaioContext>): MakaioContext;
+//#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);
+}
+declare class InvalidModelError extends MakaioError {
+  readonly subject?: string | undefined;
+  constructor(requestedModel: string, subject?: string | undefined);
+}
+declare class DirectoryNotFoundError extends MakaioError {
+  readonly subject?: string | undefined;
+  constructor(path: string, subject?: string | undefined);
+}
+declare class ConfigError extends MakaioError {
+  readonly subject?: string | undefined;
+  constructor(message: string, subject?: string | undefined);
+}
+/** Thrown when a provider rate-limits the request. */
+declare class RateLimitError extends MakaioError {
+  readonly code: "rate_limit";
+}
+/** Thrown when authentication/authorization fails. */
+declare class AuthenticationError extends MakaioError {
+  readonly code: "auth";
+}
+/** Thrown when the requested model is unavailable (deprecated, not found, etc.). */
+declare class ModelUnavailableError extends MakaioError {
+  readonly code: "model_unavailable";
+}
+/** Thrown when a usage quota (tokens, requests) is exceeded. */
+declare class QuotaExceededError extends MakaioError {
+  readonly code: "quota_exceeded";
+}
+//#endregion
+//#region core/makaio-core/src/observability/schema-observability.d.ts
+/**
+ * Zod metadata key under which observability policies are stored.
+ *
+ * Using a namespaced string key avoids collisions with any other metadata
+ * that callers attach to a schema via `.meta()`.
+ */
+declare const OBSERVABILITY_META_KEY = "makaio.observability";
+/**
+ * Schema-level observability policy attached to a Zod object schema via
+ * {@link observability.schema}.
+ */
+interface ObservabilitySchemaPolicy {
+  /**
+   * When `true`, all scalar fields of the schema are projected to telemetry
+   * unless a field opts out with `visibility: 'hidden'`.
+   */
+  readonly traceAll?: boolean;
+}
+/** Controls how a single field participates in subject telemetry projection. */
+type ObservabilityFieldVisibility = 'attribute' | 'hidden' | 'count';
+/**
+ * Field-level observability policy attached to a Zod field schema via
+ * {@link observability.field}, {@link observability.hidden},
+ * {@link observability.count}, or {@link observability.attribute}.
+ */
+interface ObservabilityFieldPolicy {
+  /** How this field participates in subject telemetry projection. */
+  readonly visibility: ObservabilityFieldVisibility;
+  /**
+   * Telemetry attribute name for this field.
+   * Defaults to the object property key when absent.
+   */
+  readonly attributeName?: string;
+}
+/**
+ * Returns the {@link ObservabilitySchemaPolicy} stored on a schema, or
+ * `undefined` if the schema has no schema-level observability metadata.
+ * @param schema - The Zod schema to inspect.
+ * @returns The schema-level observability policy, or `undefined`.
+ */
+declare function getObservabilitySchemaPolicy(schema: z.ZodType): ObservabilitySchemaPolicy | undefined;
+/**
+ * Returns the {@link ObservabilityFieldPolicy} stored on a field schema, or
+ * `undefined` if no field-level observability metadata is found.
+ *
+ * The lookup walks transparent wrapper layers from outermost to innermost so
+ * wrapper-level metadata can override inner metadata, and metadata attached to
+ * any intermediate wrapper remains readable after additional wrapping.
+ * @param schema - The Zod field schema to inspect.
+ * @returns The field-level observability policy, or `undefined`.
+ */
+declare function getObservabilityFieldPolicy(schema: z.ZodType): ObservabilityFieldPolicy | undefined;
+/**
+ * Fluent helpers for attaching observability metadata to Zod schemas.
+ *
+ * All methods return a new schema instance — Zod schemas are immutable. The
+ * original schema is never mutated.
+ * @example
+ * ```typescript
+ * const RequestSchema = observability.schema(
+ *   z.object({ query: z.string(), limit: z.number() }),
+ *   { traceAll: true },
+ * );
+ *
+ * const HiddenField = observability.hidden(z.string()).optional();
+ * ```
+ */
+declare const observability: {
+  /**
+   * Attaches a schema-level {@link ObservabilitySchemaPolicy} to a Zod schema.
+   * Preserves any metadata already present on the schema.
+   * @param schema - The Zod schema to annotate.
+   * @param policy - The schema-level observability policy to store.
+   * @returns A new schema instance with the policy merged into its metadata.
+   */
+  schema<TSchema extends z.ZodType>(schema: TSchema, policy: ObservabilitySchemaPolicy): TSchema;
+  /**
+   * Attaches a field-level {@link ObservabilityFieldPolicy} to a Zod schema.
+   * Preserves any metadata already present on the schema.
+   * @param schema - The Zod field schema to annotate.
+   * @param policy - The field-level observability policy to store.
+   * @returns A new schema instance with the policy merged into its metadata.
+   */
+  field<TSchema extends z.ZodType>(schema: TSchema, policy: ObservabilityFieldPolicy): TSchema;
+  /**
+   * Marks a field as hidden from subject telemetry projection.
+   * @param schema - The Zod field schema to hide.
+   * @returns A new schema instance with `visibility: 'hidden'` stored in its metadata.
+   */
+  hidden<TSchema extends z.ZodType>(schema: TSchema): TSchema;
+  /**
+   * Marks a field to be projected as a count metric in subject telemetry.
+   * @param schema - The Zod field schema to count.
+   * @param attributeName - Optional telemetry attribute name override.
+   * @returns A new schema instance with `visibility: 'count'` stored in its metadata.
+   */
+  count<TSchema extends z.ZodType>(schema: TSchema, attributeName?: string): TSchema;
+  /**
+   * Marks a field to be projected as a named attribute in subject telemetry.
+   * @param schema - The Zod field schema to expose as an attribute.
+   * @param attributeName - Optional telemetry attribute name override.
+   * @returns A new schema instance with `visibility: 'attribute'` stored in its metadata.
+   */
+  attribute<TSchema extends z.ZodType>(schema: TSchema, attributeName?: string): TSchema;
+};
+//#endregion
+export { type AnyHandler, type AnyMessageContext, AuthenticationError, type BaseMessageContext, type BaseSubjectSchema, type BusNamespaceDefinition, type BusSubjects, type ChannelSubjectSchema, type CollectorOnlySubjectSchema, ConfigError, type ContextForSubjectDefinition, type CreateBusNamespaceOptions, type DefaultTransportsSubjectSchema, DirectoryNotFoundError, type EventContext, type EventHandler, type EventMessagePayload, type EventSchema, type ExtractSubjectPayload, type ExtractSubjectResponse, type FilterOperator, type FilterPayloadFromSchemas, type FilterablePayloadIntersection, type FlatSubjectDefinitions, type HandlerForSubjectDefinition, type IConfigStorage, type InferSchemaPayload, type InferSubjectMeta, InvalidModelError, type LocalSubjectSchema, type MakaioBusLike, type MakaioContext, MakaioError, type MessageOrigin, type MessagePayload, ModelUnavailableError, type NamespaceRegistrationOptions, type NestedSubjectDefinitions, OBSERVABILITY_META_KEY, type ObservabilityFieldPolicy, type ObservabilityFieldVisibility, type ObservabilitySchemaPolicy, type OptionalResult, type PayloadFilter, type PrincipalContext, QuotaExceededError, RateLimitError, type RegistrableBusNamespaceDefinition, type RequestContext, type RequestHandler, type RequestMessagePayload, type RequestSchema, type SchemaRecord, type SchemaViolationReport, type ScopedSubjectDefinition, type SubjectDefinition, type SubjectRecord, type SubjectRecordFromSchemaRecord, type SubjectSchema, type TransportPeerContext, type TransportReceiveContext, type TransportRoutingDefault, type TypedPayloadFilter, type WildcardContext, type WildcardSubject, type WildcardSubjectDefinition, WildcardSubjectKey, type WildcardUnifiedHandler, channelSubject, collectorOnlySubject, createBusNamespace, createMakaioContext, defaultTransports, getFullSubjectForSubjectDefinition, getObservabilityFieldPolicy, getObservabilitySchemaPolicy, isChannelSchema, isCollectorOnlySchema, isDefaultTransportsSchema, isLocalSchema, isOperatorObject, isRequestSchema, localSubject, nestSubjectDefinitions, observability, unwrapSchema };