@hile/micro 4.0.2 → 4.0.4

package/AI.md

@@ -35,13 +35,14 @@ Message handler file:
 
 ```ts
 // src/messages/ping.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data, params }) => {
+export default defineMicroMessage(async ({ data, params, invocation }) => {
   return {
     type: 'pong',
     data,
     params,
+    requestId: invocation.context.values.requestId,
     timestamp: Date.now(),
   }
 })
@@ -74,7 +75,11 @@ export default defineService('micro.app', async (shutdown) => {
 Caller:
 
 ```ts
-const result = await app.call('example.service', '/ping', { hello: 'world' })
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID() })
+const result = await app.call('example.service', '/ping', { hello: 'world' }, { context })
 ```
 
 ## More Examples
@@ -83,11 +88,11 @@ Streaming handler:
 
 ```ts
 // src/messages/events.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async function* () {
+export default defineMicroMessage(async function* ({ invocation }) {
   for (let i = 0; i < 3; i++) {
-    yield { seq: i }
+    yield { seq: i, requestId: invocation.context.values.requestId }
   }
 })
 ```
@@ -95,7 +100,7 @@ export default defineMessage(async function* () {
 Streaming caller:
 
 ```ts
-const stream = await app.stream('example.service', '/events', {})
+const stream = await app.stream('example.service', '/events', {}, { context })
 for await (const chunk of stream) {
   console.log(chunk)
 }
@@ -132,13 +137,13 @@ Use the message packages for request/response messaging over WebSocket, process
 
 - Do not use `stream()` for normal single-result calls.
 - Do not rely on message IDs for business idempotency. They are transport IDs.
-- Do not bypass `defineMessage()` for file-loaded handlers.
+- Use `defineMicroMessage()` for Micro business handlers; reserve generic `defineMessage()` for transport-neutral loaders.
 - Do not pass zero, fractional, non-finite, or oversized message timeouts. Explicit timeout values must be safe integers from `1` through `2_147_483_647` milliseconds.
 
 ## Install
 
 ```bash
-pnpm add @hile/micro @hile/message-loader @hile/message-ws
+pnpm add @hile/context @hile/micro @hile/message-loader @hile/message-ws
 ```
 
 Use transport-specific packages only when you need to build custom IPC or worker-thread bridges.
@@ -147,7 +152,8 @@ Use transport-specific packages only when you need to build custom IPC or worker
 
 ```ts
 import { defineMessage, MessageLoader } from '@hile/message-loader'
-import { Application, Registry, Server } from '@hile/micro'
+import { createExecutionContext } from '@hile/context'
+import { Application, defineMicroMessage, Registry, Server } from '@hile/micro'
 import { MessageWs } from '@hile/message-ws'
 import { MessageIpc } from '@hile/message-ipc'
 import { MessageWorkerThread } from '@hile/message-worker-thread'
@@ -155,7 +161,7 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 
 ## Compose With
 
-- `@hile/context` propagates context in micro message metadata.
+- Pass `ExecutionContext` explicitly in every business call or stream option; the receiver gets it in `invocation.context`.
 - `@hile/redis-idempotency` protects retryable side effects in message handlers.
 - `@hile/redis-stream-queue` is better for durable background jobs.
 
@@ -170,8 +176,8 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 - Each modem schedules request, total-stream, and idle-stream deadlines through one internal deadline scheduler. This reduces active Node.js timers without changing timeout, cancellation, ordering, or error semantics.
 - `@hile/message-ws` keeps public `decodeMessageFrame()` payloads isolated from caller-owned input by default. Its owned WebSocket `RawData` path uses a zero-copy binary Flight payload view internally.
 - A stream request requires `exec()` to return an async iterable.
-- `Application.call(namespace, url, data, options?)` returns a promise.
-- `Application.stream(namespace, url, data, options?)` returns a readable stream.
+- `Application.call(namespace, url, data, options)` requires `options.context` and returns a promise.
+- `Application.stream(namespace, url, data, options)` requires `options.context` and returns a readable stream.
 - `Application.publish(topic, payload)` returns an object with `update()` and `unpublish()`.
 - `Application.subscribe(topic, callback)` returns an unsubscribe function.
 - `Registry` stores service addresses and retained config/topic state under `~/.registry`.
@@ -185,8 +191,8 @@ import { MessageWorkerThread } from '@hile/message-worker-thread'
 
 ## Verification Checklist
 
-- Message files default-export `defineMessage(...)`.
-- RPC callers use `await app.call(...)`.
+- Micro message files default-export `defineMicroMessage(...)` and receive `invocation.context`.
+- RPC callers use `await app.call(..., { context })`.
 - Streaming handlers are async generators.
 - Custom modem timeout values use the documented safe-integer range.
 - Registry is started before application nodes need discovery.
@@ -220,10 +226,10 @@ Provider handler:
 
 ```ts
 // src/messages/charge.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data }) => {
