@uns-kit/core 3.0.36 → 3.0.37

package/MIGRATIONS.md

@@ -9,6 +9,61 @@ Agents must inspect the application's existing ownership and shutdown flow
 before editing it. The examples below describe the intended behavior, not a
 mechanical search-and-replace operation.
 
+## 3.0.37 - Application lifecycle, HTTP ownership and bounded RAM state
+
+When crossing `<3.0.37` to `>=3.0.37`, existing non-opt-in consumers retain their
+protocol. The API plugin now closes its HTTP server on shutdown and the cron
+plugin stops owned schedules. Review existing signal handlers so one owner calls
+`drainForMigration()` and reports an unsuccessful drain honestly.
+
+For stateful live migration, pass `uns.handoverProtocol` to `UnsProxyProcess`,
+set `deferHandoverUntilReady: true`, install every handler and participant, then
+call `enableMigrationDrain()`. API-only applications call
+`await runtime.prepareHandover(config.uns.instanceMode, config.uns.handover)`
+before that readiness declaration. Use `installSignalHandlers()` only when the
+application has no signal owner already. Declare `unsDatahub.mqttDrain` protocol1
+and `unsDatahub.mqttHandover` protocol2 only after this actual wiring is verified.
+
+Use the shared `ProcessWork` to track accepted asynchronous work. Stop timer and
+poller admission in `handoverShutdown.onRelease`; await `accepted.drain()` in
+`handoverShutdown.drain`. `handoverShutdown.onActivate` prepares application
+owners before successor input resumes. Do not discard already admitted input by
+checking `isActive()` in its callback. Do gate new background work. A failed or
+uncertain output stays latched and blocks a successful receipt.
+
+Applications with RAM state additionally supply `handoverState: { contract,
+exportState, validateState, importState }`. Use a stable semantic contract, check
+all fields before mutating anything, and include unfinished windows, active
+session IDs, original timestamps, conditions and counters. The shared transport
+bounds plain JSON to 768 KiB, depth32/50,000 nodes within its 1 MiB envelope.
+It refuses oversized state without truncation. Keep credentials and executable
+objects out of snapshots. Matching unchanged MQTT-only consumers retain format2;
+applications opting into new state require matching contracts on both peers.
+Do not bypass a refused comparison with a relabelled contract.
+
+Example:
+
+```ts
+const accepted = new ProcessWork();
+const runtime = new UnsProxyProcess(host, {
+  processName, handoverProtocol: config.uns.handoverProtocol,
+  deferHandoverUntilReady: true,
+  handoverShutdown: { onRelease: stopTimers, drain: () => accepted.drain() },
+  handoverState: {
+    contract: 'accumulator-v1', exportState: () => accumulator,
+    validateState: value => accumulatorSchema.parse(value),
+    importState: value => { accumulator = accumulatorSchema.parse(value); },
+  },
+});
+```
+
+The API plugin keeps passive routes unpublished, rejects passive requests with a
+retryable 503 and drains accepted requests. Cron work is gated by ownership.
+These mechanisms do not move disk queues or eliminate every routing gap. An
+unknown external effect remains uncertain; reconcile the original operation and
+use a reviewed reverse handover for return ownership. Ordinary SDK version
+alignment alone does not enable a live migration.
+
 ## 3.0.36 - Unitless state and passive background publishers
 
 When crossing `<3.0.36` to `>=3.0.36`, MQTT handover preserves absent units

package/dist/index.d.ts

@@ -17,4 +17,6 @@ export { registerService } from "./tools/datahub/runtime-service-registration.js
 export type { RegisterServiceOptions, RuntimeServiceDescriptor, RuntimeServiceRegistration, RuntimeServiceRegistrationClient, } from "./tools/datahub/runtime-service-registration.js";
 export { mqttPublishQueueSchema } from "./uns-mqtt/publish-queue-contract.js";
 export type { MqttPublishQueueOptions, MqttPublishQueueStatus } from "./uns-mqtt/publish-queue-contract.js";
+export { ProcessWork } from "./runtime/process-work.js";
+export { createApplicationHandoverContract, cloneApplicationHandoverState, type ApplicationHandoverState } from "./runtime/application-handover-state.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACzF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,gCAAgC,EAChC,wCAAwC,EACxC,wCAAwC,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAClF,YAAY,EACV,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EACV,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,GAC7B,MAAM,4BAA4B,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACzF,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAC3F,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AACzE,YAAY,EAAE,mBAAmB,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,YAAY,EACZ,sBAAsB,EACtB,yBAAyB,EACzB,qBAAqB,EACrB,gCAAgC,EAChC,wCAAwC,EACxC,wCAAwC,GACzC,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAClF,YAAY,EACV,sBAAsB,EACtB,wBAAwB,EACxB,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,iDAAiD,CAAC;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAE5G,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,iCAAiC,EAAE,6BAA6B,EAAE,KAAK,wBAAwB,EAAE,MAAM,yCAAyC,CAAC"}

package/dist/index.js

@@ -10,4 +10,6 @@ export { AuthClient, ServiceTokenProvider } from "./tools/auth/index.js";
 export { UnsClient, LastValueResult, ClientError, RangeResult, BatchRangeTopicResult, BatchRangeResponse, } from "./tools/datahub/datahub-client.js";
 export { registerService } from "./tools/datahub/runtime-service-registration.js";
 export { mqttPublishQueueSchema } from "./uns-mqtt/publish-queue-contract.js";
