@zlink-systems/framework 0.10.0

package/dist/runtime/locations/aggregate-inventory-store.js

@@ -0,0 +1,399 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkAggregateInventoryStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const in_memory_provider_location_store_1 = require("./in-memory-provider-location-store");
+const PREFIX = 'zlink:v11:aggregate-inventory:';
+const MAX_PAGE_ENTRIES = 1_024;
+const MAX_PAGE_BYTES = 1_024 * 1_024;
+const MAX_TREE_LEVELS = 32;
+const WRITE_CONCURRENCY = 64;
+/**
+ * Stores the Framework-owned participant inventory through only the opaque
+ * Location Store SPI. Providers do not interpret aggregate or participant data.
+ */
+class ZLinkAggregateInventoryStore {
+    provider;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    async store(request, signal) {
+        const fence = aggregateFence(request);
+        const tree = buildTree(request);
+        await parallelForEach(tree.pages, WRITE_CONCURRENCY, async (page) => {
+            const bytes = encode(page);
+            if (page.entries.length > MAX_PAGE_ENTRIES
+                || page.children.length > MAX_PAGE_ENTRIES
+                || bytes.byteLength > MAX_PAGE_BYTES) {
+                throw new Error('Aggregate inventory page exceeds its encoded bounds.');
+            }
+            await putImmutable(this.provider, pageKey(fence, page.level, page.index), bytes, signal);
+        });
+        await putImmutable(this.provider, rootKey(fence), encode(tree.root), signal);
+        await this.read(fence, request.inventoryDigest, signal);
+    }
+    async read(fence, expectedDeclaredDigest, signal) {
+        const rootBytes = await requireFound(this.provider, rootKey(fence), signal);
+        if (rootBytes.byteLength > MAX_PAGE_BYTES) {
+            throw dataLost(fence, 'root exceeds 1 MiB');
+        }
+        const root = decodeRoot(rootBytes);
+        validateRoot(root, fence);
+        if (expectedDeclaredDigest !== undefined
+            && !sameHash(root.declaredDigest, expectedDeclaredDigest)) {
+            throw dataLost(fence, 'declared digest does not match');
+        }
+        const entries = [];
+        const observedPageCounts = Array.from({ length: root.topLevel + 1 }, () => 0);
+        const visited = new Set();
+        const readPage = async (reference) => {
+            validateReference(reference, root, fence);
+            const identity = `${reference.level}:${reference.index}`;
+            if (visited.has(identity))
+                throw dataLost(fence, 'page reference is duplicated');
+            visited.add(identity);
+            const bytes = await requireFound(this.provider, pageKey(fence, reference.level, reference.index), signal);
+            if (bytes.byteLength > MAX_PAGE_BYTES
+                || !sameHash(reference.sha256, (0, node_crypto_1.createHash)('sha256').update(bytes).digest())) {
+                throw dataLost(fence, 'page checksum is invalid');
+            }
+            const page = decodePage(bytes);
+            if (page.level !== reference.level
+                || page.index !== reference.index
+                || page.startIndex !== reference.startIndex
+                || page.entryCount !== reference.entryCount) {
+                throw dataLost(fence, 'page metadata changed');
+            }
+            if (page.entries.length > MAX_PAGE_ENTRIES
+                || page.children.length > MAX_PAGE_ENTRIES) {
+                throw dataLost(fence, 'page entry bound is invalid');
+            }
+            observedPageCounts[page.level]++;
+            if (page.level === 0) {
+                if (page.entries.length < 1
+                    || page.children.length !== 0
+                    || page.entries.length !== page.entryCount) {
+                    throw dataLost(fence, 'leaf page bounds are invalid');
+                }
+                for (let offset = 0; offset < page.entries.length; offset++) {
+                    const entry = page.entries[offset];
+                    if (entry.index !== page.startIndex + offset) {
+                        throw dataLost(fence, 'leaf page entries are reordered');
+                    }
+                    entries.push(entry);
+                }
+                return;
+            }
+            if (page.entries.length !== 0 || page.children.length < 1) {
+                throw dataLost(fence, 'index page bounds are invalid');
+            }
+            let childStart = page.startIndex;
+            for (const child of page.children) {
+                if (child.level !== page.level - 1 || child.startIndex !== childStart) {
+                    throw dataLost(fence, 'index page children are reordered');
+                }
+                await readPage(child);
+                childStart += child.entryCount;
+            }
+            if (childStart !== page.startIndex + page.entryCount) {
+                throw dataLost(fence, 'index page entry count changed');
+            }
+        };
+        let expectedStart = 0;
+        for (const reference of root.topPages) {
+            if (reference.level !== root.topLevel
+                || reference.startIndex !== expectedStart) {
+                throw dataLost(fence, 'top page references are reordered');
+            }
+            await readPage(reference);
+            expectedStart += reference.entryCount;
+        }
+        if (expectedStart !== root.totalCount
+            || entries.length !== root.totalCount
+            || observedPageCounts.some((count, level) => count !== root.pageCountsByLevel[level])) {
+            throw dataLost(fence, 'page counts do not match the root');
+        }
+        for (let level = 0; level < observedPageCounts.length; level++) {
+            for (let index = 0; index < observedPageCounts[level]; index++) {
+                if (!visited.has(`${level}:${index}`)) {
+                    throw dataLost(fence, 'page indexes are not contiguous');
+                }
+            }
+        }
+        const digest = (0, node_crypto_1.createHash)('sha256');
+        for (let index = 0; index < entries.length; index++) {
+            const entry = entries[index];
+            validateEntry(entry, index, fence);
+            digest.update(encode(entry));
+        }
+        if (!sameHash(root.digest, digest.digest())) {
+            throw dataLost(fence, 'inventory digest does not match');
+        }
+        return entries.map(entry => ({ ...entry }));
+    }
+}
+exports.ZLinkAggregateInventoryStore = ZLinkAggregateInventoryStore;
+function buildTree(request) {
+    if (request.participants.length < 1) {
+        throw new RangeError('Aggregate inventory requires at least one participant.');
+    }
+    if (request.inventoryDigest.byteLength !== 32) {
+        throw new TypeError('Aggregate inventory digest must contain 32 bytes.');
+    }
+    const entries = request.participants.map((participant, index) => ({
+        index,
+        authorityKey: participant.authorityKey.value,
+        expectedStoreVersion: participant.expectedStoreVersion.value,
+        ownerTransition: participant.ownerTransition,
+        authorityPayloadSha256: sha256(participant.authorityPayload),
+        membershipMutationSha256: sha256(participant.membershipMutation)
+    }));
+    const keys = entries.map(entry => entry.authorityKey);
+    if (new Set(keys).size !== keys.length
+        || keys.some((key, index) => index > 0 && keys[index - 1].localeCompare(key) >= 0)) {
+        throw new TypeError('Aggregate participants must be unique and canonically sorted.');
+    }
+    const digest = (0, node_crypto_1.createHash)('sha256');
+    for (const entry of entries)
+        digest.update(encode(entry));
+    const pages = [];
+    let references = packLeafPages(entries, pages);
+    let level = 0;
+    while (references.length > MAX_PAGE_ENTRIES
+        || encode(rootCandidate(entries.length, level, references, pages, '', '')).byteLength
+            > MAX_PAGE_BYTES) {
+        level++;
+        if (level >= MAX_TREE_LEVELS) {
+            throw new RangeError('Aggregate inventory tree exceeds 32 levels.');
+        }
+        references = packIndexPages(level, references, pages);
+    }
+    const root = rootCandidate(entries.length, level, references, pages, digest.digest('hex'), Buffer.from(request.inventoryDigest).toString('hex'));
+    if (encode(root).byteLength > MAX_PAGE_BYTES) {
+        throw new RangeError('Aggregate inventory root exceeds 1 MiB.');
+    }
+    return { root, pages };
+}
+function packLeafPages(entries, pages) {
+    const references = [];
+    for (let offset = 0; offset < entries.length;) {
+        let count = Math.min(MAX_PAGE_ENTRIES, entries.length - offset);
+        let page;
+        let bytes;
+        do {
+            page = {
+                kind: 'aggregate-inventory-page-v1',
+                level: 0,
+                index: references.length,
+                startIndex: offset,
+                entryCount: count,
+                entries: entries.slice(offset, offset + count),
+                children: []
+            };
+            bytes = encode(page);
+            if (bytes.byteLength <= MAX_PAGE_BYTES)
+                break;
+            count = Math.floor(count / 2);
+        } while (count > 0);
+        if (count < 1 || bytes.byteLength > MAX_PAGE_BYTES) {
+            throw new RangeError('Aggregate inventory entry exceeds 1 MiB.');
+        }
+        pages.push(page);
+        references.push(referenceFor(page, bytes));
+        offset += count;
+    }
+    return references;
+}
+function packIndexPages(level, children, pages) {
+    const references = [];
+    for (let offset = 0; offset < children.length;) {
+        let count = Math.min(MAX_PAGE_ENTRIES, children.length - offset);
+        let page;
+        let bytes;
+        do {
+            const selected = children.slice(offset, offset + count);
+            page = {
+                kind: 'aggregate-inventory-page-v1',
+                level,
+                index: references.length,
+                startIndex: selected[0].startIndex,
+                entryCount: selected.reduce((sum, child) => sum + child.entryCount, 0),
+                entries: [],
+                children: selected
+            };
+            bytes = encode(page);
+            if (bytes.byteLength <= MAX_PAGE_BYTES)
+                break;
+            count = Math.floor(count / 2);
+        } while (count > 0);
+        if (count < 1 || bytes.byteLength > MAX_PAGE_BYTES) {
+            throw new RangeError('Aggregate inventory page reference exceeds 1 MiB.');
+        }
+        pages.push(page);
+        references.push(referenceFor(page, bytes));
+        offset += count;
+    }
+    return references;
+}
+function rootCandidate(totalCount, topLevel, topPages, pages, digest, declaredDigest) {
+    const pageCountsByLevel = Array.from({ length: topLevel + 1 }, () => 0);
+    for (const page of pages) {
+        if (page.level <= topLevel)
+            pageCountsByLevel[page.level]++;
+    }
+    return {
+        kind: 'aggregate-inventory-root-v1',
+        totalCount,
+        digest,
+        declaredDigest,
+        topLevel,
+        topPages,
+        pageCountsByLevel
+    };
+}
+function validateRoot(root, fence) {
+    if (!Number.isSafeInteger(root.totalCount)
+        || root.totalCount < 1
+        || !isSha256(root.digest)
+        || !isSha256(root.declaredDigest)
+        || !Number.isSafeInteger(root.topLevel)
+        || root.topLevel < 0
+        || root.topLevel >= MAX_TREE_LEVELS
+        || root.topPages.length < 1
+        || root.topPages.length > MAX_PAGE_ENTRIES
+        || root.pageCountsByLevel.length !== root.topLevel + 1
+        || root.pageCountsByLevel.some(count => !Number.isSafeInteger(count) || count < 1 || count > root.totalCount)) {
+        throw dataLost(fence, 'root metadata is invalid');
+    }
+    const leafPages = root.pageCountsByLevel[0];
+    if (leafPages > root.totalCount
+        || root.totalCount > leafPages * MAX_PAGE_ENTRIES
+        || root.topPages.length !== root.pageCountsByLevel[root.topLevel]) {
+        throw dataLost(fence, 'root page counts are invalid');
+    }
+    for (let level = 1; level < root.pageCountsByLevel.length; level++) {
+        const lower = root.pageCountsByLevel[level - 1];
+        const current = root.pageCountsByLevel[level];
+        if (current < Math.ceil(lower / MAX_PAGE_ENTRIES) || current > lower) {
+            throw dataLost(fence, 'index page counts are invalid');
+        }
+    }
+}
+function validateReference(reference, root, fence) {
+    if (!Number.isSafeInteger(reference.level)
+        || reference.level < 0
+        || reference.level > root.topLevel
+        || !Number.isSafeInteger(reference.index)
+        || reference.index < 0
+        || !Number.isSafeInteger(reference.startIndex)
+        || reference.startIndex < 0
+        || !Number.isSafeInteger(reference.entryCount)
+        || reference.entryCount < 1
+        || !isSha256(reference.sha256)) {
+        throw dataLost(fence, 'page reference is invalid');
+    }
+}
+function validateEntry(entry, index, fence) {
+    if (entry.index !== index
+        || entry.authorityKey.length < 1
+        || entry.expectedStoreVersion.length < 1
+        || !['preserve', 'newOwner'].includes(entry.ownerTransition)
+        || !isSha256(entry.authorityPayloadSha256)
+        || !isSha256(entry.membershipMutationSha256)) {
+        throw dataLost(fence, 'inventory entry is invalid or reordered');
+    }
+}
+async function putImmutable(provider, key, bytes, signal) {
+    const result = await provider.write({
+        conditions: [{ kind: 'missing', key }],
+        mutations: [{ kind: 'put', key, bytes }]
+    }, signal);
+    if (result.kind === 'applied')
+        return;
+    const current = await provider.read(key, signal);
+    if (current.kind !== 'found'
+        || !Buffer.from(current.value.bytes).equals(Buffer.from(bytes))) {
+        throw new Error(`Immutable aggregate inventory value changed: ${key.value}.`);
+    }
+}
+async function requireFound(provider, key, signal) {
+    const result = await provider.read(key, signal);
+    if (result.kind !== 'found') {
+        throw new Error(`Aggregate inventory value is missing: ${key.value}.`);
+    }
+    return result.value.bytes;
+}
+function decodeRoot(bytes) {
+    const value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    if (value === null
+        || typeof value !== 'object'
+        || !('kind' in value)
+        || value.kind !== 'aggregate-inventory-root-v1') {
+        throw new Error('Invalid inventory root.');
+    }
+    return value;
+}
+function decodePage(bytes) {
+    const value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    if (value === null
+        || typeof value !== 'object'
+        || !('kind' in value)
+        || value.kind !== 'aggregate-inventory-page-v1'
+        || !('entries' in value)
+        || !Array.isArray(value.entries)
+        || !('children' in value)
+        || !Array.isArray(value.children)) {
+        throw new Error('Invalid inventory page.');
+    }
+    return value;
+}
+function encode(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8');
+}
+function referenceFor(page, encoded) {
+    return {
+        level: page.level,
+        index: page.index,
+        startIndex: page.startIndex,
+        entryCount: page.entryCount,
+        sha256: sha256(encoded)
+    };
+}
+function aggregateFence(request) {
+    return {
+        aggregateId: request.aggregateId,
+        aggregateGeneration: request.aggregateGeneration
+    };
+}
+function rootKey(fence) {
+    return (0, in_memory_provider_location_store_1.storeKey)(`${aggregatePrefix(fence)}root`);
+}
+function pageKey(fence, level, index) {
+    return (0, in_memory_provider_location_store_1.storeKey)(`${aggregatePrefix(fence)}page:${level}:${index}`);
+}
+function aggregatePrefix(fence) {
+    return `${PREFIX}${encodeURIComponent(fence.aggregateId.value)}:${fence.aggregateGeneration}:`;
+}
+function sha256(bytes) {
+    return (0, node_crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+function isSha256(value) {
+    return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);
+}
+function sameHash(expected, actual) {
+    return isSha256(expected)
+        && actual.byteLength === 32
+        && (0, node_crypto_1.timingSafeEqual)(Buffer.from(expected, 'hex'), Buffer.from(actual));
+}
+function dataLost(fence, reason) {
+    return new Error(`Aggregate '${fence.aggregateId.value}:${fence.aggregateGeneration}' inventory ${reason}.`);
+}
+async function parallelForEach(values, concurrency, operation) {
+    let next = 0;
+    await Promise.all(Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        while (next < values.length) {
+            const index = next++;
+            await operation(values[index]);
+        }
+    }));
+}

