@makaio/framework 1.0.0-dev-1779046984397

package/dist/core/index.d.mts

@@ -0,0 +1,1001 @@
+import { ZodType, z } from "zod";
+import { Paths, Simplify, UnknownRecord } from "type-fest";
+
+//#region packages/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 packages/makaio-core/src/types/message.d.ts
+/**
+ * Host-agnostic principal attached by a trusted local transport.
+ *
+ * The framework treats this as opaque metadata. Host code decides what
+ * principal kinds and claims mean.
+ */
+interface PrincipalContext {
+  /** Principal kind, such as `user`, `device`, `machine`, or host-defined values. */
+  readonly kind: string;
+  /** Optional stable principal identifier in the principal namespace. */
+  readonly id?: string;
+  /** Optional opaque claims supplied by the authenticating transport or host policy. */
+  readonly claims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Authenticated peer metadata supplied by a transport connection.
+ */
+interface TransportPeerContext {
+  /** Peer kind, such as `browser`, `machine`, `worker`, or host-defined values. */
+  readonly kind: string;
+  /** Optional transport-level peer identifier. */
+  readonly id?: string;
+  /** Whether the receiving transport authenticated the peer. */
+  readonly authenticated?: boolean;
+  /** Whether the receiving transport established encrypted payload transport. */
+  readonly encrypted?: boolean;
+  /** Optional opaque peer claims. */
+  readonly claims?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Trusted context derived locally by the receiving transport.
+ *
+ * This context is never serialized into `BusMessage`; each receiving node must
+ * derive its own context from its own transport/session state.
+ */
+interface TransportReceiveContext {
+  /** Registered bus transport name that received the message. */
+  readonly transportName: string;
+  /** Optional connection/session identifier local to the transport. */
+  readonly connectionId?: string;
+  /** Optional authenticated transport peer. */
+  readonly peer?: TransportPeerContext;
+  /** Optional host-agnostic principal resolved for this connection. */
+  readonly principal?: PrincipalContext;
+}
+/**
+ * Base message context interface for both events and requests.
+ *
+ * Provides common metadata for tracking and correlation:
+ * - `messageId`: Unique identifier for this specific message
+ * - `correlationId`: Optional identifier linking related operations
+ */
+interface BaseMessageContext {
+  /**
+   * Unique identifier for this specific message.
+   * Auto-generated if not provided.
+   *
+   * Used for:
+   * - Message deduplication
+   * - Idempotency checks
+   * - Tracking individual messages in logs
+   */
+  messageId: string;
+  /**
+   * Optional identifier linking related operations.
+   * Propagated through chains of requests/events.
+   *
+   * Used for:
+   * - Distributed tracing
+   * - Causality tracking
+   * - Following a workflow through the system
+   * @example
+   * ```typescript
+   * // Initial request generates correlationId
+   * const result = await request(
+   *   UserSubjects.getUser,
+   *   { userId: '42' },
+   *   { correlationId: 'user-action-123' }
+   * );
+   *
+   * // Handler propagates correlationId to downstream operations
+   * await emit(
+   *   UserSubjects.userLoaded,
+   *   { user: result },
+   *   { correlationId: context.correlationId }
+   * );
+   * ```
+   */
+  correlationId?: string;
+  /**
+   * Trusted context supplied by the local receiving transport.
+   *
+   * Undefined for local calls and for transports that do not supply connection
+   * context. Never trust similarly named fields in payloads or wire messages.
+   */
+  transport?: TransportReceiveContext;
+  isRequest: boolean;
+}
+type EventMessagePayload<Payload extends UnknownRecord = UnknownRecord> = Payload & {
+  request?: never;
+  response?: never;
+};
+type RequestMessagePayload<Request extends UnknownRecord = UnknownRecord, Response extends UnknownRecord = UnknownRecord> = {
+  request: Request;
+  response: Response;
+};
+type MessagePayload = RequestMessagePayload | EventMessagePayload;
+//#endregion
+//#region packages/makaio-core/src/types/context.d.ts
+/**
+ * Context object passed to event handlers when using wildcard patterns.
+ *
+ * Provides:
+ * - `isRequest`: Always false (discriminator for type narrowing)
+ * - `payload`: The event payload
+ * - Message tracking fields from BaseMessage (messageId, correlationId)
+ */
+interface EventContext<Payload> extends BaseMessageContext {
+  /** Discriminator - always false for events */
+  isRequest: false;
+  /** The event payload */
+  payload: Payload;
+  /** The event subject */
+  subject: string;
+}
+/**
+ * Context object passed to request handlers.
+ *
+ * Provides:
+ * - `isRequest`: Always true (discriminator for type narrowing)
+ * - `payload`: The request payload
+ * - `setResult`: Function to set the response value
+ * - `next`: Function to call the next handler in the middleware chain
+ * - `replacePayload`: Function to transform the payload for subsequent handlers
+ * - `identify`: Optional function to identify the handler for broadcast aggregation
+ * - Message tracking fields from BaseMessage (messageId, correlationId)
+ */
+interface RequestContext<Payload, Response> extends BaseMessageContext {
+  /** Discriminator - always true for requests */
+  isRequest: true;
+  /** The request payload */
+  payload: Payload;
+  /** Set the response value (ends the handler chain) */
+  setResult: (result: Response) => void;
+  /**
+   * Read the current result value.
+   *
+   * Returns the value set by `setResult()` in this handler or by a downstream
+   * handler after `await next()`. Undefined until a result has been set.
+   */
+  readonly result: Response | undefined;
+  /**
+   * Shallow-merge additional fields into the current result.
+   *
+   * Only valid for object-typed responses. In the request path the operation
+   * uses spread (immutable); in broadcast mode it uses `Object.assign`
+   * (in-place mutation) so the already-pushed result reference stays current.
+   * If no result has been set yet, starts from an empty object.
+   * @param extension - Fields to merge into the current result
+   */
+  extendResult: (extension: [Response] extends [Record<string, unknown>] ? Partial<Response> : never) => void;
+  /**
+   * Call the next handler in the middleware chain.
+   * If no more handlers exist, throws NoHandlerError.
+   */
+  next: () => Promise<void>;
+  /**
+   * Replace the payload with a new value.
+   * Subsequent handlers in the middleware chain will receive the new payload.
+   * Useful for hooks that need to inject context before the main handler runs.
+   */
+  replacePayload: (newPayload: Payload) => void;
+  /**
+   * Identify this handler for broadcast aggregation.
+   * Only present when called via broadcast() - call before setResult().
+   * @param nodeId - Unique identifier for this handler/node
+   */
+  identify?: (nodeId: string) => void;
+}
+/**
+ * Unified context for wildcard handlers that can match both events and requests.
+ * Use the `isRequest` discriminator to narrow the type.
+ * @example
+ * ```typescript
+ * MakaioBus.on('adapter.*', (context) => {
+ *   if (context.isRequest) {
+ *     // TypeScript knows this is RequestContext
+ *     context.setResult({ handled: true });
+ *   } else {
+ *     // TypeScript knows this is EventContext
+ *     console.debug('Event:', context.payload);
+ *   }
+ * });
+ * ```
+ */
+type WildcardContext<Payload = unknown, Response = unknown> = EventContext<Payload> | RequestContext<Payload, Response>;
+//#endregion
+//#region packages/makaio-core/src/types/filter.d.ts
+type Primitive = string | number | boolean | null;
+/**
+ * Filter operators for payload field matching.
+ * @example
+ * ```typescript
+ * // Equality (implicit)
+ * { agentId: 'agent-123' }
+ *
+ * // Membership
+ * { status: { $in: ['active', 'pending'] } }
+ *
+ * // Not equal
+ * { type: { $ne: 'internal' } }
+ *
+ * // Presence check
+ * { error: { $exists: false } }
+ *
+ * // String prefix/suffix matching
+ * { path: { $startsWith: '.git/' } }
+ * { file: { $endsWith: '.ts' } }
+ * ```
+ */
+type FilterOperator<T extends Primitive = Primitive> = T | {
+  $in: T[];
+} | {
+  $ne: T;
+} | {
+  $exists: boolean;
+} | {
+  $startsWith: string;
+} | {
+  $endsWith: string;
+};
+/**
+ * Untyped payload filter - accepts any string keys.
+ * Use TypedPayloadFilter<T> for type-safe filters.
+ */
+type PayloadFilter = Record<string, FilterOperator>;
+/**
+ * Type-safe payload filter constrained to valid paths of a payload type.
+ *
+ * Uses type-fest's `Paths` to support dotted path notation for nested fields.
+ * @example
+ * ```typescript
+ * interface McpPayload {
+ *   agentId: string;
+ *   raw: { msg: { type: string } };
+ * }
+ *
+ * // Type-safe - validates both top-level and nested paths
+ * const filter: TypedPayloadFilter<McpPayload> = {
+ *   agentId: 'agent-123',
+ *   'raw.msg.type': 'session_configured',  // ✅ valid path
+ *   'raw.msg.typo': 'x',                   // ❌ type error
+ * };
+ * ```
+ */
+type TypedPayloadFilter<T> = { [K in Paths<T> & string]?: FilterOperator };
+/**
+ * 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 packages/makaio-core/src/types/schema.d.ts
+/**
+ * Schema definition for event subjects (fire-and-forget).
+ * Events have only a payload schema, no response.
+ * The payload is now separate from the context, so no restrictions needed.
+ */
+type EventSchema = z.ZodType;
+/**
+ * Schema definition for request subjects (request-response).
+ * Requests have both a request payload schema and a response schema.
+ */
+type RequestSchema<Request extends ZodType = ZodType, Response extends ZodType = ZodType> = {
+  request: Request;
+  response: Response;
+};
+/**
+ * Wrapper to mark a subject as local-only (never sent to transports).
+ *
+ * Use `localSubject()` from `@makaio/bus-core` to create these.
+ * @example
+ * ```typescript
+ * import { localSubject } from '@makaio/framework/bus';
+ *
+ * const WidgetSchemas = {
+ *   register: localSubject(widgetDefinitionSchema),  // local event
+ *   unregister: localSubject(z.object({ widgetId: z.string() })),
+ * };
+ * ```
+ */
+type LocalSubjectSchema<T extends EventSchema | RequestSchema = EventSchema | RequestSchema> = {
+  readonly __local: true;
+  readonly schema: T;
+};
+/**
+ * Wrapper to mark a subject as channel-only (encrypted point-to-point).
+ *
+ * Channel subjects are rejected by public bus methods and are only
+ * routable through the DirectChannel encrypted transport. Use
+ * `channelSubject()` from `@makaio/bus-core` to create these.
+ * @example
+ * ```typescript
+ * import { channelSubject } from '@makaio/framework/bus';
+ *
+ * const DirectSchemas = {
+ *   message: channelSubject(z.object({ text: z.string() })),
+ *   ping: channelSubject({
+ *     request: z.object({ ts: z.number() }),
+ *     response: z.object({ ts: z.number() }),
+ *   }),
+ * };
+ * ```
+ */
+type ChannelSubjectSchema<T extends EventSchema | RequestSchema = EventSchema | RequestSchema> = {
+  readonly __channel: true;
+  readonly schema: T;
+};
+/**
+ * Base schema types (unwrapped).
+ */
+type BaseSubjectSchema = EventSchema | RequestSchema;
+/**
+ * Union of all subject schema types (including local and channel wrappers).
+ */
+type SubjectSchema = BaseSubjectSchema | LocalSubjectSchema | ChannelSubjectSchema;
+type SchemaRecord = Record<string, SubjectSchema>;
+//#endregion
+//#region packages/makaio-core/src/types/type-helpers.d.ts
+/**
+ * Unwrap LocalSubjectSchema or ChannelSubjectSchema wrappers if present.
+ * Returns the inner schema for wrapped subjects, or the schema as-is otherwise.
+ */
+type UnwrapSchema<S> = S extends {
+  readonly __local: true;
+  readonly schema: infer Inner;
+} ? Inner : S extends {
+  readonly __channel: true;
+  readonly schema: infer Inner;
+} ? Inner : S;
+/**
+ * Infer payload type from schema (handles EventSchema, RequestSchema,
+ * LocalSubjectSchema, and ChannelSubjectSchema).
+ *
+ * For requests:
+ * - Uses z.input for request (what callers pass before validation/defaults)
+ * - Uses z.infer for response (what handlers return after processing)
+ *
+ * This allows schemas with .default() to have optional fields in the caller API
+ * while the response type reflects the validated output.
+ *
+ * LocalSubjectSchema and ChannelSubjectSchema wrappers are automatically
+ * unwrapped before inference.
+ *
+ * Idempotent: Returns already-inferred types as-is.
+ */
+type InferSchemaPayload<S extends SubjectSchema> = InferSchemaPayloadInner<UnwrapSchema<S>>;
+type InferSchemaPayloadInner<S> = S extends {
+  request: infer Req extends z.ZodType;
+  response: infer Res extends z.ZodType;
+} ? {
+  request: z.input<Req>;
+  response: z.infer<Res>;
+} : S extends z.ZodType ? Simplify<z.infer<S>> : unknown;
+/**
+ * Compute all subject meta from the original schema in one place.
+ *
+ * Resolves payload, locality, channel membership, request/event discriminator,
+ * and namespace from a raw SubjectSchema.
+ * @typeParam S - The subject schema type
+ * @typeParam Ns - The namespace string
+ */
+type InferSubjectMeta<S extends SubjectSchema, Ns extends string> = {
+  /** True when the subject is a request-response pair, false for events. */isRequest: UnwrapSchema<S> extends {
+    request: z.ZodType;
+    response: z.ZodType;
+  } ? true : false; /** True when the subject is wrapped with `localSubject()`. */
+  local: S extends LocalSubjectSchema ? true : false; /** True when the subject is wrapped with `channelSubject()`. */
+  channel: S extends ChannelSubjectSchema ? true : false; /** Inferred payload type (request/response pair or event payload). */
+  payload: InferSchemaPayload<S>; /** The namespace this subject belongs to. */
+  namespace: Ns;
+};
+//#endregion
+//#region packages/makaio-core/src/types/subjects.d.ts
+type SubjectRecord<SubjectKeys extends string = string, Payload extends MessagePayload = MessagePayload> = Record<SubjectKeys, Payload>;
+type SubjectRecordFromSchemaRecord<SchemaRecord extends Record<string, SubjectSchema>> = { [K in keyof SchemaRecord & string]: Simplify<InferSchemaPayload<SchemaRecord[K]>> };
+type SubjectDefinitionMeta<Subject extends SubjectRecord = SubjectRecord<'default'>, K extends keyof Subject = keyof Subject, Namespace extends string = string> = {
+  isRequest: Subject extends SubjectRecord<'default'> ? boolean : Subject[K] extends RequestMessagePayload ? true : false;
+  payload: K extends string ? Subject[K] : unknown;
+  namespace: Namespace;
+  /**
+   * If true, this subject is local-only and will never be sent to transports.
+   * Use for subjects whose payloads contain non-serializable data (e.g., React components).
+   */
+  local: boolean;
+  /**
+   * If true, this subject is channel-only and is only routable through the
+   * DirectChannel encrypted point-to-point transport.
+   */
+  channel: boolean;
+};
+type SubjectDefinition<Subject extends SubjectRecord = SubjectRecord, SubjectKey extends keyof Subject = keyof Subject, Namespace extends string = string> = {
+  $meta: SubjectDefinitionMeta<Subject, SubjectKey, Namespace>;
+  subject: SubjectKey;
+};
+/** 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 packages/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 packages/makaio-core/src/types/handler-types.d.ts
+type EventHandler<T> = (context: EventContext<T>) => void | Promise<void>;
+type RequestHandler<Payload, Response> = (context: RequestContext<Payload, Response>) => void | Promise<void>;
+/**
+ * Context provided to __onAny handlers for debugging/testing.
+ * Captures all message metadata regardless of type (event/request/broadcast).
+ */
+interface AnyMessageContext {
+  type: 'event' | 'request' | 'broadcast';
+  subject: string;
+  namespace: string;
+  payload: unknown;
+  messageId: string;
+  correlationId?: string;
+}
+/**
+ * Handler for __onAny - receives all messages (events and requests) across all namespaces.
+ * Used for debugging and testing only.
+ */
+type AnyHandler = (context: AnyMessageContext) => void | Promise<void>;
+/**
+ * Special handler for wildcards that match both events and requests.
+ * @public
+ */
+type WildcardUnifiedHandler = (context: WildcardContext<unknown, unknown>) => void | Promise<void>;
+/**
+ * Resolve the appropriate handler type for a subject pattern (exact or wildcard).
+ *
+ * Handles all subscription patterns:
+ * - Event wildcards (`adapter.*`) → `(payload: unknown) => void | Promise<void>`
+ * - Request wildcards (`adapter.*`) → `(context: RequestContext<unknown, unknown>) => void | Promise<void>`
+ * - Exact request subjects → `RequestHandler<TPayload, TReturnValue>`
+ * - Exact event subjects → `EventHandler<TPayload>`
+ *
+ * This is the primary type used by the `on()` method to resolve handler signatures.
+ * @example
+ * ```typescript
+ * // Event wildcard - unknown payload
+ * type Handler1 = HandlerForPattern<'adapter.*'>;
+ * // (payload: unknown) => void | Promise<void>
+ *
+ * // Exact event subject - typed payload
+ * type Handler2 = HandlerForPattern<'adapter.log'>;
+ * // EventHandler<{ message: string, level: string }>
+ *
+ * // Request wildcard - unknown context
+ * type Handler3 = HandlerForPattern<'adapter.*'>;
+ * // (context: RequestContext<unknown, unknown>) => void | Promise<void>
+ *
+ * // Exact request subject - typed context
+ * type Handler4 = HandlerForPattern<'adapter.getCapabilities'>;
+ * // RequestHandler<{ adapterName: string }, { capabilities: string[] }>
+ * ```
+ */
+/**
+ * Resolve the handler type for a SubjectDefinition.
+ *
+ * Uses indexed access (`T['$meta']['payload']`) instead of nested `extends` with `infer`
+ * to ensure proper type resolution when T is a generic type parameter.
+ */
+type HandlerForSubjectDefinition<T extends SubjectDefinition> = T['subject'] extends WildcardSubject ? WildcardUnifiedHandler : T['$meta']['payload'] extends RequestMessagePayload<infer Request, infer Response> ? RequestHandler<Request, Response> : T['$meta']['payload'] extends EventMessagePayload<infer Payload> ? EventHandler<Payload> : never;
+/**
+ * Extract context type for once() promise return value.
+ *
+ * Uses the same pattern as HandlerForSubjectDefinition for consistency.
+ */
+type ContextForSubjectDefinition<T extends SubjectDefinition> = T['subject'] extends WildcardSubject ? WildcardContext<unknown, unknown> : T['$meta']['payload'] extends RequestMessagePayload<infer Request, infer Response> ? RequestContext<Request, Response> : T['$meta']['payload'] extends EventMessagePayload<infer Payload> ? EventContext<Payload> : never;
+//#endregion
+//#region packages/makaio-core/src/types/result.d.ts
+/**
+ * Result types for optional request handling.
+ *
+ * Used by requestOptional to distinguish between "handler returned data"
+ * and "no handler was registered".
+ */
+/**
+ * Discriminated union for optional request results.
+ *
+ * - `handled: true` - A handler was found and returned data
+ * - `handled: false` - No handler was registered for the subject
+ * @example
+ * ```typescript
+ * const result = await bus.requestOptional(Subjects.getData, { id: '123' });
+ * if (result.handled) {
+ *   console.debug('Got data:', result.data);
+ * } else {
+ *   console.debug('No handler registered for getData');
+ * }
+ * ```
+ */
+type OptionalResult<T> = {
+  handled: true;
+  data: T;
+} | {
+  handled: false;
+};
+//#endregion
+//#region packages/makaio-core/src/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 packages/makaio-core/src/subject-helpers/nest-subject-definitions.d.ts
+/**
+ * Recursively nests a flat record of dotted keys into a hierarchical object type.
+ *
+ * ```
+ * { 'assistant.text': SubjectDef, 'agent.tool.started': SubjectDef }
+ * → { assistant: { text: SubjectDef }, agent: { tool: { started: SubjectDef } } }
+ * ```
+ *
+ * Used to expose registered subjects as a nested accessor tree (e.g.
+ * `BootSubjects.service.ready`) without requiring callers to deal with
+ * flat dotted-key strings at the type level.
+ */
+type NestedSubjectDefinitions<T extends Record<string, unknown> = Record<string, SubjectDefinition>> = { [K in ExtractPrefixes<keyof T & string>]: NestByPrefix<T, K> };
+type ExtractPrefixes<Keys extends string> = Keys extends `${infer Prefix}.${string}` ? Prefix : Keys;
+type StripPrefixMap<T, Prefix extends string> = { [K in keyof T as K extends `${Prefix}.${infer Rest}` ? Rest : never]: T[K] };
+type NestByPrefix<T extends Record<string, unknown>, Prefix extends string> = Prefix extends keyof T ? T[Prefix] : NestedSubjectDefinitions<StripPrefixMap<T, Prefix>>;
+/**
+ * Maps a flat schema record to a flat subject-definition record, attaching the
+ * correct `$meta` (namespace, isRequest, local, channel) and `subject` key for
+ * each entry.
+ *
+ * Intermediate type used by {@link nestSubjectDefinitions} before nesting.
+ * @typeParam Domain - Namespace domain string (e.g. `'boot'`)
+ * @typeParam Schemas - Flat record of raw Zod schemas keyed by dotted subject names
+ */
+type FlatSubjectDefinitions<Domain extends string, Schemas extends Record<string, SubjectSchema>> = { [K in keyof Schemas & string]: {
+  $meta: InferSubjectMeta<Schemas[K], Domain>;
+  subject: K;
+} };
+/**
+ * Fully-nested subject accessor tree returned by `registerNamespace`.
+ *
+ * Combines the {@link NestedSubjectDefinitions} hierarchy with a `$all`
+ * wildcard that matches every subject in the namespace. Consumers use this
+ * type to write `SomeNamespace.subjects.foo.bar` instead of raw strings.
+ * @typeParam RecordOfSubjectDefinitions - Flat record of subject definitions
+ * @typeParam Domain - Namespace domain string used for `$all` wildcard typing
+ */
+type BusSubjects<RecordOfSubjectDefinitions extends Record<string, unknown> = Record<string, SubjectDefinition>, Domain extends string = string> = NestedSubjectDefinitions<RecordOfSubjectDefinitions> & {
+  $all: WildcardSubjectDefinition<Domain>;
+};
+/**
+ * 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
+ * @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): 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 packages/makaio-core/src/subject-helpers/is-request-schema.d.ts
+/**
+ * Type guard to check if a schema is a request schema.
+ * @param schema - The schema to check
+ * @returns True if the schema is a RequestSchema, false otherwise
+ */
+declare function isRequestSchema(schema: SubjectSchema): schema is RequestSchema;
+//#endregion
+//#region packages/makaio-core/src/subject-helpers/is-local-schema.d.ts
+/**
+ * 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 packages/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 packages/makaio-core/src/subject-helpers/unwrap-schema.d.ts
+/**
+ * Unwrap any subject schema wrapper (local or channel) 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 packages/makaio-core/src/bus-namespace-definition.d.ts
+/**
+ * Report passed to the {@link NamespaceRegistrationOptions} `onSchemaViolation` callback
+ * when lenient validation detects a schema mismatch.
+ *
+ * Canonical owner: `@makaio/core`. `@makaio/bus-core` imports this type from core.
+ */
+interface SchemaViolationReport {
+  /** Fully-qualified subject key (e.g., `"adapter:claude-code.sdk.event"`) */
+  subject: string;
+  /** Raw payload that failed validation */
+  payload: unknown;
+  /** Individual Zod issues from the failed parse */
+  issues: unknown[];
+}
+/**
+ * Options controlling runtime schema validation for a registered bus namespace.
+ *
+ * - `strict` (default) — throw `ValidationError` on schema mismatch
+ * - `lenient` — invoke `onSchemaViolation` callback, then deliver the event anyway
+ * - `skip` — no validation at all (for cross-Zod-version scenarios, e.g., SDK bundles Zod v3)
+ *
+ * Canonical owner: `@makaio/core`. `@makaio/bus-core` imports this type from core,
+ * not the other way around. Single source of truth — no mirroring.
+ */
+type NamespaceRegistrationOptions = {
+  busValidationMode?: 'strict';
+} | {
+  busValidationMode: 'lenient';
+  onSchemaViolation: (report: SchemaViolationReport) => void;
+} | {
+  busValidationMode: 'skip';
+};
+/**
+ * A declarative bus namespace definition.
+ *
+ * Created by {@link createBusNamespace}. Carries typed subject tokens for
+ * immediate use in bus operations, plus the original schemas for deferred
+ * registration at boot time via `MakaioBus.registerNamespace()`.
+ *
+ * Does not include `scopedBus()` — that method requires a bus instance and
+ * is available on the `BusNamespace` object returned by `registerNamespace()`.
+ * @typeParam Domain - Namespace domain string (e.g. `'adapter'`, `'session'`)
+ * @typeParam Schemas - Schema record mapping subject keys to Zod schemas
+ */
+interface BusNamespaceDefinition<Domain extends string = string, Schemas extends Record<string, SubjectSchema> = Record<string, SubjectSchema>> {
+  /** Namespace domain string (e.g., `'adapter'`, `'session'`) */
+  readonly name: Domain;
+  /**
+   * Typed subject tokens for bus operations — no registration needed to use
+   * these for `bus.on()`, `bus.emit()`, or `bus.request()`.
+   */
+  readonly subjects: BusSubjects<FlatSubjectDefinitions<Domain, Schemas>, Domain>;
+  /** Original Zod schemas — carried for deferred registration */
+  readonly schemas: Schemas;
+  /** Registration options (validation mode, violation callback) */
+  readonly options?: NamespaceRegistrationOptions;
+  /**
+   * Phantom field for type inference of filterable payload shape.
+   *
+   * Never set at runtime. Exists solely so TypeScript can infer the
+   * `FilterPayload` type parameter from the schema record without an
+   * explicit annotation at every callsite.
+   * @internal
+   */
+  readonly __filterPayload?: FilterablePayloadIntersection<SubjectRecordFromSchemaRecord<Schemas>>;
+}
+/**
+ * Namespace definition shape required for runtime registration.
+ *
+ * Structurally derived from {@link BusNamespaceDefinition} with the typed
+ * subject tree erased to `unknown`. Composition-root catalogs and extension
+ * manifests only need the namespace name, schemas, options, and the runtime
+ * subject tokens; keeping this structural type separate lets those catalogs
+ * contain heterogeneous namespace definitions without widening every subject
+ * tree to an unsafe index signature.
+ */
+type RegistrableBusNamespaceDefinition = Omit<BusNamespaceDefinition, 'subjects' | '__filterPayload'> & {
+  /** Runtime subject token tree created by `createBusNamespace`. */readonly subjects: unknown;
+};
+/**
+ * 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 options (validation mode, violation callback)
+ * @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?: NamespaceRegistrationOptions): BusNamespaceDefinition<Domain, Schemas>;
+//#endregion
+//#region packages/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 packages/makaio-core/src/errors/index.d.ts
+/**
+ * Base error class for all Makaio-related errors.
+ */
+declare class MakaioError extends Error {
+  readonly subject?: string | undefined;
+  constructor(message: string, subject?: string | undefined);
+}
+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
+export { type AnyHandler, type AnyMessageContext, AuthenticationError, type BaseSubjectSchema, type BusNamespaceDefinition, type BusSubjects, type ChannelSubjectSchema, ConfigError, type ContextForSubjectDefinition, 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 MessagePayload, ModelUnavailableError, type NamespaceRegistrationOptions, type NestedSubjectDefinitions, 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 TypedPayloadFilter, type WildcardContext, type WildcardSubject, type WildcardSubjectDefinition, WildcardSubjectKey, type WildcardUnifiedHandler, channelSubject, createBusNamespace, createMakaioContext, getFullSubjectForSubjectDefinition, isChannelSchema, isLocalSchema, isOperatorObject, isRequestSchema, localSubject, nestSubjectDefinitions, unwrapSchema };