+export { ProcessWork } from "./runtime/process-work.js";
+export { createApplicationHandoverContract, cloneApplicationHandoverState } from "./runtime/application-handover-state.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAOxE,cAAc,yBAAyB,CAAC;AAExC,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC;AAgB3C,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAQlF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC","sourcesContent":["export { default as UnsProxyProcess } from \"./uns/uns-proxy-process.js\";\nexport type {\n  UnsProxyProcessPlugin,\n  UnsProxyProcessPluginApi,\n  UnsProxyProcessPluginMethod,\n  UnsProxyProcessPluginMethods,\n} from \"./uns/uns-proxy-process.js\";\nexport * from \"./uns/uns-interfaces.js\";\nexport type { HandoverShutdownHooks } from \"./uns/handover-shutdown.js\";\nexport * from \"./uns/service-metadata.js\";\nexport { ConfigFile } from \"./config-file.js\";\nexport { default as logger } from \"./logger.js\";\nexport { getLogger } from \"./logger.js\";\nexport { resolveInfisicalConfig } from \"./uns-config/secret-resolver.js\";\nexport { mqttChannelParameters, resolveMqttChannel } from \"./uns-config/mqtt-channel.js\";\nexport type { MqttChannelConfig, ResolvedMqttChannel } from \"./uns-config/mqtt-channel.js\";\nexport { AuthClient, ServiceTokenProvider } from \"./tools/auth/index.js\";\nexport type { AccessTokenProvider, ServiceTokenProviderOptions } from \"./tools/auth/index.js\";\nexport {\n  UnsClient,\n  LastValueResult,\n  ClientError,\n  RangeResult,\n  BatchRangeTopicResult,\n  BatchRangeResponse,\n} from \"./tools/datahub/datahub-client.js\";\nexport type {\n  LastValuePayload,\n  CatchAllTimeField,\n  CatchAllAggregate,\n  RangeQueryOptions,\n  RangeColumn,\n  RangeStats,\n  RangePayload,\n  BatchRangeTopicPayload,\n  BatchRangeResponsePayload,\n  ProviderAssetIdentity,\n  AssetIdentityPublicationMetadata,\n  AssetProviderIdentityPublicationMetadata,\n  AssetIdentityPublicationEvidenceMetadata,\n} from \"./tools/datahub/datahub-client.js\";\nexport { registerService } from \"./tools/datahub/runtime-service-registration.js\";\nexport type {\n  RegisterServiceOptions,\n  RuntimeServiceDescriptor,\n  RuntimeServiceRegistration,\n  RuntimeServiceRegistrationClient,\n} from \"./tools/datahub/runtime-service-registration.js\";\n\nexport { mqttPublishQueueSchema } from \"./uns-mqtt/publish-queue-contract.js\";\nexport type { MqttPublishQueueOptions, MqttPublishQueueStatus } from \"./uns-mqtt/publish-queue-contract.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAOxE,cAAc,yBAAyB,CAAC;AAExC,cAAc,2BAA2B,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,OAAO,IAAI,MAAM,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAEzF,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEzE,OAAO,EACL,SAAS,EACT,eAAe,EACf,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,mCAAmC,CAAC;AAgB3C,OAAO,EAAE,eAAe,EAAE,MAAM,iDAAiD,CAAC;AAQlF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAG9E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,iCAAiC,EAAE,6BAA6B,EAAiC,MAAM,yCAAyC,CAAC","sourcesContent":["export { default as UnsProxyProcess } from \"./uns/uns-proxy-process.js\";\nexport type {\n  UnsProxyProcessPlugin,\n  UnsProxyProcessPluginApi,\n  UnsProxyProcessPluginMethod,\n  UnsProxyProcessPluginMethods,\n} from \"./uns/uns-proxy-process.js\";\nexport * from \"./uns/uns-interfaces.js\";\nexport type { HandoverShutdownHooks } from \"./uns/handover-shutdown.js\";\nexport * from \"./uns/service-metadata.js\";\nexport { ConfigFile } from \"./config-file.js\";\nexport { default as logger } from \"./logger.js\";\nexport { getLogger } from \"./logger.js\";\nexport { resolveInfisicalConfig } from \"./uns-config/secret-resolver.js\";\nexport { mqttChannelParameters, resolveMqttChannel } from \"./uns-config/mqtt-channel.js\";\nexport type { MqttChannelConfig, ResolvedMqttChannel } from \"./uns-config/mqtt-channel.js\";\nexport { AuthClient, ServiceTokenProvider } from \"./tools/auth/index.js\";\nexport type { AccessTokenProvider, ServiceTokenProviderOptions } from \"./tools/auth/index.js\";\nexport {\n  UnsClient,\n  LastValueResult,\n  ClientError,\n  RangeResult,\n  BatchRangeTopicResult,\n  BatchRangeResponse,\n} from \"./tools/datahub/datahub-client.js\";\nexport type {\n  LastValuePayload,\n  CatchAllTimeField,\n  CatchAllAggregate,\n  RangeQueryOptions,\n  RangeColumn,\n  RangeStats,\n  RangePayload,\n  BatchRangeTopicPayload,\n  BatchRangeResponsePayload,\n  ProviderAssetIdentity,\n  AssetIdentityPublicationMetadata,\n  AssetProviderIdentityPublicationMetadata,\n  AssetIdentityPublicationEvidenceMetadata,\n} from \"./tools/datahub/datahub-client.js\";\nexport { registerService } from \"./tools/datahub/runtime-service-registration.js\";\nexport type {\n  RegisterServiceOptions,\n  RuntimeServiceDescriptor,\n  RuntimeServiceRegistration,\n  RuntimeServiceRegistrationClient,\n} from \"./tools/datahub/runtime-service-registration.js\";\n\nexport { mqttPublishQueueSchema } from \"./uns-mqtt/publish-queue-contract.js\";\nexport type { MqttPublishQueueOptions, MqttPublishQueueStatus } from \"./uns-mqtt/publish-queue-contract.js\";\n\nexport { ProcessWork } from \"./runtime/process-work.js\";\nexport { createApplicationHandoverContract, cloneApplicationHandoverState, type ApplicationHandoverState } from \"./runtime/application-handover-state.js\";\n"]}

package/dist/runtime/application-handover-state.d.ts