package/dist/runtime/locations/authority-key-codec.d.ts

@@ -0,0 +1,6 @@
+import type { ZLinkAuthorityKey, ZLinkPlacementObjectKind } from '../../contracts/Locations/Authority';
+export declare function encodeAuthorityKey(kind: ZLinkPlacementObjectKind, globalId: string): ZLinkAuthorityKey;
+export declare function decodeAuthorityKey(key: ZLinkAuthorityKey): {
+    readonly kind: ZLinkPlacementObjectKind;
+    readonly globalId: string;
+};

package/dist/runtime/locations/authority-key-codec.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeAuthorityKey = encodeAuthorityKey;
+exports.decodeAuthorityKey = decodeAuthorityKey;
+function encodeAuthorityKey(kind, globalId) {
+    const bytes = Buffer.from(globalId);
+    if (bytes.byteLength < 1 || bytes.byteLength > 255) {
+        throw new RangeError('Authority identity must contain 1..255 UTF-8 bytes.');
+    }
+    const discriminator = kind === 'actor' ? 'a' : 's';
+    return {
+        value: `zla1:${discriminator}:${bytes.byteLength}:${percentEncode(bytes)}`
+    };
+}
+function decodeAuthorityKey(key) {
+    if (Buffer.byteLength(key.value, 'utf8') > 776) {
+        throw new TypeError('Authority key exceeds the encoded byte limit.');
+    }
+    const match = /^zla1:([as]):([1-9][0-9]{0,2}):(.*)$/.exec(key.value);
+    if (match === null)
+        throw new TypeError('Authority key is not canonical.');
+    const declaredLength = Number(match[2]);
+    if (declaredLength > 255)
+        throw new TypeError('Authority key identity exceeds the byte limit.');
+    const encoded = match[3];
+    const bytes = [];
+    for (let index = 0; index < encoded.length;) {
+        if (encoded[index] === '%') {
+            const hex = encoded.slice(index + 1, index + 3);
+            if (!/^[0-9A-F]{2}$/.test(hex))
+                throw new TypeError('Authority key escape is invalid.');
+            const byte = Number.parseInt(hex, 16);
+            if (isUnreserved(byte))
+                throw new TypeError('Authority key escape is not canonical.');
+            bytes.push(byte);
+            index += 3;
+        }
+        else {
+            const byte = encoded.charCodeAt(index);
+            if (!isUnreserved(byte))
+                throw new TypeError('Authority key literal is not canonical.');
+            bytes.push(byte);
+            index++;
+        }
+    }
+    if (bytes.length !== declaredLength) {
+        throw new TypeError('Authority key length does not match its identity.');
+    }
+    let globalId;
+    try {
+        globalId = new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(bytes));
+    }
+    catch (error) {
+        throw new TypeError('Authority key identity is not valid UTF-8.', { cause: error });
+    }
+    return {
+        kind: match[1] === 'a' ? 'actor' : 'user_spot',
+        globalId
+    };
+}
+function percentEncode(bytes) {
+    let result = '';
+    for (const byte of bytes) {
+        result += isUnreserved(byte)
+            ? String.fromCharCode(byte)
+            : `%${byte.toString(16).toUpperCase().padStart(2, '0')}`;
+    }
+    return result;
+}
+function isUnreserved(byte) {
+    return byte >= 0x41 && byte <= 0x5a
+        || byte >= 0x61 && byte <= 0x7a
+        || byte >= 0x30 && byte <= 0x39
+        || byte === 0x2d
+        || byte === 0x2e
+        || byte === 0x5f
+        || byte === 0x7e;
+}