-  return { charged: true, input: data }
+export default defineMicroMessage(async ({ data, invocation }) => {
+  return { charged: true, input: data, requestId: invocation.context.values.requestId }
 })
 ```
 
@@ -251,10 +257,14 @@ export default defineService('billing.micro', async (shutdown) => {
 Consumer:
 
 ```ts
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID(), tenantId: 't1' })
 const result = await app.call('billing', '/charge', {
   tenantId: 't1',
   amount: 100,
-})
+}, { context })
 ```
 
 ## File Layout
@@ -274,16 +284,15 @@ Use this recipe when services communicate over Hile registry-backed RPC.
 ## Packages To Use
 
 - `@hile/micro`
-- `@hile/message-loader`
-- `@hile/context` when context must cross service boundaries
+- `@hile/context` for the required explicit execution context carrier
 - `@hile/redis-idempotency` for retryable side effects
 
 ## Implementation Steps
 
 1. Start a Registry with `hile registry`.
 2. Start providers with stable namespaces.
-3. Load `*.msg.ts` handlers through `app.load()`.
-4. Call providers with `await app.call(namespace, url, data)`.
+3. Default-export `defineMicroMessage()` handlers and load them through `app.load()`.
+4. Create context at ingress and call providers with `await app.call(namespace, url, data, { context })`.
 5. Use `app.stream()` only for async-generator handlers.
 
 ## Failure And Cleanup Behavior
@@ -296,8 +305,8 @@ Use this recipe when services communicate over Hile registry-backed RPC.
 
 - Registry is reachable.
 - Provider namespace matches consumer call.
-- Handlers default-export `defineMessage()`.
-- Consumer code awaits `app.call(...)` directly.
+- Handlers default-export `defineMicroMessage()` and consume explicit invocation context when needed.
+- Consumer code awaits `app.call(..., { context })` directly.
 
 # Runtime Dynamic Config
 

package/README.md

@@ -22,13 +22,14 @@ Message handler file:
 
 ```ts
 // src/messages/ping.msg.ts
-import { defineMessage } from '@hile/message-loader'
+import { defineMicroMessage } from '@hile/micro'
 