@@ -0,0 +1,13 @@
+/** Versioned application-owned RAM state; SDK owns bounds, peer binding and transport. */
+export interface ApplicationHandoverState {
+    contract: string;
+    exportState(): unknown;
+    validateState(value: unknown): void;
+    importState(value: unknown): void | Promise<void>;
+}
+export declare function validateApplicationHandoverContract(state?: ApplicationHandoverState): void;
+/** Plain bounded JSON only. No files, executable code, credentials or implicit truncation. */
+export declare function cloneApplicationHandoverState(value: unknown): unknown;
+/** Bind application-selected business resources without transmitting their contents. */
+export declare function createApplicationHandoverContract(revision: string, resources: unknown): string;
+//# sourceMappingURL=application-handover-state.d.ts.map

package/dist/runtime/application-handover-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-handover-state.d.ts","sourceRoot":"","sources":["../../src/runtime/application-handover-state.ts"],"names":[],"mappings":"AAEA,0FAA0F;AAC1F,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,IAAI,OAAO,CAAC;IACvB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAM1F;AAED,8FAA8F;AAC9F,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAiBrE;AAED,wFAAwF;AACxF,wBAAgB,iCAAiC,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,CAM9F"}

package/dist/runtime/application-handover-state.js

@@ -0,0 +1,43 @@
+import { createHash } from 'node:crypto';
+export function validateApplicationHandoverContract(state) {
+    if (!state)
+        return;
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,127}$/.test(state.contract) ||
+        [state.exportState, state.validateState, state.importState].some(fn => typeof fn !== "function")) {
+        throw new TypeError("Invalid application handover contract");
+    }
+}
+/** Plain bounded JSON only. No files, executable code, credentials or implicit truncation. */
+export function cloneApplicationHandoverState(value) {
+    let nodes = 0;
+    const visit = (item, depth) => {
+        if (++nodes > 50000 || depth > 32)
+            throw new Error("Application handover state exceeds structural bounds");
+        if (item === null || typeof item === "string" || typeof item === "boolean")
+            return;
+        if (typeof item === "number" && Number.isFinite(item))
+            return;
+        if (!item || typeof item !== "object" || (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype))
+            throw new TypeError("Application handover state must be plain JSON");
+        for (const [key, child] of Object.entries(item)) {
+            if (["__proto__", "constructor", "prototype"].includes(key))
+                throw new Error("Unsafe application state key");
+            visit(child, depth + 1);
+        }
+    };
+    visit(value, 0);
+    const json = JSON.stringify(value);
+    if (Buffer.byteLength(json) > 768 * 1024)
+        throw new Error("Application handover state exceeds byte bound");
+    return JSON.parse(json);
+}
+/** Bind application-selected business resources without transmitting their contents. */
+export function createApplicationHandoverContract(revision, resources) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,59}$/.test(revision))
+        throw Error("Invalid application state revision");
+    const normalized = cloneApplicationHandoverState(resources);
+    const stable = (value) => Array.isArray(value) ? value.map(stable)
+        : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;
+    return revision + '/' + createHash('sha256').update(JSON.stringify(stable(normalized))).digest('hex');
+}
+//# sourceMappingURL=application-handover-state.js.map

package/dist/runtime/application-handover-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-handover-state.js","sourceRoot":"","sources":["../../src/runtime/application-handover-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\n\n/** Versioned application-owned RAM state; SDK owns bounds, peer binding and transport. */\nexport interface ApplicationHandoverState {\n  contract: string;\n  exportState(): unknown;\n  validateState(value: unknown): void;\n  importState(value: unknown): void | Promise<void>;\n}\n\nexport function validateApplicationHandoverContract(state?: ApplicationHandoverState): void {\n  if (!state) return;\n  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,127}$/.test(state.contract) ||\n      [state.exportState, state.validateState, state.importState].some(fn => typeof fn !== \"function\")) {\n    throw new TypeError(\"Invalid application handover contract\");\n  }\n}\n\n/** Plain bounded JSON only. No files, executable code, credentials or implicit truncation. */\nexport function cloneApplicationHandoverState(value: unknown): unknown {\n  let nodes = 0;\n  const visit = (item: unknown, depth: number): void => {\n    if (++nodes > 50000 || depth > 32) throw new Error(\"Application handover state exceeds structural bounds\");\n    if (item === null || typeof item === \"string\" || typeof item === \"boolean\") return;\n    if (typeof item === \"number\" && Number.isFinite(item)) return;\n    if (!item || typeof item !== \"object\" || (!Array.isArray(item) && Object.getPrototypeOf(item) !== Object.prototype))\n      throw new TypeError(\"Application handover state must be plain JSON\");\n    for (const [key, child] of Object.entries(item)) {\n      if ([\"__proto__\", \"constructor\", \"prototype\"].includes(key)) throw new Error(\"Unsafe application state key\");\n      visit(child, depth + 1);\n    }\n  };\n  visit(value, 0);\n  const json = JSON.stringify(value);\n  if (Buffer.byteLength(json) > 768 * 1024) throw new Error(\"Application handover state exceeds byte bound\");\n  return JSON.parse(json);\n}\n\n/** Bind application-selected business resources without transmitting their contents. */\nexport function createApplicationHandoverContract(revision: string, resources: unknown): string {\n  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,59}$/.test(revision)) throw Error(\"Invalid application state revision\");\n  const normalized = cloneApplicationHandoverState(resources);\n  const stable = (value: any): any => Array.isArray(value) ? value.map(stable)\n    : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(key => [key, stable(value[key])])) : value;\n  return revision + '/' + createHash('sha256').update(JSON.stringify(stable(normalized))).digest('hex');\n}\n"]}

package/dist/runtime/mqtt-handover-state.d.ts