package/dist/runtime/locations/auto-connect-loop.d.ts

@@ -0,0 +1,37 @@
+import { type ZLinkLocationOptionOverrides } from '../../contracts/Locations/Options';
+import type { ZLinkDomainLocationStore as ZLinkLocationStore } from './domain-store-contract';
+import type { ZLinkOwnerLeaseTracker } from './lease-tracker';
+import type { ZLinkAutoConnectLocal } from './auto-connect-types';
+import type { ZLinkAutoConnectReconciler } from './auto-connect-reconciler';
+export interface ZLinkAutoConnectLoopOptions {
+    readonly reconciler: ZLinkAutoConnectReconciler;
+    readonly local: ZLinkAutoConnectLocal;
+    readonly options?: ZLinkLocationOptionOverrides;
+    readonly changeStampStore?: Pick<ZLinkLocationStore, 'getMeshNodeChangeStamp'>;
+    readonly leaseTracker?: ZLinkOwnerLeaseTracker;
+    readonly setTimer?: (callback: () => void, delayMs: number) => unknown;
+    readonly clearTimer?: (handle: unknown) => void;
+}
+export declare class ZLinkAutoConnectLoop {
+    private readonly lane;
+    private readonly reconciler;
+    private readonly options;
+    private readonly meshName;
+    private readonly changeStampStore?;
+    private readonly leaseTracker?;
+    private readonly setTimer;
+    private readonly clearTimer;
+    private controller?;
+    private timer?;
+    private lastStamp?;
+    private lastLiveOwnerSetVersion?;
+    private lastTickFailed;
+    constructor(options: ZLinkAutoConnectLoopOptions);
+    start(signal?: AbortSignal): Promise<void>;
+    stop(signal?: AbortSignal): Promise<void>;
+    prepareTransportShutdown(): Promise<void>;
+    finishTransportShutdown(signal?: AbortSignal): Promise<void>;
+    tick(signal?: AbortSignal): Promise<void>;
+    private runReconcile;
+    private scheduleNext;
+}

