iii-sdk 0.22.1 → 0.23.0-alpha.2

package/dist/index.d.cts

@@ -1,10 +1,15 @@
-import { C as MiddlewareFunctionInput, d as StreamResponse, r as IIIClient, u as StreamRequest, x as JsonValue } from "./types-n-760A15.cjs";
-import { i as IIIReconnectionConfig } from "./iii-constants-BqXp8xSN.cjs";
-import { InvocationError, InvocationErrorInit } from "./errors.cjs";
+import { D as MiddlewareFunctionInput, T as JsonValue, d as StreamResponse, r as IIIClient, u as StreamRequest, v as IIIConnectionState, y as IIIReconnectionConfig } from "./types-D-KH-5pT.cjs";
+import { n as InvocationErrorInit, r as RegistrationRejectedError, t as InvocationError } from "./errors-B2LphIs-.cjs";
 import { OtelConfig } from "@iii-dev/helpers/observability";
 import { EnqueueResult } from "@iii-dev/helpers/queue";
 
 //#region src/iii.d.ts
+/**
+ * Engine address used when neither an explicit address nor `III_URL` is set.
+ * The IPv4 loopback is spelled out on purpose: `localhost` can resolve to `::1`
+ * on a host whose engine only listens on IPv4.
+ */
+declare const DEFAULT_ENGINE_URL = "ws://127.0.0.1:49134";
 /** Worker metadata reported to the engine (language, framework, project). */
 type TelemetryOptions = {
   /** Programming language of the worker. */language?: string; /** Name of the project this worker belongs to. */
@@ -25,7 +30,19 @@ type TelemetryOptions = {
  * ```
  */
 type InitOptions = {
-  /** Display name for this worker. Defaults to `hostname:pid`. */workerName?: string;
+  /** Display name for this worker. A non-empty `III_WORKER_NAME` overrides it. Defaults to `hostname:pid`. */workerName?: string;
+  /**
+   * Namespace this worker belongs to. Resolution order:
+   * `options.namespace` -> `process.env.III_NAMESPACE` -> undefined. When
+   * undefined the engine applies its `default` namespace.
+   *
+   * It scopes more than the registration. The worker and its functions
+   * register here, so identically-named entries coexist across namespaces, and
+   * everything the worker does afterwards follows it: a `trigger` resolves its
+   * target here, and a `registerTrigger` binds here, unless the call names
+   * another namespace. One declaration places the whole worker.
+   */
+  namespace?: string;
   /**
    * One-line, human/LLM-readable summary of what this worker does.
    * Surfaces in `engine::workers::list` / `engine::workers::info`.
@@ -76,7 +93,7 @@ declare const TriggerAction: {
    * acknowledges the caller with `{ messageReceiptId }`, and processes it
    * asynchronously.
    *
-   * Requires a queue worker in the project. Run `iii worker add queue`.
+   * Requires the `queue` worker in `worker-compose.yaml`.
    * Without it the trigger rejects with `enqueue_error` (no queue provider).
    *
    * @param opts - Queue routing options.
@@ -100,7 +117,8 @@ declare const TriggerAction: {
  * Register the worker with a iii instance, returns a connected worker client.
  * The WebSocket connection is established automatically.
  *
- * @param address - WebSocket URL of the III engine (e.g. `ws://localhost:49134`).
+ * @param address - WebSocket URL of the III engine. Omit to resolve it from
+ *   `process.env.III_URL`, falling back to {@link DEFAULT_ENGINE_URL}.
  * @param options - Optional {@link InitOptions} for worker name, timeouts, reconnection, and OTel.
  * @returns A connected {@link IIIClient} instance.
  *
@@ -108,12 +126,14 @@ declare const TriggerAction: {
  * ```typescript
  * import { registerWorker } from 'iii-sdk'
  *
- * const worker = registerWorker(process.env.III_URL ?? 'ws://localhost:49134', {
- *   workerName: 'my-worker',
- * })
+ * // Address from III_URL, set by whatever supervisor spawned this worker.
+ * const worker = registerWorker()
+ *
+ * // Or explicitly, which always wins over the environment.
+ * const other = registerWorker('ws://localhost:49134', { workerName: 'my-worker' })
  * ```
  */
-declare const registerWorker: (address: string, options?: InitOptions) => IIIClient;
+declare const registerWorker: (address?: string, options?: InitOptions) => IIIClient;
 //#endregion
-export { type EnqueueResult, type IIIClient, type InitOptions, InvocationError, type InvocationErrorInit, type JsonValue, type MiddlewareFunctionInput, type StreamRequest, type StreamResponse, type TelemetryOptions, TriggerAction, registerWorker };
+export { DEFAULT_ENGINE_URL, type EnqueueResult, type IIIClient, type IIIConnectionState, type InitOptions, InvocationError, type InvocationErrorInit, type JsonValue, type MiddlewareFunctionInput, RegistrationRejectedError, type StreamRequest, type StreamResponse, type TelemetryOptions, TriggerAction, registerWorker };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/iii.ts"],"mappings":";;;;;;;;KAoFY,gBAAA;4CAEV,QAAA,WAFU;EAIV,YAAA;EAEA,SAAA,WAJA;EAMA,iBAAA;AAAA;;;;AAeF;;;;;;;;;KAAY,WAAA;EA2BkB,gEAzB5B,UAAA;EAKA;;;;EAAA,iBAAA,WAU6B;EAR7B,sBAAA,YAcO;EAZP,mBAAA;EAcA;;;;;EARA,kBAAA,GAAqB,OAAA,CAAQ,qBAAA;EAggClB;;;;;EA1/BX,IAAA,GAAO,IAAA,CAAK,UAAA;EAEZ,OAAA,GAAU,MAAA;EAEV,SAAA,GAAY,gBAAA;AAAA;;;AA2hCd;;;;;;;;;;;;;;;;;;;;cArCa,aAAA;;;;;;;;;;;;;IAYO,KAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyBP,cAAA,GAAkB,OAAA,UAAiB,OAAA,GAAU,WAAA,KAAc,SAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/iii.ts"],"mappings":";;;;;;;;;AAsGA;;cAAa,kBAAA;;KAmFD,gBAAA;EAAA,0CAEV,QAAA;EAEA,YAAA,WAFA;EAIA,SAAA;EAEA,iBAAA;AAAA;;AAeF;;;;;;;;;;;KAAY,WAAA;EAcV,4GAZA,UAAA;EAmBA;;;;;;;;;;;EAPA,SAAA;EAyB4B;;AAgpC9B;;EApqCE,iBAAA,WAsrCQ;EAprCR,sBAAA,YA8qCkB;EA5qClB,mBAAA;;;;;;EAMA,kBAAA,GAAqB,OAAA,CAAQ,qBAAA;EAksClB;;;;;EA5rCX,IAAA,GAAO,IAAA,CAAK,UAAA,kBA4rCmC;EA1rC/C,OAAA,GAAU,MAAA,kBA2rC+B;EAzrCzC,SAAA,GAAY,gBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;cAgpCD,aAAA;;;;;;;;;;;;;IAYO,KAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BP,cAAA,GAAkB,OAAA,WAAkB,OAAA,GAAU,WAAA,KAAc,SAAA"}

package/dist/index.d.mts

@@ -1,10 +1,15 @@
-import { C as MiddlewareFunctionInput, d as StreamResponse, r as IIIClient, u as StreamRequest, x as JsonValue } from "./types-BD2fp4Py.mjs";
-import { i as IIIReconnectionConfig } from "./iii-constants-Baptl8nm.mjs";
-import { InvocationError, InvocationErrorInit } from "./errors.mjs";
+import { D as MiddlewareFunctionInput, T as JsonValue, d as StreamResponse, r as IIIClient, u as StreamRequest, v as IIIConnectionState, y as IIIReconnectionConfig } from "./types-Be3nGFI2.mjs";
+import { n as InvocationErrorInit, r as RegistrationRejectedError, t as InvocationError } from "./errors-BnYJZ4Ye.mjs";
 import { OtelConfig } from "@iii-dev/helpers/observability";
 import { EnqueueResult } from "@iii-dev/helpers/queue";
 
 //#region src/iii.d.ts
+/**
+ * Engine address used when neither an explicit address nor `III_URL` is set.
+ * The IPv4 loopback is spelled out on purpose: `localhost` can resolve to `::1`
+ * on a host whose engine only listens on IPv4.
+ */
+declare const DEFAULT_ENGINE_URL = "ws://127.0.0.1:49134";
 /** Worker metadata reported to the engine (language, framework, project). */
 type TelemetryOptions = {
   /** Programming language of the worker. */language?: string; /** Name of the project this worker belongs to. */
@@ -25,7 +30,19 @@ type TelemetryOptions = {
  * ```
  */
 type InitOptions = {
-  /** Display name for this worker. Defaults to `hostname:pid`. */workerName?: string;
+  /** Display name for this worker. A non-empty `III_WORKER_NAME` overrides it. Defaults to `hostname:pid`. */workerName?: string;
+  /**
+   * Namespace this worker belongs to. Resolution order:
+   * `options.namespace` -> `process.env.III_NAMESPACE` -> undefined. When
+   * undefined the engine applies its `default` namespace.
+   *
+   * It scopes more than the registration. The worker and its functions
+   * register here, so identically-named entries coexist across namespaces, and
+   * everything the worker does afterwards follows it: a `trigger` resolves its
+   * target here, and a `registerTrigger` binds here, unless the call names
+   * another namespace. One declaration places the whole worker.
+   */
+  namespace?: string;
   /**
    * One-line, human/LLM-readable summary of what this worker does.
    * Surfaces in `engine::workers::list` / `engine::workers::info`.
@@ -76,7 +93,7 @@ declare const TriggerAction: {
    * acknowledges the caller with `{ messageReceiptId }`, and processes it
    * asynchronously.
    *
-   * Requires a queue worker in the project. Run `iii worker add queue`.
+   * Requires the `queue` worker in `worker-compose.yaml`.
    * Without it the trigger rejects with `enqueue_error` (no queue provider).
    *
    * @param opts - Queue routing options.
@@ -100,7 +117,8 @@ declare const TriggerAction: {
  * Register the worker with a iii instance, returns a connected worker client.
  * The WebSocket connection is established automatically.
  *
- * @param address - WebSocket URL of the III engine (e.g. `ws://localhost:49134`).
+ * @param address - WebSocket URL of the III engine. Omit to resolve it from
+ *   `process.env.III_URL`, falling back to {@link DEFAULT_ENGINE_URL}.
  * @param options - Optional {@link InitOptions} for worker name, timeouts, reconnection, and OTel.
  * @returns A connected {@link IIIClient} instance.
  *
@@ -108,12 +126,14 @@ declare const TriggerAction: {
  * ```typescript
  * import { registerWorker } from 'iii-sdk'
  *
- * const worker = registerWorker(process.env.III_URL ?? 'ws://localhost:49134', {
- *   workerName: 'my-worker',
- * })
+ * // Address from III_URL, set by whatever supervisor spawned this worker.
+ * const worker = registerWorker()
+ *
+ * // Or explicitly, which always wins over the environment.
+ * const other = registerWorker('ws://localhost:49134', { workerName: 'my-worker' })
  * ```
  */
-declare const registerWorker: (address: string, options?: InitOptions) => IIIClient;
+declare const registerWorker: (address?: string, options?: InitOptions) => IIIClient;
 //#endregion
-export { type EnqueueResult, type IIIClient, type InitOptions, InvocationError, type InvocationErrorInit, type JsonValue, type MiddlewareFunctionInput, type StreamRequest, type StreamResponse, type TelemetryOptions, TriggerAction, registerWorker };
+export { DEFAULT_ENGINE_URL, type EnqueueResult, type IIIClient, type IIIConnectionState, type InitOptions, InvocationError, type InvocationErrorInit, type JsonValue, type MiddlewareFunctionInput, RegistrationRejectedError, type StreamRequest, type StreamResponse, type TelemetryOptions, TriggerAction, registerWorker };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/iii.ts"],"mappings":";;;;;;;;KAoFY,gBAAA;4CAEV,QAAA,WAFU;EAIV,YAAA;EAEA,SAAA,WAJA;EAMA,iBAAA;AAAA;;;;AAeF;;;;;;;;;KAAY,WAAA;EA2BkB,gEAzB5B,UAAA;EAKA;;;;EAAA,iBAAA,WAU6B;EAR7B,sBAAA,YAcO;EAZP,mBAAA;EAcA;;;;;EARA,kBAAA,GAAqB,OAAA,CAAQ,qBAAA;EAggClB;;;;;EA1/BX,IAAA,GAAO,IAAA,CAAK,UAAA;EAEZ,OAAA,GAAU,MAAA;EAEV,SAAA,GAAY,gBAAA;AAAA;;;AA2hCd;;;;;;;;;;;;;;;;;;;;cArCa,aAAA;;;;;;;;;;;;;IAYO,KAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAyBP,cAAA,GAAkB,OAAA,UAAiB,OAAA,GAAU,WAAA,KAAc,SAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/iii.ts"],"mappings":";;;;;;;;;AAsGA;;cAAa,kBAAA;;KAmFD,gBAAA;EAAA,0CAEV,QAAA;EAEA,YAAA,WAFA;EAIA,SAAA;EAEA,iBAAA;AAAA;;AAeF;;;;;;;;;;;KAAY,WAAA;EAcV,4GAZA,UAAA;EAmBA;;;;;;;;;;;EAPA,SAAA;EAyB4B;;AAgpC9B;;EApqCE,iBAAA,WAsrCQ;EAprCR,sBAAA,YA8qCkB;EA5qClB,mBAAA;;;;;;EAMA,kBAAA,GAAqB,OAAA,CAAQ,qBAAA;EAksClB;;;;;EA5rCX,IAAA,GAAO,IAAA,CAAK,UAAA,kBA4rCmC;EA1rC/C,OAAA,GAAU,MAAA,kBA2rC+B;EAzrCzC,SAAA,GAAY,gBAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;cAgpCD,aAAA;;;;;;;;;;;;;IAYO,KAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4BP,cAAA,GAAkB,OAAA,WAAkB,OAAA,GAAU,WAAA,KAAc,SAAA"}

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { InvocationError, isErrorBody } from "./errors.mjs";
+import { InvocationError, RegistrationRejectedError, isErrorBody } from "./errors.mjs";
 import { a as WS_HANDSHAKE_TIMEOUT_MS, n as DEFAULT_INVOCATION_TIMEOUT_MS, o as WS_IDLE_TIMEOUT_MS, r as EngineFunctions, s as WS_PING_INTERVAL_MS, t as DEFAULT_BRIDGE_RECONNECTION_CONFIG } from "./iii-constants-TIcoyiOl.mjs";
 import { i as ChannelWriter, r as ChannelReader } from "./channels-C4f7nfQr.mjs";
-import { t as MessageType } from "./iii-types-wPYrg7hX.mjs";
+import { t as MessageType } from "./iii-types-Btz-0RpP.mjs";
 import { r as isChannelRef, t as detectProjectName } from "./utils-8G4hHqvZ.mjs";
 import { createRequire } from "node:module";
 import { SpanKind, context, trace } from "@opentelemetry/api";
@@ -12,13 +12,62 @@ import { getMeter, getTracer } from "@iii-dev/helpers/observability/internal";
 
 //#region src/iii.ts
 const { version: SDK_VERSION } = createRequire(import.meta.url)("../package.json");
+/**
+* `registrationrejected` code (engine `protocol.rs`): another live worker
+* already holds this `(namespace, worker_name)`. The engine closes the
+* connection -- fatal.
+*/
+const WORKER_NAMESPACE_CONFLICT = "WORKER_NAMESPACE_CONFLICT";
+/**
+* `registrationrejected` code (engine `protocol.rs`): another live worker in
+* this namespace already exports this one function id. The connection stays
+* open -- non-fatal.
+*/
+const FUNCTION_NAMESPACE_CONFLICT = "FUNCTION_NAMESPACE_CONFLICT";
 function getOsInfo() {
 	return `${os.platform()} ${os.release()} (${os.arch()})`;
 }
-function getDefaultWorkerName() {
+function resolveWorkerName(explicitName) {
 	const managedName = process.env.III_WORKER_NAME;
 	if (managedName) return managedName;
-	return `${os.hostname()}:${process.pid}`;
+	return explicitName ?? `${os.hostname()}:${process.pid}`;
+}
+/**
+* Engine address used when neither an explicit address nor `III_URL` is set.
+* The IPv4 loopback is spelled out on purpose: `localhost` can resolve to `::1`
+* on a host whose engine only listens on IPv4.
+*/
+const DEFAULT_ENGINE_URL = "ws://127.0.0.1:49134";
+function resolveAddress(address) {
+	if (address) return address;
+	const fromEnv = process.env.III_URL;
+	if (fromEnv) return fromEnv;
+	return DEFAULT_ENGINE_URL;
+}
+/**
+* The namespace one call or one binding resolves in.
+*
+* `undefined` inherits the worker's. A blank one is refused: named and left
+* empty asks for the opposite of what absent asks for, and the two are only
+* ever confused by accident -- `??` forwards the empty string, Python's `or`
+* coerced it and Go dropped it, so one mistake produced three behaviours.
+*/
+function callNamespace(explicit, worker, source) {
+	if (explicit !== void 0 && explicit.trim() === "") throw new Error(`namespace is empty: ${source} was set to ${JSON.stringify(explicit)}. Give it a name, or leave it unset to stay in this worker's namespace.`);
+	return explicit ?? worker;
+}
+/** Resolve one function invocation without leaking engine builtins into a worker namespace. */
+function invocationNamespace(explicit, worker, functionId) {
+	const namespace = callNamespace(explicit, worker, "TriggerRequest.namespace");
+	return explicit === void 0 && functionId.startsWith("engine::") ? "default" : namespace;
+}
+function resolveNamespace(optionNamespace) {
+	if (optionNamespace !== void 0) {
+		if (optionNamespace.trim() === "") throw new Error(`namespace is empty: options.namespace was set to ${JSON.stringify(optionNamespace)}. Give it a name, or leave it unset to register in \`default\`.`);
+		return optionNamespace;
+	}
+	const managedNamespace = process.env.III_NAMESPACE;
+	if (managedNamespace) return managedNamespace;
 }
 var Sdk = class {
 	constructor(address, options) {
@@ -48,7 +97,8 @@ var Sdk = class {
 						type: triggerType.id,
 						function_id: functionId,
 						config,
-						metadata
+						metadata,
+						namespace: this.namespace
 					});
 				},
 				registerFunction: (functionId, handler, config, metadata) => {
@@ -57,7 +107,8 @@ var Sdk = class {
 						type: triggerType.id,
 						function_id: functionId,
 						config,
-						metadata
+						metadata,
+						namespace: this.namespace
 					});
 					return ref;
 				},
@@ -75,7 +126,11 @@ var Sdk = class {
 			const fullTrigger = {
 				...trigger,
 				id,
-				message_type: MessageType.RegisterTrigger
+				message_type: MessageType.RegisterTrigger,
+				...(() => {
+					const namespace = callNamespace(trigger.namespace, this.namespace, "RegisterTriggerInput.namespace");
+					return namespace !== void 0 ? { namespace } : {};
+				})()
 			};
 			this.sendMessage(MessageType.RegisterTrigger, fullTrigger, true);
 			this.triggers.set(id, fullTrigger);
@@ -184,6 +239,7 @@ var Sdk = class {
 		};
 		this.trigger = async (request) => {
 			const { function_id, payload, action, timeoutMs, metadata } = request;
+			const namespace = invocationNamespace(request.namespace, this.namespace, function_id);
 			const effectiveTimeout = timeoutMs ?? this.invocationTimeoutMs;
 			if (action?.type === "void") {
 				const traceparent = injectTraceparent();
@@ -194,7 +250,8 @@ var Sdk = class {
 					traceparent,
 					baggage,
 					action,
-					metadata
+					metadata,
+					...namespace !== void 0 ? { namespace } : {}
 				});
 				return;
 			}
@@ -231,7 +288,8 @@ var Sdk = class {
 					traceparent,
 					baggage,
 					action,
-					metadata
+					metadata,
+					...namespace !== void 0 ? { namespace } : {}
 				});
 			});
 		};
@@ -242,6 +300,9 @@ var Sdk = class {
 			this.registerFunction(`stream::list(${streamName})`, stream.list.bind(stream));
 			this.registerFunction(`stream::list_groups(${streamName})`, stream.listGroups.bind(stream));
 		};
+		this.getConnectionState = () => this.connectionState;
+		this.getAddress = () => this.address;
+		this.getFatalError = () => this.fatalError;
 		this.shutdown = async () => {
 			this.isShuttingDown = true;
 			this.stopMetricsReporting();
@@ -263,7 +324,8 @@ var Sdk = class {
 			}
 			this.setConnectionState("disconnected");
 		};
-		this.workerName = options?.workerName ?? getDefaultWorkerName();
+		this.workerName = resolveWorkerName(options?.workerName);
+		this.namespace = resolveNamespace(options?.namespace);
 		this.workerDescription = options?.workerDescription;
 		this.metricsReportingEnabled = options?.enableMetricsReporting ?? true;
 		this.invocationTimeoutMs = options?.invocationTimeoutMs ?? 3e4;
@@ -290,6 +352,7 @@ var Sdk = class {
 				os: getOsInfo(),
 				pid: process.pid,
 				isolation: process.env.III_ISOLATION || null,
+				...this.namespace !== void 0 ? { namespace: this.namespace } : {},
 				telemetry: {
 					language,
 					project_name: telemetryOpts?.project_name ?? detectProjectName(),
@@ -405,6 +468,7 @@ var Sdk = class {
 			previous_worker_id: this.workerId,
 			reattach_token: this.reattachToken
 		}));
+		this.registerWorkerMetadata();
 		this.triggerTypes.forEach(({ message }) => {
 			this.sendMessage(MessageType.RegisterTriggerType, message, true);
 		});
@@ -420,7 +484,6 @@ var Sdk = class {
 			if (message.type === MessageType.InvokeFunction && typeof message.invocation_id === "string" && !this.invocations.has(message.invocation_id)) continue;
 			this.sendMessageRaw(JSON.stringify(message));
 		}
-		this.registerWorkerMetadata();
 	}
 	isOpen() {
 		return this.ws?.readyState === WebSocket.OPEN;
@@ -479,6 +542,56 @@ var Sdk = class {
 		});
 		else console.error(`[iii] ${message}`, error ?? "");
 	}
+	logWarn(message) {
+		const otelLogger = getLogger();
+		if (otelLogger) otelLogger.emit({
+			severityNumber: SeverityNumber.WARN,
+			body: `[iii] ${message}`
+		});
+		else console.warn(`[iii] ${message}`);
+	}
+	/**
+	* Handle a `registrationrejected` from the engine. The `code` decides the
+	* severity:
+	*
+	* - {@link WORKER_NAMESPACE_CONFLICT}: another live worker already holds this
+	*   `(namespace, worker_name)`. The engine closes the connection, so this is
+	*   fatal -- stop the worker, do not reconnect, and surface a
+	*   {@link RegistrationRejectedError} to every pending invocation.
+	* - {@link FUNCTION_NAMESPACE_CONFLICT}: another live worker in this namespace
+	*   already exports this one function id. Only that registration is refused;
+	*   the engine keeps the connection open and the worker keeps serving its
+	*   other functions. Non-fatal -- log a warning and continue.
+	* - Any other code: treated as fatal (safe default).
+	*/
+	onRegistrationRejected(init) {
+		if (init.code === FUNCTION_NAMESPACE_CONFLICT) {
+			this.logWarn(`Function registration rejected: function "${init.function_id ?? "<unknown>"}" in namespace "${init.namespace}" is already exported by worker ${init.owner_worker_id}. The worker stays connected and keeps serving its other functions.`);
+			return;
+		}
+		const error = new RegistrationRejectedError(init);
+		this.fatalError = error;
+		if (init.code === WORKER_NAMESPACE_CONFLICT) this.logError("Registration rejected by engine", error);
+		else this.logError(`Registration rejected by engine with unknown code "${init.code}"; treating as fatal`, error);
+		this.isShuttingDown = true;
+		this.clearReconnectTimeout();
+		this.stopHeartbeat();
+		for (const [, invocation] of this.invocations) {
+			if (invocation.timeout) clearTimeout(invocation.timeout);
+			invocation.reject(error);
+		}
+		this.invocations.clear();
+		if (this.ws) {
+			this.ws.removeAllListeners();
+			this.ws.on("error", () => {});
+			try {
+				this.ws.terminate();
+			} catch {}
+			this.ws = void 0;
+		}
+		this.stopMetricsReporting();
+		this.setConnectionState("failed");
+	}
 	onInvocationResult(invocation_id, result, error) {
 		const invocation = this.invocations.get(invocation_id);
 		if (invocation) {
@@ -572,14 +685,15 @@ var Sdk = class {
 		}
 	}
 	async onRegisterTrigger(message) {
-		const { trigger_type, id, function_id, config, metadata } = message;
+		const { trigger_type, id, function_id, config, metadata, namespace } = message;
 		const triggerTypeData = this.triggerTypes.get(trigger_type);
 		if (triggerTypeData) try {
 			await triggerTypeData.handler.registerTrigger({
 				id,
 				function_id,
 				config,
-				metadata
+				metadata,
+				namespace
 			});
 			this.sendMessage(MessageType.TriggerRegistrationResult, {
 				id,
@@ -659,6 +773,15 @@ var Sdk = class {
 			this.reattachToken = reattach_token;
 			console.debug("[iii] Worker registered with ID:", worker_id);
 			this.startMetricsReporting();
+		} else if (msgType === MessageType.RegistrationRejected) {
+			const { code, namespace, worker_name, function_id, owner_worker_id } = message;
+			this.onRegistrationRejected({
+				code,
+				namespace,
+				worker_name,
+				function_id,
+				owner_worker_id
+			});
 		}
 	}
 };
@@ -695,7 +818,8 @@ const TriggerAction = {
 * Register the worker with a iii instance, returns a connected worker client.
 * The WebSocket connection is established automatically.
 *
-* @param address - WebSocket URL of the III engine (e.g. `ws://localhost:49134`).
+* @param address - WebSocket URL of the III engine. Omit to resolve it from
+*   `process.env.III_URL`, falling back to {@link DEFAULT_ENGINE_URL}.
 * @param options - Optional {@link InitOptions} for worker name, timeouts, reconnection, and OTel.
 * @returns A connected {@link IIIClient} instance.
 *
@@ -703,13 +827,15 @@ const TriggerAction = {
 * ```typescript
 * import { registerWorker } from 'iii-sdk'
 *
-* const worker = registerWorker(process.env.III_URL ?? 'ws://localhost:49134', {
-*   workerName: 'my-worker',
-* })
+* // Address from III_URL, set by whatever supervisor spawned this worker.
+* const worker = registerWorker()
+*
+* // Or explicitly, which always wins over the environment.
+* const other = registerWorker('ws://localhost:49134', { workerName: 'my-worker' })
 * ```
 */
-const registerWorker = (address, options) => new Sdk(address, options);
+const registerWorker = (address, options) => new Sdk(resolveAddress(address), options);
 
 //#endregion
-export { InvocationError, TriggerAction, registerWorker };
+export { DEFAULT_ENGINE_URL, InvocationError, RegistrationRejectedError, TriggerAction, registerWorker };
 //# sourceMappingURL=index.mjs.map