@uns-kit/core 3.0.36 → 3.0.38

package/MIGRATIONS.md

@@ -9,6 +9,82 @@ 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.38 - Bounded late-subscriber input boundary (format3)
+
+When crossing `<3.0.38` to `>=3.0.38`, non-opt-in applications keep their existing
+protocol. For opt-in correlated-v2 MQTT handover, both peers must use the new
+format3 implementation. Format is bound
+into the compatibility digest: a mixed old/new pair refuses while the source
+remains active. Review an initial stop-before-start upgrade, then use matching
+peers for live moves. Never relabel a business contract to bypass this check.
+
+No application-specific migration hooks are introduced. Keep existing
+`deferHandoverUntilReady`, semantic contracts and accepted-work/drain ownership.
+The SDK checks fresh broker subscription acknowledgements and uniquely shared
+ordered input before release, including sparse sources whose target missed old
+packets. Without proof the source stays active and the target remains passive.
+Only read-only preparation can repeat after delayed input; unknown import or
+activation effects remain blocked. Equal values are not deduplicated.
+
+This does not move persistent queues or guarantee replay of broker losses.
+Use a reviewed reverse hot move for return ownership and retain existing fences.
+See [protocol, example and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/mqtt-stateful-handover.md#sparse-input-and-late-subscribers-3038).
+
+## 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/README.md

@@ -273,6 +273,17 @@ and apply only the migrations whose version boundaries are crossed. The
 `3.0.0` migration documents the MQTT table-column object contract, while the
 `2.0.71` migration documents MQTT publish and shutdown ownership changes.
 
+## State-preserving MQTT handover
+
+Correlated-v2 MQTT handover in3.0.38 verifies a uniquely shared input boundary
+before releasing the source, including a late subscriber that missed older
+packets. Both peers need format3; mixed old/new formats refuse before freeze.
+Retain semantic contracts, accepted-work drain and restart fences. Missing or
+ambiguous overlap and unknown activation results stay blocked.
+See the [protocol, example and limits](https://github.com/uns-openhub/uns-kit/blob/master/docs/mqtt-stateful-handover.md)
+and the version-bounded3.0.38 entry in `MIGRATIONS.md`. This does not transfer
+persistent queues or promise replay of broker losses.
+
 ## Optional configuration-owned process groups
 
 Version3.0.29 adds optional shared contracts for immutable application-owned JSON

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/input-queue-boundary.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const inputPreviewSchema: z.ZodArray<z.ZodString>;
+export declare const inputCursorSchema: z.ZodObject<{
+    batchSize: z.ZodNumber;
+    referenceHash: z.ZodString;
+    processedTail: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type InputQueueCursor = z.infer<typeof inputCursorSchema>;
+export declare function inputFingerprint(item: {
+    topic: string;
+    message: string;
+}): string;
+/** Find an ordered common suffix. Neither a timestamp nor equal values alone authorize skipping. */
+export declare function uniqueInputBoundary(processedTail: readonly string[], buffered: readonly string[]): number;
+//# sourceMappingURL=input-queue-boundary.d.ts.map

package/dist/runtime/input-queue-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-queue-boundary.d.ts","sourceRoot":"","sources":["../../src/runtime/input-queue-boundary.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,kBAAkB,yBAAuD,CAAC;AACvF,eAAO,MAAM,iBAAiB;;;;kBAI5B,CAAC;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACjE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAEjF;AAED,oGAAoG;AACpG,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAezG"}

package/dist/runtime/input-queue-boundary.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+export const inputPreviewSchema = z.array(z.string().regex(/^[a-f0-9]{64}$/)).max(100);
+export const inputCursorSchema = z.strictObject({
+    batchSize: z.number().int().min(0).max(100),
+    referenceHash: z.string().regex(/^[a-f0-9]{64}$/),
+    processedTail: inputPreviewSchema.optional(),
+});
+export function inputFingerprint(item) {
+    return createHash("sha256").update(JSON.stringify({ topic: item.topic, message: item.message })).digest("hex");
+}
+/** Find an ordered common suffix. Neither a timestamp nor equal values alone authorize skipping. */
+export function uniqueInputBoundary(processedTail, buffered) {
+    if (processedTail.length === 0)
+        return 0;
+    for (let size = Math.min(processedTail.length, buffered.length); size > 0; size--) {
+        const tail = processedTail.slice(-size);
+        const matches = (items) => {
+            const ends = [];
+            for (let start = 0; start <= items.length - size; start++)
+                if (tail.every((value, offset) => items[start + offset] === value))
+                    ends.push(start + size);
+            return ends;
+        };
+        if (matches(processedTail).length !== 1)
+            continue;
+        const ends = matches(buffered);
+        if (ends.length === 1)
+            return ends[0];
+    }
+    throw Error("MQTT input overlap is missing or ambiguous; successor stays passive");
+}
+//# sourceMappingURL=input-queue-boundary.js.map

package/dist/runtime/input-queue-boundary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-queue-boundary.js","sourceRoot":"","sources":["../../src/runtime/input-queue-boundary.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,YAAY,CAAC;IAC9C,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAC3C,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC;IACjD,aAAa,EAAE,kBAAkB,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC;AAEH,MAAM,UAAU,gBAAgB,CAAC,IAAwC;IACvE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACjH,CAAC;AAED,oGAAoG;AACpG,MAAM,UAAU,mBAAmB,CAAC,aAAgC,EAAE,QAA2B;IAC/F,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACzC,KAAK,IAAI,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC;QAClF,MAAM,IAAI,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,OAAO,GAAG,CAAC,KAAwB,EAAE,EAAE;YAC3C,MAAM,IAAI,GAAa,EAAE,CAAC;YAC1B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE;gBACvD,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,KAAK,CAAC;oBAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC;YAC9F,OAAO,IAAI,CAAC;QACd,CAAC,CAAC;QACF,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAClD,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/B,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IACxC,CAAC;IACD,MAAM,KAAK,CAAC,qEAAqE,CAAC,CAAC;AACrF,CAAC","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { z } from \"zod\";\n\nexport const inputPreviewSchema = z.array(z.string().regex(/^[a-f0-9]{64}$/)).max(100);\nexport const inputCursorSchema = z.strictObject({\n  batchSize: z.number().int().min(0).max(100),\n  referenceHash: z.string().regex(/^[a-f0-9]{64}$/),\n  processedTail: inputPreviewSchema.optional(),\n});\nexport type InputQueueCursor = z.infer<typeof inputCursorSchema>;\nexport function inputFingerprint(item: { topic: string; message: string }): string {\n  return createHash(\"sha256\").update(JSON.stringify({ topic: item.topic, message: item.message })).digest(\"hex\");\n}\n\n/** Find an ordered common suffix. Neither a timestamp nor equal values alone authorize skipping. */\nexport function uniqueInputBoundary(processedTail: readonly string[], buffered: readonly string[]): number {\n  if (processedTail.length === 0) return 0;\n  for (let size = Math.min(processedTail.length, buffered.length); size > 0; size--) {\n    const tail = processedTail.slice(-size);\n    const matches = (items: readonly string[]) => {\n      const ends: number[] = [];\n      for (let start = 0; start <= items.length - size; start++)\n        if (tail.every((value, offset) => items[start + offset] === value)) ends.push(start + size);\n      return ends;\n    };\n    if (matches(processedTail).length !== 1) continue;\n    const ends = matches(buffered);\n    if (ends.length === 1) return ends[0];\n  }\n  throw Error(\"MQTT input overlap is missing or ambiguous; successor stays passive\");\n}\n"]}

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

@@ -1,9 +1,10 @@
 import { z } from 'zod';
-export declare const MQTT_HANDOVER_STATE_FORMAT = 2;
+export declare const MQTT_HANDOVER_STATE_FORMAT = 3;
 export declare const MQTT_HANDOVER_STATE_MAX_BYTES: number;
 export declare const mqttHandoverOfferSchema: z.ZodArray<z.ZodObject<{
     instanceName: z.ZodString;
     compatibility: z.ZodString;
+    inputPreview: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>>;
 export declare const mqttProxyHandoverStateSchema: z.ZodObject<{
     instanceName: z.ZodString;
@@ -18,10 +19,15 @@ export declare const mqttProxyHandoverStateSchema: z.ZodObject<{
     cursor: z.ZodObject<{
         batchSize: z.ZodNumber;
         referenceHash: z.ZodString;
+        processedTail: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>;
 }, 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;
@@ -35,6 +41,7 @@ export declare const mqttHandoverStateSchema: z.ZodObject<{
         cursor: z.ZodObject<{
             batchSize: z.ZodNumber;
             referenceHash: z.ZodString;
+            processedTail: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

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;AAMxB,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAC5C,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAIzD,eAAO,MAAM,uBAAuB;;;;mBAI8E,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,9 +2,11 @@ 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';
+import { inputCursorSchema, inputPreviewSchema } from './input-queue-boundary.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;
+// Bound into peer compatibility so older cursor/state readers reject before freeze.
+export const MQTT_HANDOVER_STATE_FORMAT = 3;
 export const MQTT_HANDOVER_STATE_MAX_BYTES = 1024 * 1024;
 const text = z.string().min(1).max(65535).refine(v => !v.includes('\0'));
 const scalar = z.union([z.number().finite(), z.string().max(65535)]);
@@ -12,13 +14,14 @@ const value = z.union([scalar, z.array(scalar).max(4096)]);
 export const mqttHandoverOfferSchema = z.array(z.strictObject({
     instanceName: z.string().min(1).max(256),
     compatibility: z.string().regex(/^[a-f0-9]{64}$/),
+    inputPreview: inputPreviewSchema.optional(),
 })).max(64).refine(offer => new Set(offer.map(p => p.instanceName)).size === offer.length, 'Duplicate MQTT proxy');
 export const mqttProxyHandoverStateSchema = z.strictObject({
     instanceName: z.string().min(1).max(256),
     compatibility: z.string().regex(/^[a-f0-9]{64}$/),
     values: z.array(z.strictObject({ topic: text, value, uom: z.string().max(256).optional(), timestamp: z.string().datetime() })).max(10000),
     sequences: z.array(z.tuple([text, z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)])).max(10000),
-    cursor: z.strictObject({ batchSize: z.number().int().min(0).max(100), referenceHash: z.string().regex(/^[a-f0-9]{64}$/) }),
+    cursor: inputCursorSchema,
 }).superRefine((state, ctx) => {
     for (const keys of [state.values.map(v => v.topic), state.sequences.map(v => v[0])])
         if (new Set(keys).size !== keys.length)
@@ -26,6 +29,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 +39,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';\nimport { inputCursorSchema, inputPreviewSchema } from './input-queue-boundary.js';\n\n// Same contract for every SDK MQTT consumer. No application/profile selectors.\n// Bound into peer compatibility so older cursor/state readers reject before freeze.\nexport const MQTT_HANDOVER_STATE_FORMAT = 3;\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  inputPreview: inputPreviewSchema.optional(),\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: inputCursorSchema,\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;
@@ -32,11 +34,14 @@ export declare class HandoverManager {
     private stateDigest;
     private acceptedStateDigest;
     private targetPreparation;
+    private targetStateApplied;
     private finRetry;
+    private requestRetry;
+    private sourceReviewInFlight;
     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 +61,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;IAwCxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAC;IAxC7B,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,kBAAkB,CAAS;IACnC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,oBAAoB,CAAS;IAC9B,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;IA+FxE;;OAEG;IACH,OAAO,CAAC,UAAU;YAIJ,qBAAqB;YAiFrB,iBAAiB;YAOjB,mBAAmB;YA8BnB,mBAAmB;YAQnB,qBAAqB;YAWrB,oBAAoB;YA2BpB,cAAc;CA+I7B"}