package/dist/runtime/locations/auto-connect-loop.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkAutoConnectLoop = void 0;
+const Options_1 = require("../../contracts/Locations/Options");
+const state_lane_1 = require("../execution/state-lane");
+class ZLinkAutoConnectLoop {
+    lane = new state_lane_1.ZLinkStateLane();
+    reconciler;
+    options;
+    meshName;
+    changeStampStore;
+    leaseTracker;
+    setTimer;
+    clearTimer;
+    controller;
+    timer;
+    lastStamp;
+    lastLiveOwnerSetVersion;
+    lastTickFailed = false;
+    constructor(options) {
+        this.reconciler = options.reconciler;
+        this.options = { ...Options_1.zlinkRuntimeDefaultLocationOptions, ...options.options };
+        this.meshName = options.local.meshName;
+        this.changeStampStore = options.changeStampStore;
+        this.leaseTracker = options.leaseTracker;
+        this.setTimer = options.setTimer ?? ((callback, delayMs) => setTimeout(callback, delayMs));
+        this.clearTimer = options.clearTimer ?? ((handle) => clearTimeout(handle));
+    }
+    async start(signal) {
+        if (await this.lane.run(() => this.controller !== undefined))
+            return;
+        await this.tick(signal);
+        const started = await this.lane.run(() => {
+            if (this.controller !== undefined)
+                return false;
+            this.controller = new AbortController();
+            return true;
+        });
+        if (!started)
+            return;
+        this.scheduleNext();
+    }
+    async stop(signal) {
+        await this.prepareTransportShutdown();
+        await this.finishTransportShutdown(signal);
+    }
+    async prepareTransportShutdown() {
+        const controller = this.controller;
+        this.controller = undefined;
+        if (controller !== undefined) {
+            controller.abort();
+        }
+        if (this.timer !== undefined) {
+            this.clearTimer(this.timer);
+            this.timer = undefined;
+        }
+        this.reconciler.disconnectPeers();
+    }
+    async finishTransportShutdown(signal) {
+        await this.reconciler.unpublishLocal(signal);
+    }
+    async tick(signal) {
+        const lastTickFailed = await this.lane.run(() => this.lastTickFailed);
+        if (this.changeStampStore?.getMeshNodeChangeStamp !== undefined && !lastTickFailed) {
+            try {
+                const stamp = await this.changeStampStore.getMeshNodeChangeStamp(this.meshName, signal);
+                const liveOwners = this.leaseTracker === undefined
+                    ? 0
+                    : await this.leaseTracker.getLiveOwnerSetVersion(signal);
+                if (this.lastStamp === stamp
+                    && this.lastLiveOwnerSetVersion === liveOwners
+                    && this.reconciler.localPublicationReady) {
+                    return;
+                }
+                const tickFailed = await this.runReconcile(signal);
+                if (!tickFailed)
+                    await this.lane.run(() => {
+                        this.lastStamp = stamp;
+                        this.lastLiveOwnerSetVersion = liveOwners;
+                    });
+                return;
+            }
+            catch {
+                // A failed stamp read degrades to a full reconcile tick.
+            }
+        }
+        await this.runReconcile(signal);
+        await this.lane.run(() => {
+            this.lastStamp = undefined;
+            this.lastLiveOwnerSetVersion = undefined;
+        });
+    }
+    async runReconcile(signal) {
+        await this.reconciler.tick(signal);
+        return await this.lane.run(() => {
+            this.lastTickFailed = this.reconciler.storeFailed;
+            return this.lastTickFailed;
+        });
+    }
+    scheduleNext() {
+        if (this.controller === undefined || this.controller.signal.aborted) {
+            return;
+        }
+        this.timer = this.setTimer(() => {
+            this.timer = undefined;
+            void this.tick(this.controller?.signal)
+                .catch(() => undefined)
+                .finally(() => this.scheduleNext());
+        }, this.options.pollingIntervalMs);
+    }
+}
+exports.ZLinkAutoConnectLoop = ZLinkAutoConnectLoop;

package/dist/runtime/locations/auto-connect-planner.d.ts

@@ -0,0 +1,9 @@
+import { ZLinkLocationAutoConnectType, ZLinkLocationRole, type ZLinkPeerLocation } from './internal-location-contracts';
+import type { ZLinkAutoConnectLocal, ZLinkAutoConnectTarget } from './auto-connect-types';
+export declare const ZLinkAutoConnectPlanner: Readonly<{
+    isRoleAllowed(type: ZLinkLocationAutoConnectType, role: ZLinkLocationRole): boolean;
+    computeDesired(local: ZLinkAutoConnectLocal, peers: readonly ZLinkPeerLocation[], includeDraining?: boolean): ReadonlyMap<string, ZLinkAutoConnectTarget>;
+    computeCandidates(local: ZLinkAutoConnectLocal, peers: readonly ZLinkPeerLocation[]): ReadonlyMap<string, ZLinkAutoConnectTarget>;
+    targetKeyOf(peer: ZLinkPeerLocation): string;
+    computeNotRequired(local: ZLinkAutoConnectLocal, peers: readonly ZLinkPeerLocation[]): readonly ZLinkAutoConnectTarget[];
+}>;