-export default defineMessage(async ({ data, params }) => {
+export default defineMicroMessage(async ({ data, params, invocation }) => {
   return {
     type: 'pong',
     data,
     params,
+    requestId: invocation.context.values.requestId,
     timestamp: Date.now(),
   }
 })
@@ -61,14 +62,18 @@ export default defineService('micro.app', async (shutdown) => {
 Caller:
 
 ```ts
-const result = await app.call('example.service', '/ping', { hello: 'world' })
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID() })
+const result = await app.call('example.service', '/ping', { hello: 'world' }, { context })
 ```
 
 ## Boundaries
 
 - Do not use `stream()` for normal single-result calls.
 - Do not rely on message IDs for business idempotency. They are transport IDs.
-- Do not bypass `defineMessage()` for file-loaded handlers.
+- Use `defineMicroMessage()` for Micro business handlers; reserve generic `defineMessage()` for transport-neutral loaders.
 - Do not pass zero, fractional, non-finite, or oversized message timeouts. Explicit timeout values must be safe integers from `1` through `2_147_483_647` milliseconds.
 
 - Appending a secondary response getter to `client.request('/x', data)`
@@ -78,8 +83,8 @@ const result = await app.call('example.service', '/ping', { hello: 'world' })
 
 ## Verify
 
-- Message files default-export `defineMessage(...)`.
-- RPC callers use `await app.call(...)`.
+- Micro message files default-export `defineMicroMessage(...)` and receive `invocation.context`.
+- RPC callers use `await app.call(..., { context })`.
 - Streaming handlers are async generators.
 - Custom modem timeout values use the documented safe-integer range.
 - Registry is started before application nodes need discovery.

package/dist/application.d.ts

@@ -1,3 +1,4 @@
+import { type ExecutionContext } from '@hile/context';
 import { Client, type ClientStreamOptions } from './client.js';
 import { Server, type MicroServerProps } from './server.js';
 import type { RegistryAddress, RegistryTopicSnapshot, RegistryTopicSnapshotsResult, RegistryTopicSummary } from './registry';
@@ -48,6 +49,15 @@ export type ApplicationProps = {
     /** 本地内存熔断策略配置 */
     circuitBreaker?: CircuitBreakerOptions;
 } & MicroServerProps;
+export type ApplicationCallOptions = {
+    context: ExecutionContext;
+    timeout?: number;
+    retries?: number;
+    signal?: AbortSignal;
+};
+export type ApplicationStreamOptions = ClientStreamOptions & {
+    retries?: number;
+};
 export declare class Application extends Server {
     private registry?;
     private reconnectTimeout?;
@@ -108,16 +118,10 @@ export declare class Application extends Server {
     private findFromRegistry;
     get(namespace: string, exclude?: string[]): Promise<Client>;
     protected resolveClient(namespace: string, exclude?: string[], options?: RegistryLookupOptions): Promise<Client>;
-    call<T = any>(namespace: string, url: string, data: any, options?: {
-        timeout?: number;
-        retries?: number;
-        signal?: AbortSignal;
-    }): Promise<T>;
-    stream(namespace: string, url: string, data: any, options?: ClientStreamOptions & {
-        retries?: number;
-    }): Promise<import('stream').Readable>;
+    call<T = any>(namespace: string, url: string, data: any, options: ApplicationCallOptions): Promise<T>;
+    stream(namespace: string, url: string, data: any, options: ApplicationStreamOptions): Promise<import('stream').Readable>;
     /** Opens a stream against one exact service instance without registry selection. */
-    streamPeer(address: RegistryAddress, url: string, data: any, options?: ClientStreamOptions): Promise<import('stream').Readable>;
+    streamPeer(address: RegistryAddress, url: string, data: any, options: ClientStreamOptions): Promise<import('stream').Readable>;
     publish<T = any>(topic: string, data: T): Promise<{
         update: (payload: T) => Promise</*elided*/ any>;
         unpublish: () => Promise</*elided*/ any>;

package/dist/application.js

@@ -1,3 +1,4 @@
+import { MissingExecutionContextError, parseExecutionContext, } from '@hile/context';
 import { Server } from './server.js';
 var RegistryLookupStatus;
 (function (RegistryLookupStatus) {
@@ -302,7 +303,7 @@ export class Application extends Server {
             if (preserveRevision && this.publishedTopicRevisions.has(topic)) {
                 request.revision = this.publishedTopicRevisions.get(topic);
             }
-            const revision = await registry.request('/-/declare', request, this.registryRequestOptions());
+            const revision = await registry.requestControl('/-/declare', request, this.registryRequestOptions());
             if (this.publishedTopics.has(topic) &&
                 this.publishedTopicVersions.get(topic) === version &&
                 Number.isFinite(revision)) {
@@ -313,12 +314,12 @@ export class Application extends Server {
     }
     syncUnpublishedTopic(topic, options = {}) {
         return this.enqueueTopicSync(topic, async (registry) => {
-            await registry.request('/-/undeclare', { topic }, this.registryRequestOptions());
+            await registry.requestControl('/-/undeclare', { topic }, this.registryRequestOptions());
         }, options);
     }
     syncUnsubscribedTopic(topic, options = {}) {
         return this.enqueueTopicSync(topic, async (registry) => {
-            await registry.request('/-/unsubscribe', { topic }, this.registryRequestOptions());
+            await registry.requestControl('/-/unsubscribe', { topic }, this.registryRequestOptions());
         }, options);
     }
     syncRestoredSubscription(topic, callback, options = {}) {
@@ -330,7 +331,7 @@ export class Application extends Server {
     }
     async restoreSubscription(topic, callback, registry, isReconnect, requireLocal = true) {
         const replayBaseVersion = this.topicUpdateVersions.get(topic) ?? 0;
-        const snapshot = await registry.request('/-/subscribe', { topic }, this.registryRequestOptions());
+        const snapshot = await registry.requestControl('/-/subscribe', { topic }, this.registryRequestOptions());
         if (requireLocal && !this.topics.get(topic)?.has(callback))
             return;
         if (!snapshot.hasData)
@@ -680,7 +681,7 @@ export class Application extends Server {
     async findFromRegistry(namespace, exclude) {
         if (!this.registry)
             throw new Error('Registry not found');
-        const promise = this.registry.request('/-/find', { namespace, exclude });
+        const promise = this.registry.requestControl('/-/find', { namespace, exclude });
         return await withTimeout(promise, this._registryLookupTimeoutMs, 'Registry /-/find');
     }
     get(namespace, exclude) {
@@ -752,7 +753,10 @@ export class Application extends Server {
         });
     }
     async call(namespace, url, data, options) {
-        const { timeout = this._requestTimeoutMs, retries = 1, signal } = options || {};
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro call ${namespace}${url}`);
+        const context = parseExecutionContext(options.context);
+        const { timeout = this._requestTimeoutMs, retries = 1, signal } = options;
         let remainingRetries = retries;
         let retrySourceError;
         let hasRetrySourceError = false;
@@ -769,6 +773,7 @@ export class Application extends Server {
             const { client, probe } = selected;
             try {
                 const result = await client.request(url, data, {
+                    context,
                     timeout: timeout ?? this._requestTimeoutMs,
                     signal,
                 });
@@ -791,7 +796,10 @@ export class Application extends Server {
         }
     }
     async stream(namespace, url, data, options) {
-        const { signal, retries = 1, timeout, idleTimeout, window } = options || {};
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro stream ${namespace}${url}`);
+        const context = parseExecutionContext(options.context);
+        const { signal, retries = 1, timeout, idleTimeout, window } = options;
         let remainingRetries = retries;
         let retrySourceError;
         let hasRetrySourceError = false;
@@ -807,7 +815,7 @@ export class Application extends Server {
             }
             const { client, probe } = selected;
             try {
-                const readable = client.stream(url, data, { signal, timeout, idleTimeout, window });
+                const readable = client.stream(url, data, { context, signal, timeout, idleTimeout, window });
                 return this.trackCircuitStream(namespace, client.host, client.port, probe, readable);
             }
             catch (err) {
@@ -825,6 +833,9 @@ export class Application extends Server {
     }
     /** Opens a stream against one exact service instance without registry selection. */
     async streamPeer(address, url, data, options) {
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro peer stream ${address.host}:${address.port}${url}`);
+        const context = parseExecutionContext(options.context);
         assertValidRegistrySocket('peer address', address.host, address.port);
         if (options?.timeout !== undefined && (!Number.isSafeInteger(options.timeout) || options.timeout < 1 || options.timeout > 2_147_483_647)) {
             throw new TypeError('Stream timeout must be a positive safe integer not exceeding 2147483647');
@@ -834,7 +845,7 @@ export class Application extends Server {
         const timeout = options?.timeout === undefined
             ? undefined
             : Math.max(1, options.timeout - (Date.now() - startedAt));
-        return client.stream(url, data, { ...options, timeout });
+        return client.stream(url, data, { ...options, context, timeout });
     }
     async publish(topic, data) {
         this.assertCanUsePubSub();
@@ -894,7 +905,7 @@ export class Application extends Server {
             this.ensureRegistryReconnectScheduled();
             throw new Error('Registry is not connected');
         }
-        const result = await registry.request('/-/topics', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
+        const result = await registry.requestControl('/-/topics', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
         return structuredClone(result.topics);
     }
     /** Reads current topic payloads in one Registry round trip. */
@@ -904,7 +915,7 @@ export class Application extends Server {
             this.ensureRegistryReconnectScheduled();
             throw new Error('Registry is not connected');
         }
-        const result = await registry.request('/-/topic/snapshots', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
+        const result = await registry.requestControl('/-/topic/snapshots', prefix === undefined ? {} : { prefix }, { ...this.registryRequestOptions(), signal: options?.signal });
         return structuredClone(result.topics);
     }
     /** Reads one retained/current Registry topic payload without subscribing to it. */
@@ -917,7 +928,7 @@ export class Application extends Server {
             this.ensureRegistryReconnectScheduled();
             throw new Error('Registry is not connected');
         }
-        const snapshot = await registry.request('/-/topic/get', { topic }, { ...this.registryRequestOptions(), signal: options?.signal });
+        const snapshot = await registry.requestControl('/-/topic/get', { topic }, { ...this.registryRequestOptions(), signal: options?.signal });
         return snapshot === undefined ? undefined : structuredClone(snapshot);
     }
     /**
@@ -969,7 +980,7 @@ export class Application extends Server {
         await this.enqueueTopicSync(topic, async (registry) => {
             if (!this.topics.get(topic)?.has(callback))
                 return;
-            snapshot = await registry.request('/-/subscribe', { topic }, this.registryRequestOptions());
+            snapshot = await registry.requestControl('/-/subscribe', { topic }, this.registryRequestOptions());
             synced = true;
         });
         if (!synced || !snapshot) {

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import { MessageWs } from "@hile/message-ws";
-import { type ContextData, type ContextInput } from '@hile/context';
+import { type ExecutionContext } from '@hile/context';
 import { Server } from './server.js';
 import { WebSocket } from 'ws';
 import { EventEmitter } from 'node:events';
@@ -10,13 +10,15 @@ export interface ClientProps {
     ws: WebSocket;
 }
 export interface ClientStreamOptions {
+    context: ExecutionContext;
     signal?: AbortSignal;
     timeout?: number;
     idleTimeout?: number;
     window?: number;
 }
 export type MicroMessageMetadata = {
-    context?: ContextInput<ContextData>;
+    context?: ExecutionContext;
+    control?: true;
     [key: string]: unknown;
 };
 export type MicroMessage<T = any> = {
@@ -37,14 +39,26 @@ export declare class Client extends MessageWs {
     constructor(props: ClientProps);
     private startHeartbeat;
     protected exec(data: MicroMessage, signal?: AbortSignal): Promise<any>;
-    request<T = any>(url: string, data: any, options?: {
+    request<T = any>(url: string, data: any, options: {
+        context: ExecutionContext;
         timeout?: number;
         signal?: AbortSignal;
     }): Promise<T>;
-    push(url: string, data: any, options?: {
+    /** Framework-internal transport path. Business requests must use request() with context. */
+    requestControl<T = any>(url: string, data: any, options?: {
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<T>;
+    push(url: string, data: any, options: {
+        context: ExecutionContext;
+        timeout?: number;
+        signal?: AbortSignal;
+    }): void;
+    /** Framework-internal transport path. Business pushes must use push() with context. */
+    pushControl(url: string, data: any, options?: {
         timeout?: number;
         signal?: AbortSignal;
     }): void;
-    stream(url: string, data: any, options?: ClientStreamOptions): import("node:stream").Readable;
+    stream(url: string, data: any, options: ClientStreamOptions): import("node:stream").Readable;
     dispose(): void;
 }

package/dist/client.js

@@ -1,51 +1,44 @@
 import { MessageWs } from "@hile/message-ws";
-import { isContextData, runWithContext, snapshotContext, } from '@hile/context';
+import { createInvocationContext, MissingExecutionContextError, parseExecutionContext, } from '@hile/context';
 import { WebSocket } from 'ws';
 import { EventEmitter } from 'node:events';
-function createEnvelope(url, data) {
-    const context = snapshotContext();
-    if (Object.keys(context).length === 0)
-        return { url, data };
+const FRAMEWORK_CONTROL_ROUTES = new Set([
+    '/-/config/get',
+    '/-/configs',
+    '/-/declare',
+    '/-/find',
+    '/-/namespace/peers',
+    '/-/namespaces',
+    '/-/registry/status',
+    '/-/subscribe',
+    '/-/topic/get',
+    '/-/topic/snapshots',
+    '/-/topic/update',
+    '/-/topics',
+    '/-/undeclare',
+    '/-/unsubscribe',
+]);
+function assertFrameworkControlRoute(url) {
+    if (!FRAMEWORK_CONTROL_ROUTES.has(url)) {
+        throw new TypeError(`Unknown framework control route: ${url}`);
+    }
+}
+function createEnvelope(url, data, context) {
     return {
         url,
         data,
         metadata: {
-            context,
+            context: parseExecutionContext(context),
         },
     };
 }
+function createControlEnvelope(url, data) {
+    assertFrameworkControlRoute(url);
+    return { url, data, metadata: { control: true } };
+}
 function getEnvelopeContext(data) {
     const context = data.metadata?.context;
-    if (!isContextData(context))
-        return undefined;
-    return context;
-}
-function isAsyncIterable(value) {
-    return value != null && typeof value[Symbol.asyncIterator] === 'function';
-}
-function bindAsyncIterableToContext(iterable, context) {
-    return {
-        [Symbol.asyncIterator]() {
-            const iterator = iterable[Symbol.asyncIterator]();
-            return {
-                next() {
-                    return Promise.resolve(runWithContext(context, () => iterator.next()));
-                },
-                return(value) {
-                    if (!iterator.return) {
-                        return Promise.resolve({ done: true, value });
-                    }
-                    return Promise.resolve(runWithContext(context, () => iterator.return(value)));
-                },
-                throw(error) {
-                    if (!iterator.throw) {
-                        return Promise.reject(error);
-                    }
-                    return Promise.resolve(runWithContext(context, () => iterator.throw(error)));
-                },
-            };
-        },
-    };
+    return context === undefined ? undefined : parseExecutionContext(context);
 }
 export class Client extends MessageWs {
     server;
@@ -95,35 +88,55 @@ export class Client extends MessageWs {
         if (!this._online)
             throw new Error('Client is not online');
         const context = getEnvelopeContext(data);
-        const dispatch = async () => {
-            const result = await this.server.dispatch(data.url, data.data, {
-                client: this,
-                metadata: data.metadata,
-                signal,
-            });
-            if (context && isAsyncIterable(result)) {
-                return bindAsyncIterableToContext(result, context);
-            }
-            return result;
-        };
-        if (context)
-            return runWithContext(context, dispatch);
-        return dispatch();
+        const isControl = data.metadata?.control === true && FRAMEWORK_CONTROL_ROUTES.has(data.url);
+        if (!context && !isControl) {
+            throw new MissingExecutionContextError(`inbound micro message ${data.url}`);
+        }
+        const invocation = context
+            ? createInvocationContext(context, signal ?? new AbortController().signal, `inbound micro message ${data.url}`)
+            : undefined;
+        return this.server.dispatch(data.url, data.data, {
+            client: this,
+            metadata: data.metadata,
+            signal,
+            invocation,
+        });
     }
     request(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._send(createEnvelope(url, data), options);
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro client request ${url}`);
+        const { context, ...transport } = options;
+        return this._send(createEnvelope(url, data, context), transport);
+    }
+    /** Framework-internal transport path. Business requests must use request() with context. */
+    requestControl(url, data, options) {
+        if (!this._online)
+            throw new Error('Client is not online');
+        return this._send(createControlEnvelope(url, data), options);
     }
     push(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._push(createEnvelope(url, data), options);
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro client push ${url}`);
+        const { context, ...transport } = options;
+        return this._push(createEnvelope(url, data, context), transport);
+    }
+    /** Framework-internal transport path. Business pushes must use push() with context. */
+    pushControl(url, data, options) {
+        if (!this._online)
+            throw new Error('Client is not online');
+        return this._push(createControlEnvelope(url, data), options);
     }
     stream(url, data, options) {
         if (!this._online)
             throw new Error('Client is not online');
-        return this._stream(createEnvelope(url, data), options);
+        if (!options?.context)
+            throw new MissingExecutionContextError(`micro client stream ${url}`);
+        const { context, ...transport } = options;
+        return this._stream(createEnvelope(url, data, context), transport);
     }
     dispose() {
         if (this.heartbeatTimer)

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export * from './server.js';
 export * from './client.js';
 export * from './application.js';
 export * from './registry.js';
+export * from './message.js';

package/dist/index.js

@@ -2,3 +2,4 @@ export * from './server.js';
 export * from './client.js';
 export * from './application.js';
 export * from './registry.js';
+export * from './message.js';

package/dist/message.d.ts

@@ -0,0 +1,12 @@
+import type { InvocationContext } from '@hile/context';
+import { type MessageFunction, type MessageRegisterProps } from '@hile/message-loader';
+import type { Client, MicroMessageMetadata } from './client';
+export type MicroMessageHandlerExtras = {
+    client: Client;
+    metadata?: MicroMessageMetadata;
+    signal?: AbortSignal;
+    invocation: InvocationContext;
+};
+export type MicroMessageFunction<T = any> = MessageFunction<T, MicroMessageHandlerExtras>;
+/** Defines a file-loaded Micro business handler with an explicit invocation context. */
+export declare function defineMicroMessage<T = any>(handler: MicroMessageFunction<T>): MessageRegisterProps<T, MicroMessageHandlerExtras>;

package/dist/message.js

@@ -0,0 +1,5 @@
+import { defineMessage, } from '@hile/message-loader';
+/** Defines a file-loaded Micro business handler with an explicit invocation context. */
+export function defineMicroMessage(handler) {
+    return defineMessage(handler);
+}

package/dist/registry.js

@@ -490,7 +490,7 @@ export class Registry extends Server {
         for (const key of entry.subscribers.values()) {
             try {
                 if (this.clients.has(key)) {
-                    this.clients.get(key).push(`/-/topic/update`, { topic, payload });
+                    this.clients.get(key).pushControl(`/-/topic/update`, { topic, payload });
                 }
             }
             catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hile/micro",
-  "version": "4.0.2",
+  "version": "4.0.4",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -24,13 +24,13 @@
     "vitest": "^4.0.18"
   },
   "dependencies": {
-    "@hile/context": "^4.0.1",
-    "@hile/logger": "^4.0.0",
-    "@hile/message-loader": "^4.0.2",
-    "@hile/message-ws": "^4.0.2",
+    "@hile/context": "^4.0.2",
+    "@hile/logger": "^4.0.1",
+    "@hile/message-loader": "^4.0.4",
+    "@hile/message-ws": "^4.0.3",
     "internal-ip": "^9.0.0",
     "ws": "^8.21.0",
     "yaml": "^2.9.0"
   },
-  "gitHead": "46d7bcfc78a914aa2af8cd96e41b08511f5af38e"
+  "gitHead": "c89cb395e014c1973dcc0053a533cfea039a91fe"
 }