@@ -22,6 +22,10 @@ export declare const mqttProxyHandoverStateSchema: z.ZodObject<{
 }, z.core.$strict>;
 export declare const mqttHandoverStateSchema: z.ZodObject<{
     protocol: z.ZodLiteral<1>;
+    application: z.ZodOptional<z.ZodObject<{
+        contract: z.ZodString;
+        data: z.ZodUnknown;
+    }, z.core.$strict>>;
     proxies: z.ZodArray<z.ZodObject<{
         instanceName: z.ZodString;
         compatibility: z.ZodString;

package/dist/runtime/mqtt-handover-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mqtt-handover-state.d.ts","sourceRoot":"","sources":["../../src/runtime/mqtt-handover-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAIzD,eAAO,MAAM,uBAAuB;;;mBAG8E,CAAC;AACnH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;kBASvC,CAAC;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;kBAMlC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAIxE;AACD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAExE;AACD,eAAO,MAAM,4BAA4B;;kBAAoD,CAAC;AAC9F,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAS7E"}
+{"version":3,"file":"mqtt-handover-state.d.ts","sourceRoot":"","sources":["../../src/runtime/mqtt-handover-state.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAIzD,eAAO,MAAM,uBAAuB;;;mBAG8E,CAAC;AACnH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;kBASvC,CAAC;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;kBAOlC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AACxE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAMxE;AACD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAExE;AACD,eAAO,MAAM,4BAA4B;;kBAAoD,CAAC;AAC9F,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAS7E"}

package/dist/runtime/mqtt-handover-state.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
+import { cloneApplicationHandoverState } from './application-handover-state.js';
 // Same contract for every SDK MQTT consumer. No application/profile selectors.
 // Bound into peer compatibility so older required-unit readers reject before freeze.
 export const MQTT_HANDOVER_STATE_FORMAT = 2;
@@ -26,6 +27,7 @@ export const mqttProxyHandoverStateSchema = z.strictObject({
 });
 export const mqttHandoverStateSchema = z.strictObject({
     protocol: z.literal(1),
+    application: z.strictObject({ contract: z.string().min(1).max(128), data: z.unknown() }).optional(),
     proxies: z.array(mqttProxyHandoverStateSchema).max(64),
 }).superRefine((state, ctx) => {
     if (new Set(state.proxies.map(p => p.instanceName)).size !== state.proxies.length)
@@ -35,7 +37,10 @@ export function parseMqttHandoverState(input) {
     const json = JSON.stringify(input);
     if (!json || Buffer.byteLength(json) > MQTT_HANDOVER_STATE_MAX_BYTES)
         throw Error('MQTT handover state exceeds its bound');
-    return mqttHandoverStateSchema.parse(input);
+    const state = mqttHandoverStateSchema.parse(input);
+    if (state.application)
+        state.application.data = cloneApplicationHandoverState(state.application.data);
+    return state;
 }
 export function mqttHandoverStateDigest(state) {
     return createHash('sha256').update(JSON.stringify(parseMqttHandoverState(state))).digest('hex');

package/dist/runtime/mqtt-handover-state.js.map

@@ -1 +1 @@
-{"version":3,"file":"mqtt-handover-state.js","sourceRoot":"","sources":["../../src/runtime/mqtt-handover-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { z } from 'zod';\n\n// Same contract for every SDK MQTT consumer. No application/profile selectors.\n// Bound into peer compatibility so older required-unit readers reject before freeze.\nexport const MQTT_HANDOVER_STATE_FORMAT = 2;\nexport const MQTT_HANDOVER_STATE_MAX_BYTES = 1024 * 1024;\nconst text = z.string().min(1).max(65535).refine(v => !v.includes('\\0'));\nconst scalar = z.union([z.number().finite(), z.string().max(65535)]);\nconst value = z.union([scalar, z.array(scalar).max(4096)]);\nexport const mqttHandoverOfferSchema = z.array(z.strictObject({\n  instanceName: z.string().min(1).max(256),\n  compatibility: z.string().regex(/^[a-f0-9]{64}$/),\n})).max(64).refine(offer => new Set(offer.map(p => p.instanceName)).size === offer.length, 'Duplicate MQTT proxy');\nexport const mqttProxyHandoverStateSchema = z.strictObject({\n  instanceName: z.string().min(1).max(256),\n  compatibility: z.string().regex(/^[a-f0-9]{64}$/),\n  values: z.array(z.strictObject({ topic: text, value, uom: z.string().max(256).optional(), timestamp: z.string().datetime() })).max(10000),\n  sequences: z.array(z.tuple([text, z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)])).max(10000),\n  cursor: z.strictObject({ batchSize: z.number().int().min(0).max(100), referenceHash: z.string().regex(/^[a-f0-9]{64}$/) }),\n}).superRefine((state, ctx) => {\n  for (const keys of [state.values.map(v => v.topic), state.sequences.map(v => v[0])])\n    if (new Set(keys).size !== keys.length) ctx.addIssue({ code: 'custom', message: 'Duplicate MQTT state key' });\n});\nexport const mqttHandoverStateSchema = z.strictObject({\n  protocol: z.literal(1),\n  proxies: z.array(mqttProxyHandoverStateSchema).max(64),\n}).superRefine((state, ctx) => {\n  if (new Set(state.proxies.map(p => p.instanceName)).size !== state.proxies.length)\n    ctx.addIssue({ code: 'custom', message: 'Duplicate MQTT proxy' });\n});\nexport type MqttProxyHandoverState = z.infer<typeof mqttProxyHandoverStateSchema>;\nexport type MqttHandoverState = z.infer<typeof mqttHandoverStateSchema>;\nexport function parseMqttHandoverState(input: unknown): MqttHandoverState {\n  const json = JSON.stringify(input);\n  if (!json || Buffer.byteLength(json) > MQTT_HANDOVER_STATE_MAX_BYTES) throw Error('MQTT handover state exceeds its bound');\n  return mqttHandoverStateSchema.parse(input);\n}\nexport function mqttHandoverStateDigest(state: MqttHandoverState): string {\n  return createHash('sha256').update(JSON.stringify(parseMqttHandoverState(state))).digest('hex');\n}\nexport const mqttHandoverCapabilitySchema = z.strictObject({ protocolVersion: z.literal(2) });\nexport function readMqttHandoverCapability(packageRoot: string): 2 | undefined {\n  const file = path.join(packageRoot, 'package.json');\n  let stat: fs.Stats;\n  try { stat = fs.lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; throw error; }\n  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1048576) throw Error('Unsafe MQTT handover descriptor');\n  const descriptor = JSON.parse(fs.readFileSync(file, 'utf8'))?.unsDatahub?.mqttHandover;\n  if (descriptor === undefined) return undefined;\n  mqttHandoverCapabilitySchema.parse(descriptor);\n  return 2;\n}\n"]}
+{"version":3,"file":"mqtt-handover-state.js","sourceRoot":"","sources":["../../src/runtime/mqtt-handover-state.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport fs from 'node:fs';\nimport path from 'node:path';\nimport { z } from 'zod';\nimport { cloneApplicationHandoverState } from './application-handover-state.js';\n\n// Same contract for every SDK MQTT consumer. No application/profile selectors.\n// Bound into peer compatibility so older required-unit readers reject before freeze.\nexport const MQTT_HANDOVER_STATE_FORMAT = 2;\nexport const MQTT_HANDOVER_STATE_MAX_BYTES = 1024 * 1024;\nconst text = z.string().min(1).max(65535).refine(v => !v.includes('\\0'));\nconst scalar = z.union([z.number().finite(), z.string().max(65535)]);\nconst value = z.union([scalar, z.array(scalar).max(4096)]);\nexport const mqttHandoverOfferSchema = z.array(z.strictObject({\n  instanceName: z.string().min(1).max(256),\n  compatibility: z.string().regex(/^[a-f0-9]{64}$/),\n})).max(64).refine(offer => new Set(offer.map(p => p.instanceName)).size === offer.length, 'Duplicate MQTT proxy');\nexport const mqttProxyHandoverStateSchema = z.strictObject({\n  instanceName: z.string().min(1).max(256),\n  compatibility: z.string().regex(/^[a-f0-9]{64}$/),\n  values: z.array(z.strictObject({ topic: text, value, uom: z.string().max(256).optional(), timestamp: z.string().datetime() })).max(10000),\n  sequences: z.array(z.tuple([text, z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)])).max(10000),\n  cursor: z.strictObject({ batchSize: z.number().int().min(0).max(100), referenceHash: z.string().regex(/^[a-f0-9]{64}$/) }),\n}).superRefine((state, ctx) => {\n  for (const keys of [state.values.map(v => v.topic), state.sequences.map(v => v[0])])\n    if (new Set(keys).size !== keys.length) ctx.addIssue({ code: 'custom', message: 'Duplicate MQTT state key' });\n});\nexport const mqttHandoverStateSchema = z.strictObject({\n  protocol: z.literal(1),\n  application: z.strictObject({ contract: z.string().min(1).max(128), data: z.unknown() }).optional(),\n  proxies: z.array(mqttProxyHandoverStateSchema).max(64),\n}).superRefine((state, ctx) => {\n  if (new Set(state.proxies.map(p => p.instanceName)).size !== state.proxies.length)\n    ctx.addIssue({ code: 'custom', message: 'Duplicate MQTT proxy' });\n});\nexport type MqttProxyHandoverState = z.infer<typeof mqttProxyHandoverStateSchema>;\nexport type MqttHandoverState = z.infer<typeof mqttHandoverStateSchema>;\nexport function parseMqttHandoverState(input: unknown): MqttHandoverState {\n  const json = JSON.stringify(input);\n  if (!json || Buffer.byteLength(json) > MQTT_HANDOVER_STATE_MAX_BYTES) throw Error('MQTT handover state exceeds its bound');\n  const state = mqttHandoverStateSchema.parse(input);\n  if (state.application) state.application.data = cloneApplicationHandoverState(state.application.data);\n  return state;\n}\nexport function mqttHandoverStateDigest(state: MqttHandoverState): string {\n  return createHash('sha256').update(JSON.stringify(parseMqttHandoverState(state))).digest('hex');\n}\nexport const mqttHandoverCapabilitySchema = z.strictObject({ protocolVersion: z.literal(2) });\nexport function readMqttHandoverCapability(packageRoot: string): 2 | undefined {\n  const file = path.join(packageRoot, 'package.json');\n  let stat: fs.Stats;\n  try { stat = fs.lstatSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; throw error; }\n  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1048576) throw Error('Unsafe MQTT handover descriptor');\n  const descriptor = JSON.parse(fs.readFileSync(file, 'utf8'))?.unsDatahub?.mqttHandover;\n  if (descriptor === undefined) return undefined;\n  mqttHandoverCapabilitySchema.parse(descriptor);\n  return 2;\n}\n"]}

package/dist/runtime/process-work.d.ts

@@ -0,0 +1,16 @@
+/** Accepted application work is separate from transport queues. Errors stay latched. */
+export declare class ProcessWork {
+    private readonly active;
+    private pending;
+    private failed;
+    private paused;
+    constructor(active?: () => boolean);
+    /** Track work already admitted by a transport. Never drop it during release. */
+    track<T>(work: Promise<T>): Promise<T>;
+    /** Timers/pollers must enter through this ownership gate. */
+    run<T>(work: () => Promise<T>): Promise<T | undefined>;
+    pause(): void;
+    fail(): void;
+    drain(): Promise<void>;
+}
+//# sourceMappingURL=process-work.d.ts.map

package/dist/runtime/process-work.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-work.d.ts","sourceRoot":"","sources":["../../src/runtime/process-work.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,qBAAa,WAAW;IAKV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,MAAM,CAAS;gBAEM,MAAM,GAAE,MAAM,OAAoB;IAE/D,gFAAgF;IAChF,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAStC,6DAA6D;IAC7D,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAKtD,KAAK,IAAI,IAAI;IACb,IAAI,IAAI,IAAI;IACN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/runtime/process-work.js

@@ -0,0 +1,34 @@
+/** Accepted application work is separate from transport queues. Errors stay latched. */
+export class ProcessWork {
+    active;
+    pending = new Set();
+    failed = false;
+    paused = false;
+    constructor(active = () => true) {
+        this.active = active;
+    }
+    /** Track work already admitted by a transport. Never drop it during release. */
+    track(work) {
+        this.pending.add(work);
+        void work.then(() => this.pending.delete(work), () => {
+            this.failed = true;
+            this.pending.delete(work);
+        });
+        return work;
+    }
+    /** Timers/pollers must enter through this ownership gate. */
+    run(work) {
+        if (this.paused || !this.active())
+            return Promise.resolve(undefined);
+        return this.track(Promise.resolve().then(work));
+    }
+    pause() { this.paused = true; }
+    fail() { this.failed = true; }
+    async drain() {
+        while (this.pending.size)
+            await Promise.allSettled([...this.pending]);
+        if (this.failed)
+            throw new Error("Accepted application work is unconfirmed");
+    }
+}
+//# sourceMappingURL=process-work.js.map

package/dist/runtime/process-work.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-work.js","sourceRoot":"","sources":["../../src/runtime/process-work.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,MAAM,OAAO,WAAW;IAKO;IAJrB,OAAO,GAAG,IAAI,GAAG,EAAoB,CAAC;IACtC,MAAM,GAAG,KAAK,CAAC;IACf,MAAM,GAAG,KAAK,CAAC;IAEvB,YAA6B,SAAwB,GAAG,EAAE,CAAC,IAAI;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,gFAAgF;IAChF,KAAK,CAAI,IAAgB;QACvB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvB,KAAK,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE;YACnD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IACd,CAAC;IAED,6DAA6D;IAC7D,GAAG,CAAI,IAAsB;QAC3B,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,KAAW,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACrC,IAAI,KAAW,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IACpC,KAAK,CAAC,KAAK;QACT,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QACtE,IAAI,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC/E,CAAC;CACF","sourcesContent":["/** Accepted application work is separate from transport queues. Errors stay latched. */\nexport class ProcessWork {\n  private pending = new Set<Promise<unknown>>();\n  private failed = false;\n  private paused = false;\n\n  constructor(private readonly active: () => boolean = () => true) {}\n\n  /** Track work already admitted by a transport. Never drop it during release. */\n  track<T>(work: Promise<T>): Promise<T> {\n    this.pending.add(work);\n    void work.then(() => this.pending.delete(work), () => {\n      this.failed = true;\n      this.pending.delete(work);\n    });\n    return work;\n  }\n\n  /** Timers/pollers must enter through this ownership gate. */\n  run<T>(work: () => Promise<T>): Promise<T | undefined> {\n    if (this.paused || !this.active()) return Promise.resolve(undefined);\n    return this.track(Promise.resolve().then(work));\n  }\n\n  pause(): void { this.paused = true; }\n  fail(): void { this.failed = true; }\n  async drain(): Promise<void> {\n    while (this.pending.size) await Promise.allSettled([...this.pending]);\n    if (this.failed) throw new Error(\"Accepted application work is unconfirmed\");\n  }\n}\n"]}

package/dist/uns/handover-manager.d.ts

@@ -1,3 +1,4 @@
+import { type ApplicationHandoverState } from "../runtime/application-handover-state.js";
 import { type HandoverShutdownHooks } from "./handover-shutdown.js";
 import { HandoverManagerEvents } from "../uns-mqtt/mqtt-interfaces.js";
 import MqttProxy from "../uns-mqtt/mqtt-proxy.js";
@@ -11,6 +12,7 @@ import { UnsEvents } from "./uns-interfaces.js";
  */
 export declare class HandoverManager {
     private readonly statefulHandover;
+    private readonly applicationState?;
     event: HandoverManagerEventEmitter<HandoverManagerEvents>;
     private processName;
     private processId;
@@ -36,7 +38,7 @@ export declare class HandoverManager {
     handoverRequestEnabled: boolean;
     handoverEnabled: boolean;
     forceStartEnabled: boolean;
-    constructor(processName: string, processId: string, mqttProxy: MqttProxy, unsMqttProxies: UnsMqttProxy[], handoverRequestEnabled: boolean, handoverEnabled: boolean, forceStartEnabled: boolean, handoverId?: string, shutdownHooks?: HandoverShutdownHooks, statefulHandover?: boolean);
+    constructor(processName: string, processId: string, mqttProxy: MqttProxy, unsMqttProxies: UnsMqttProxy[], handoverRequestEnabled: boolean, handoverEnabled: boolean, forceStartEnabled: boolean, handoverId?: string, shutdownHooks?: HandoverShutdownHooks, statefulHandover?: boolean, applicationState?: ApplicationHandoverState);
     private getUserProperties;
     private handoverPayload;
     private getHandoverId;
@@ -56,6 +58,8 @@ export declare class HandoverManager {
     private prepareSourceHandover;
     private sendPreparedState;
     private acceptPreparedState;
+    private activateApplication;
+    private deactivateApplication;
     private finishSourceHandover;
     private handleHandover;
 }

package/dist/uns/handover-manager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handover-manager.d.ts","sourceRoot":"","sources":["../../src/uns/handover-manager.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiD,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,SAAS,MAAM,2BAA2B,CAAC;AAElD,OAAO,YAAY,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAElF,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAQhD;;;;GAIG;AACH,qBAAa,eAAe;IAqCxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IApC5B,KAAK,EAAE,2BAA2B,CAAC,qBAAqB,CAAC,CAA4D;IAC5H,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAA6B;IACtC,sBAAsB,EAAE,OAAO,CAAS;IACxC,eAAe,EAAE,OAAO,CAAQ;IAChC,iBAAiB,EAAE,OAAO,CAAS;gBAGxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,YAAY,EAAE,EAC9B,sBAAsB,EAAE,OAAO,EAC/B,eAAe,EAAE,OAAO,EACxB,iBAAiB,EAAE,OAAO,EAC1B,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,qBAAqB,EACpB,gBAAgB,UAAQ;IAkC3C,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,oBAAoB;IAU5B;;;OAGG;IACU,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAqFxE;;OAEG;IACH,OAAO,CAAC,UAAU;YAIJ,qBAAqB;YA8ErB,iBAAiB;YAOjB,mBAAmB;YAkBnB,oBAAoB;YA2BpB,cAAc;CAwH7B"}
+{"version":3,"file":"handover-manager.d.ts","sourceRoot":"","sources":["../../src/uns/handover-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAGxH,OAAO,EAAiD,KAAK,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnH,OAAO,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,SAAS,MAAM,2BAA2B,CAAC;AAElD,OAAO,YAAY,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,2BAA2B,EAAE,MAAM,qCAAqC,CAAC;AAElF,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAQhD;;;;GAIG;AACH,qBAAa,eAAe;IAqCxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IArC7B,KAAK,EAAE,2BAA2B,CAAC,qBAAqB,CAAC,CAA4D;IAC5H,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,SAAS,CAAY;IAC7B,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,kBAAkB,CAAkB;IAC5C,OAAO,CAAC,YAAY,CAAmB;IACvC,OAAO,CAAC,aAAa,CAA6B;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,kBAAkB,CAAqB;IAC/C,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAoC;IAClE,OAAO,CAAC,gBAAgB,CAAqB;IAC7C,OAAO,CAAC,aAAa,CAAgC;IACrD,OAAO,CAAC,WAAW,CAAqB;IACxC,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,iBAAiB,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAA6B;IACtC,sBAAsB,EAAE,OAAO,CAAS;IACxC,eAAe,EAAE,OAAO,CAAQ;IAChC,iBAAiB,EAAE,OAAO,CAAS;gBAGxC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,YAAY,EAAE,EAC9B,sBAAsB,EAAE,OAAO,EAC/B,eAAe,EAAE,OAAO,EACxB,iBAAiB,EAAE,OAAO,EAC1B,UAAU,CAAC,EAAE,MAAM,EACnB,aAAa,CAAC,EAAE,qBAAqB,EACpB,gBAAgB,UAAQ,EACxB,gBAAgB,CAAC,EAAE,wBAAwB;IAkC9D,OAAO,CAAC,iBAAiB;IAUzB,OAAO,CAAC,eAAe;IAcvB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,uBAAuB;IAW/B,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,oBAAoB;IAU5B;;;OAGG;IACU,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAoFxE;;OAEG;IACH,OAAO,CAAC,UAAU;YAIJ,qBAAqB;YAiFrB,iBAAiB;YAOjB,mBAAmB;YA2BnB,mBAAmB;YAQnB,qBAAqB;YAWrB,oBAAoB;YA2BpB,cAAc;CA6H7B"}

package/dist/uns/handover-manager.js

@@ -1,3 +1,4 @@
+import { cloneApplicationHandoverState } from "../runtime/application-handover-state.js";
 import { mqttHandoverOfferSchema, parseMqttHandoverState, mqttHandoverStateDigest } from "../runtime/mqtt-handover-state.js";
 import logger from "../logger.js";
 import { runHandoverShutdown, validateHandoverShutdown } from "./handover-shutdown.js";
@@ -17,6 +18,7 @@ function normalizeHandoverId(value) {
  */
 export class HandoverManager {
     statefulHandover;
+    applicationState;
     event = new HandoverManagerEventEmitter();
     processName;
     processId;
@@ -42,8 +44,9 @@ export class HandoverManager {
     handoverRequestEnabled = false;
     handoverEnabled = true;
     forceStartEnabled = false;
-    constructor(processName, processId, mqttProxy, unsMqttProxies, handoverRequestEnabled, handoverEnabled, forceStartEnabled, handoverId, shutdownHooks, statefulHandover = false) {
+    constructor(processName, processId, mqttProxy, unsMqttProxies, handoverRequestEnabled, handoverEnabled, forceStartEnabled, handoverId, shutdownHooks, statefulHandover = false, applicationState) {
         this.statefulHandover = statefulHandover;
+        this.applicationState = applicationState;
         validateHandoverShutdown(shutdownHooks);
         this.shutdownHooks = shutdownHooks ? { ...shutdownHooks } : undefined;
         this.processName = processName;
@@ -59,17 +62,23 @@ export class HandoverManager {
         const version = PACKAGE_INFO.version;
         this.topicBuilder = new MqttTopicBuilder(`uns-infra/${MqttTopicBuilder.sanitizeTopicPart(packageName)}/${MqttTopicBuilder.sanitizeTopicPart(version)}/${MqttTopicBuilder.sanitizeTopicPart(this.processName)}/`);
         // Set status as active after a timeout if no other active process are detected.
-        this.activeTimeout = setTimeout(() => {
+        this.activeTimeout = setTimeout(async () => {
             if (this.statefulHandover && this.handoverId)
                 return; // A reviewed successor never self-promotes.
             logger.info(`${this.processName} - No active message received within timeout. Assuming no other process is running.`);
+            for (const proxy of this.unsMqttProxies)
+                proxy.setPublisherActive();
+            try {
+                await this.activateApplication();
+            }
+            catch {
+                logger.error("Runtime activation failed; successor remains passive");
+                return;
+            }
             this.active = true;
             this.event.emit("handoverManager", { active: this.active });
-            // Activate all UNS proxy instance publishers and subscribers.
-            this.unsMqttProxies.forEach((unsProxy) => {
-                unsProxy.setPublisherActive();
-                unsProxy.setSubscriberActive();
-            });
+            // Publishers were prepared for application activation; input opens last.
+            this.unsMqttProxies.forEach((unsProxy) => unsProxy.setSubscriberActive());
         }, ACTIVE_TIMEOUT);
     }
     getUserProperties(handoverId) {
@@ -185,7 +194,7 @@ export class HandoverManager {
                     setTimeout(async () => {
                         logger.info(`${this.processName} - Requesting handover ${eventHandoverTopic}.`);
                         this.handoverInProgress = true;
-                        await this.mqttProxy.publish(eventHandoverTopic, this.handoverPayload("handover_request", undefined, this.statefulHandover ? { offer: this.unsMqttProxies.map(proxy => proxy.getHandoverCompatibility()) } : {}), {
+                        await this.mqttProxy.publish(eventHandoverTopic, this.handoverPayload("handover_request", undefined, this.statefulHandover ? { offer: this.unsMqttProxies.map(proxy => proxy.getHandoverCompatibility()), applicationContract: this.applicationState?.contract } : {}), {
                             retain: false,
                             properties: {
                                 responseTopic: this.topicBuilder.getHandoverTopic(),
@@ -201,13 +210,13 @@ export class HandoverManager {
                         logger.warn(`${this.processName} - Warning: Source and destination being the same may lead to duplicate messages.`);
                         clearTimeout(this.activeTimeout); // Clear the active timeout if it exists - prevent this process from becoming active after a timeout.
                         this.activeTimeout = undefined;
+                        for (const proxy of this.unsMqttProxies)
+                            proxy.setPublisherActive();
+                        await this.activateApplication();
                         this.active = true;
                         this.event.emit("handoverManager", { active: this.active });
                         // Activate all UNS proxy instance publishers and subscribers.
-                        this.unsMqttProxies.forEach((unsProxy) => {
-                            unsProxy.setPublisherActive();
-                            unsProxy.setSubscriberActive();
-                        });
+                        this.unsMqttProxies.forEach((unsProxy) => unsProxy.setSubscriberActive());
                     }
                     else {
                         logger.info(`${this.processName} - Waiting for the other process on topic ${event.topic} to become passive.`);
@@ -252,7 +261,11 @@ export class HandoverManager {
             await this.shutdownHooks?.drain();
             for (const proxy of this.unsMqttProxies)
                 await proxy.flush();
-            this.preparedState = parseMqttHandoverState({ protocol: 1, proxies: this.unsMqttProxies.map((proxy, i) => proxy.exportHandoverState({ batchSize: mqttWorkerData[i].batchSize, referenceHash: mqttWorkerData[i].referenceHash })) });
+            const application = this.applicationState ? { contract: this.applicationState.contract,
+                data: cloneApplicationHandoverState(this.applicationState.exportState()) } : undefined;
+            if (application)
+                this.applicationState.validateState(application.data);
+            this.preparedState = parseMqttHandoverState({ protocol: 1, ...(application ? { application } : {}), proxies: this.unsMqttProxies.map((proxy, i) => proxy.exportHandoverState({ batchSize: mqttWorkerData[i].batchSize, referenceHash: mqttWorkerData[i].referenceHash })) });
             this.stateDigest = mqttHandoverStateDigest(this.preparedState);
             await this.sendPreparedState(event, handoverId);
             let retries = 0;
@@ -308,6 +321,10 @@ export class HandoverManager {
         const digest = mqttHandoverStateDigest(state);
         if (digest !== response.stateDigest)
             throw Error("MQTT handover state digest mismatch");
+        if (state.application?.contract !== this.applicationState?.contract)
+            throw Error("Application handover contract differs");
+        if (state.application)
+            this.applicationState.validateState(state.application.data);
         const byName = new Map(this.unsMqttProxies.map(proxy => [proxy.instanceName, proxy]));
         if (byName.size !== this.unsMqttProxies.length || state.proxies.length !== byName.size || state.proxies.some(p => !byName.has(p.instanceName)))
             throw Error("MQTT handover proxy set differs");
@@ -318,14 +335,45 @@ export class HandoverManager {
             await byName.get(snapshot.instanceName).prepareHandoverResume(snapshot.cursor);
         for (const snapshot of state.proxies)
             byName.get(snapshot.instanceName).importHandoverState(snapshot);
+        if (state.application)
+            await this.applicationState.importState(state.application.data);
         for (const proxy of this.unsMqttProxies)
             proxy.setPublisherActive();
-        for (const proxy of this.unsMqttProxies)
-            await proxy.activateHandoverResume();
+        await this.activateApplication();
+        try {
+            for (const proxy of this.unsMqttProxies)
+                await proxy.activateHandoverResume();
+        }
+        catch {
+            await this.deactivateApplication();
+            throw Error("MQTT input activation failed; successor remains passive");
+        }
         this.acceptedStateDigest = digest;
         this.active = true;
         this.event.emit("handoverManager", { active: true });
     }
+    async activateApplication() {
+        try {
+            await this.shutdownHooks?.onActivate?.();
+        }
+        catch {
+            await this.deactivateApplication();
+            throw Error("Application activation failed; successor remains passive");
+        }
+    }
+    async deactivateApplication() {
+        this.active = false;
+        try {
+            this.shutdownHooks?.onRelease?.();
+        }
+        catch { /* Keep admission closed if cleanup itself fails. */ }
+        // A failed worker may not acknowledge the stop. Request passive input on
+        // every peer, close outputs, and never acknowledge ownership as successful.
+        for (const proxy of this.unsMqttProxies) {
+            void Promise.resolve().then(() => proxy.setSubscriberPassive(true)).catch(() => { });
+        }
+        await Promise.allSettled(this.unsMqttProxies.map(proxy => Promise.resolve().then(() => proxy.setPublisherPassive())));
+    }
     async finishSourceHandover() {
         const result = await runHandoverShutdown(async () => {
             await this.sourcePreparation;
@@ -376,6 +424,12 @@ export class HandoverManager {
                     return;
                 if (this.statefulHandover) {
                     // Reject incompatible upgrades before freezing the current owner.
+                    if (response.applicationContract !== this.applicationState?.contract)
+                        throw Error("Application handover contract differs; source remains active");
+                    if (this.applicationState) {
+                        const preliminary = cloneApplicationHandoverState(this.applicationState.exportState());
+                        this.applicationState.validateState(preliminary);
+                    }
                     const offer = mqttHandoverOfferSchema.parse(response.offer);
                     const own = this.unsMqttProxies.map(proxy => proxy.getHandoverCompatibility());
                     if (offer.length !== own.length || own.some(p => !offer.some(o => o.instanceName === p.instanceName && o.compatibility === p.compatibility)))