@uns-kit/bridge-core

Shared runtime engine and management API for building protocol bridges into a Unified Namespace (UNS).

This package is intended to be the reusable base for bridge services. It provides the common lifecycle, reconciliation, and management API patterns, while concrete bridge applications implement their own protocol-specific adapter logic on top.

Scope

• Generic bridge runtime lifecycle
• Connection and mapping registries
• Reconciliation-friendly bridge engine
• Shared management API route helpers
• Generic bridge settings schema

Intended usage

Use @uns-kit/bridge-core as the shared template/runtime layer behind bridge services that:

• connect to external systems
• manage dynamic runtime connections and mappings
• normalize incoming value events
• publish into the UNS through an application-specific publisher

This package should stay protocol-agnostic. Concrete protocol concerns belong in the consuming bridge service, not here.

Development

pnpm run typecheck
pnpm run build

3.0 migration

Version 3.0.0 aligns the public Zod schema boundary with the Zod 4 based @uns-kit/core and @uns-kit/api 3.0.10 runtime. Concrete bridge add-ons must consume Zod 4 as well, so their project configuration can be combined and generated as one schema. MQTT table publishers must provide message.table.columns as an object keyed by column name; legacy arrays remain an inbound compatibility format handled by @uns-kit/core.

3.0.1 managed publisher

ManagedBridgePublisher wraps a protocol bridge's publisher and reconciles its observed topic metadata against configured effective output identities. It needs @uns-kit/core 3.0.21 (UnsProxy.retainProducedTopics). Include targets of stopped connections and every per-output override. Multiple mappings can share a target.

Allow reviewed new targets before activating the protocol so initial/retained values can be published. After persisting the configuration, await reconcile: it serializes target changes, rejects late callbacks for removed targets, drains already accepted publications with a bounded timeout, then evicts stale publisher metadata. On activation/persistence failure, reconcile the last committed target set. A timeout is an error, not evidence of completed removal; retry reconciliation after the transport recovers.

This changes only this publisher's advertised/observed targets. It neither clears retained MQTT values nor deletes UNS definitions or archived history. Reconciliation does not advertise configured targets that have never produced a value.

Release

pnpm run version:patch
pnpm run version:minor
pnpm run version:major
pnpm run publish:npm:dry-run
pnpm run publish:npm