@zlink-systems/framework 0.10.0

package/dist/contracts/Handlers/JsonContract.d.ts

@@ -0,0 +1,46 @@
+/** Describes the fields accepted by the default framework-json-v1 serializer. */
+export type ZLinkJsonSchema = {
+    readonly type: 'boolean';
+} | {
+    readonly type: 'string';
+} | {
+    readonly type: 'number';
+} | {
+    readonly type: 'int32';
+} | {
+    readonly type: 'uint32';
+} | {
+    readonly type: 'int64';
+} | {
+    readonly type: 'uint64';
+} | {
+    readonly type: 'bytes';
+} | {
+    readonly type: 'enum';
+    readonly names: readonly string[];
+} | {
+    readonly type: 'nullable';
+    readonly value: ZLinkJsonSchema;
+} | {
+    readonly type: 'array';
+    readonly items: ZLinkJsonSchema;
+} | {
+    readonly type: 'record';
+    readonly values: ZLinkJsonSchema;
+} | {
+    readonly type: 'object';
+    readonly properties: Readonly<Record<string, ZLinkJsonSchema>>;
+    readonly required: readonly string[];
+    /** Unknown properties are ignored during decoding unless this is false. */
+    readonly additionalProperties?: boolean;
+};
+/**
+ * Describes the request and optional reply fields carried under one packet
+ * name by the default JSON serializer.
+ */
+export interface ZLinkPacketJsonContract {
+    readonly payload: ZLinkJsonSchema;
+    readonly reply?: ZLinkJsonSchema;
+}
+export declare function defineZLinkPacketJsonContract(packetName: string, contract: ZLinkPacketJsonContract): ZLinkPacketJsonContract;
+export declare function readZLinkPacketJsonContract(packetName: string): ZLinkPacketJsonContract | undefined;

package/dist/contracts/Handlers/JsonContract.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineZLinkPacketJsonContract = defineZLinkPacketJsonContract;
+exports.readZLinkPacketJsonContract = readZLinkPacketJsonContract;
+const ZLINK_PACKET_JSON_CONTRACTS = Symbol.for('@zlink-systems/framework:packet-json-contracts');
+function defineZLinkPacketJsonContract(packetName, contract) {
+    if (packetName.trim().length === 0) {
+        throw new TypeError('ZLink packet name must not be empty.');
+    }
+    const runtimeContract = contract;
+    if (typeof runtimeContract !== 'object' || runtimeContract === null) {
+        throw new TypeError('ZLink packet JSON contract must be an object.');
+    }
+    const normalizedContract = runtimeContract;
+    const normalized = Object.freeze({
+        payload: normalizeJsonSchema(normalizedContract.payload, new Set(), 0),
+        ...(normalizedContract.reply === undefined
+            ? {}
+            : { reply: normalizeJsonSchema(normalizedContract.reply, new Set(), 0) })
+    });
+    const contracts = packetJsonContracts();
+    const current = contracts.get(packetName);
+    if (current !== undefined && canonicalContract(current) !== canonicalContract(normalized)) {
+        throw new TypeError(`ZLink packet '${packetName}' has conflicting JSON contracts in one process.`);
+    }
+    if (current !== undefined)
+        return current;
+    contracts.set(packetName, normalized);
+    return normalized;
+}
+function readZLinkPacketJsonContract(packetName) {
+    return packetJsonContracts().get(packetName);
+}
+function normalizeJsonSchema(schema, parents, depth) {
+    // Keep the runtime boundary defensive for JavaScript callers even though
+    // the TypeScript signature describes the accepted shape.
+    const runtimeSchema = schema;
+    if (typeof runtimeSchema !== 'object' || runtimeSchema === null || depth > 64) {
+        throw new TypeError('ZLink packet JSON schema must be an acyclic object with at most 64 levels.');
+    }
+    const normalizedSchema = runtimeSchema;
+    if (parents.has(normalizedSchema))
+        throw new TypeError('ZLink packet JSON schema must not contain a cycle.');
+    const nextParents = new Set(parents).add(normalizedSchema);
+    switch (normalizedSchema.type) {
+        case 'boolean':
+        case 'string':
+        case 'number':
+        case 'int32':
+        case 'uint32':
+        case 'int64':
+        case 'uint64':
+        case 'bytes':
+            return Object.freeze({ type: normalizedSchema.type });
+        case 'enum': {
+            if (!Array.isArray(normalizedSchema.names)
+                || normalizedSchema.names.length === 0
+                || normalizedSchema.names.some((name) => typeof name !== 'string' || name.length === 0)) {
+                throw new TypeError('ZLink packet enum schema requires non-empty string names.');
+            }
+            if (new Set(normalizedSchema.names).size !== normalizedSchema.names.length) {
+                throw new TypeError('ZLink packet enum schema names must be unique.');
+            }
+            return Object.freeze({ type: 'enum', names: Object.freeze([...normalizedSchema.names]) });
+        }
+        case 'nullable':
+            return Object.freeze({ type: 'nullable', value: normalizeJsonSchema(normalizedSchema.value, nextParents, depth + 1) });
+        case 'array':
+            return Object.freeze({ type: 'array', items: normalizeJsonSchema(normalizedSchema.items, nextParents, depth + 1) });
+        case 'record':
+            return Object.freeze({ type: 'record', values: normalizeJsonSchema(normalizedSchema.values, nextParents, depth + 1) });
+        case 'object': {
+            const runtimeProperties = normalizedSchema.properties;
+            if (typeof runtimeProperties !== 'object' || runtimeProperties === null || Array.isArray(runtimeProperties)) {
+                throw new TypeError('ZLink packet object schema properties must be an object.');
+            }
+            if (!Array.isArray(normalizedSchema.required)
+                || normalizedSchema.required.some((name) => typeof name !== 'string' || name.length === 0)) {
+                throw new TypeError('ZLink packet object schema required must contain property names.');
+            }
+            if (normalizedSchema.additionalProperties !== undefined && typeof normalizedSchema.additionalProperties !== 'boolean') {
+                throw new TypeError('ZLink packet object schema additionalProperties must be boolean.');
+            }
+            const properties = {};
+            for (const [name, property] of Object.entries(runtimeProperties)) {
+                if (name === '__proto__' || name === 'prototype' || name === 'constructor') {
+                    throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
+                }
+                properties[name] = normalizeJsonSchema(property, nextParents, depth + 1);
+            }
+            if (new Set(normalizedSchema.required).size !== normalizedSchema.required.length) {
+                throw new TypeError('ZLink packet JSON required properties must be unique.');
+            }
+            for (const name of normalizedSchema.required) {
+                if (name === '__proto__' || name === 'prototype' || name === 'constructor') {
+                    throw new TypeError(`ZLink packet JSON property '${name}' is not allowed.`);
+                }
+                if (!Object.prototype.hasOwnProperty.call(properties, name)) {
+                    throw new TypeError(`ZLink packet JSON required property '${name}' has no property schema.`);
+                }
+            }
+            return Object.freeze({
+                type: 'object',
+                properties: Object.freeze(properties),
+                required: Object.freeze([...normalizedSchema.required]),
+                ...(normalizedSchema.additionalProperties === undefined
+                    ? {}
+                    : { additionalProperties: normalizedSchema.additionalProperties })
+            });
+        }
+    }
+    throw new TypeError(`ZLink packet JSON schema type '${String(normalizedSchema.type)}' is not supported.`);
+}
+function packetJsonContracts() {
+    const root = globalThis;
+    let contracts = root[ZLINK_PACKET_JSON_CONTRACTS];
+    if (contracts === undefined) {
+        contracts = new Map();
+        Object.defineProperty(root, ZLINK_PACKET_JSON_CONTRACTS, {
+            configurable: false,
+            enumerable: false,
+            value: contracts,
+            writable: false
+        });
+    }
+    return contracts;
+}
+function canonicalContract(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalContract).join(',')}]`;
+    if (typeof value !== 'object' || value === null)
+        return JSON.stringify(value);
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, item]) => `${JSON.stringify(key)}:${canonicalContract(item)}`)
+        .join(',')}}`;
+}

package/dist/contracts/Handlers/ZLinkHandlerFilterNext.d.ts

@@ -0,0 +1 @@
+export type ZLinkHandlerFilterNext = () => Promise<void>;

package/dist/contracts/Handlers/ZLinkHandlerFilterNext.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/Handlers/index.d.ts

@@ -0,0 +1,5 @@
+export { ZLinkHandlerGroup, ZLinkPacket, ZLinkPublish, ZLinkRequest, ZLinkSend, ZLinkSpotActorRequest, ZLinkSpotActorSend, ZLinkSpotRequest, ZLinkSpotSubscription, ZLinkStreamPacket, ZLinkStreamRaw } from './Attributes';
+export * from './Contexts';
+export * from './IZLinkChannelHandlers';
+export * from './IZLinkHandlerFilter';
+export * from './ZLinkHandlerFilterNext';

package/dist/contracts/Handlers/index.js

@@ -0,0 +1,33 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkStreamRaw = exports.ZLinkStreamPacket = exports.ZLinkSpotSubscription = exports.ZLinkSpotRequest = exports.ZLinkSpotActorSend = exports.ZLinkSpotActorRequest = exports.ZLinkSend = exports.ZLinkRequest = exports.ZLinkPublish = exports.ZLinkPacket = exports.ZLinkHandlerGroup = void 0;
+var Attributes_1 = require("./Attributes");
+Object.defineProperty(exports, "ZLinkHandlerGroup", { enumerable: true, get: function () { return Attributes_1.ZLinkHandlerGroup; } });
+Object.defineProperty(exports, "ZLinkPacket", { enumerable: true, get: function () { return Attributes_1.ZLinkPacket; } });
+Object.defineProperty(exports, "ZLinkPublish", { enumerable: true, get: function () { return Attributes_1.ZLinkPublish; } });
+Object.defineProperty(exports, "ZLinkRequest", { enumerable: true, get: function () { return Attributes_1.ZLinkRequest; } });
+Object.defineProperty(exports, "ZLinkSend", { enumerable: true, get: function () { return Attributes_1.ZLinkSend; } });
+Object.defineProperty(exports, "ZLinkSpotActorRequest", { enumerable: true, get: function () { return Attributes_1.ZLinkSpotActorRequest; } });
+Object.defineProperty(exports, "ZLinkSpotActorSend", { enumerable: true, get: function () { return Attributes_1.ZLinkSpotActorSend; } });
+Object.defineProperty(exports, "ZLinkSpotRequest", { enumerable: true, get: function () { return Attributes_1.ZLinkSpotRequest; } });
+Object.defineProperty(exports, "ZLinkSpotSubscription", { enumerable: true, get: function () { return Attributes_1.ZLinkSpotSubscription; } });
+Object.defineProperty(exports, "ZLinkStreamPacket", { enumerable: true, get: function () { return Attributes_1.ZLinkStreamPacket; } });
+Object.defineProperty(exports, "ZLinkStreamRaw", { enumerable: true, get: function () { return Attributes_1.ZLinkStreamRaw; } });
+__exportStar(require("./Contexts"), exports);
+__exportStar(require("./IZLinkChannelHandlers"), exports);
+__exportStar(require("./IZLinkHandlerFilter"), exports);
+__exportStar(require("./ZLinkHandlerFilterNext"), exports);

package/dist/contracts/Locations/ActorTransfer.d.ts

@@ -0,0 +1,41 @@
+import type { ActorRef, RoutingId } from '../Common';
+export type ZLinkActorTransferState = 'prepared' | 'committed' | 'activated' | 'aborted';
+export type ZLinkActorTransferWriteStatus = 'stored' | 'notFound' | 'ignoredStale' | 'rejectedConflict' | 'invalidState';
+export interface ZLinkActorTransferRecord {
+    readonly meshName: string;
+    readonly actorId: string;
+    readonly transferId: string;
+    readonly source: ActorRef;
+    readonly target: ActorRef;
+    readonly expectedActorGeneration: bigint;
+    readonly expectedMembershipEpoch: bigint;
+    readonly participants: ReadonlySet<RoutingId>;
+    readonly state: ZLinkActorTransferState;
+    readonly recoveryOwnerId: string;
+    readonly recoveryLeaseExpiresAt: Date;
+    readonly updatedAt: Date;
+}
+export interface ZLinkActorTransferPrepareRequest {
+    readonly meshName: string;
+    readonly actorId: string;
+    readonly transferId: string;
+    readonly source: ActorRef;
+    readonly target: ActorRef;
+    readonly expectedActorGeneration: bigint;
+    readonly expectedMembershipEpoch: bigint;
+    readonly participants: ReadonlySet<RoutingId>;
+    readonly recoveryOwnerId: string;
+    readonly recoveryLeaseTtlMs: number;
+}
+export interface ZLinkActorTransferWriteResult {
+    readonly status: ZLinkActorTransferWriteStatus;
+    readonly record?: ZLinkActorTransferRecord;
+}
+export interface ZLinkActorTransferStore {
+    prepareActorTransfer(request: ZLinkActorTransferPrepareRequest, signal?: AbortSignal): Promise<ZLinkActorTransferWriteResult>;
+    commitActorTransfer(meshName: string, actorId: string, transferId: string, recoveryOwnerId: string, signal?: AbortSignal): Promise<ZLinkActorTransferWriteResult>;
+    activateActorTransfer(meshName: string, actorId: string, transferId: string, recoveryOwnerId: string, signal?: AbortSignal): Promise<ZLinkActorTransferWriteResult>;
+    abortActorTransfer(meshName: string, actorId: string, transferId: string, recoveryOwnerId: string, signal?: AbortSignal): Promise<ZLinkActorTransferWriteResult>;
+    takeOverActorTransfer(meshName: string, actorId: string, transferId: string, successorOwnerId: string, recoveryLeaseTtlMs: number, signal?: AbortSignal): Promise<ZLinkActorTransferWriteResult>;
+    resolveActorTransfer(meshName: string, actorId: string, signal?: AbortSignal): Promise<ZLinkActorTransferRecord | undefined>;
+}

package/dist/contracts/Locations/ActorTransfer.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/Locations/Authority.d.ts

@@ -0,0 +1,296 @@
+import type { RoutingId } from '../Common';
+import type { ZLinkMeshNodeDescriptorKey } from './Keys';
+import type { ZLinkLocationOwnerToken } from './Writes';
+declare const zlinkAuthorityKeyBrand: unique symbol;
+declare const zlinkAuthorityVersionBrand: unique symbol;
+declare const zlinkAggregateIdBrand: unique symbol;
+export interface ZLinkAuthorityKey {
+    readonly value: string;
+    readonly [zlinkAuthorityKeyBrand]: true;
+}
+export interface ZLinkAuthorityStoreVersion {
+    readonly value: string;
+    readonly [zlinkAuthorityVersionBrand]: true;
+}
+export type ZLinkPlacementObjectKind = 'actor' | 'user_spot' | 'instance_spot';
+export type ZLinkPlacementAllocationState = 'reserved' | 'active';
+export interface ZLinkSpotTypeCapacityDelta {
+    readonly objectKind: 'user_spot' | 'instance_spot';
+    readonly stableType: string;
+    readonly count: number;
+}
+export interface ZLinkCapacityVector {
+    readonly actors: number;
+    readonly spots: number;
+    readonly spotType?: ZLinkSpotTypeCapacityDelta;
+}
+export interface ZLinkPlacementAllocation {
+    readonly state: ZLinkPlacementAllocationState;
+    readonly objectKind: ZLinkPlacementObjectKind;
+    readonly stableType: string;
+    readonly descriptor: ZLinkMeshNodeDescriptorKey;
+    readonly descriptorLifecycleGeneration: bigint;
+    readonly capacity: ZLinkCapacityVector;
+}
+export interface ZLinkPendingObjectCreation {
+    readonly reservationId: string;
+    readonly requestContentReference: string;
+    readonly requestSha256: Uint8Array;
+    readonly requestEncodedSize: bigint;
+}
+/** Immutable creation reservation projected by an authority snapshot. */
+export interface ZLinkReservedObjectCreation extends ZLinkPendingObjectCreation {
+}
+export interface ZLinkAuthoritySnapshot {
+    readonly kind: 'snapshot';
+    readonly storeVersion: ZLinkAuthorityStoreVersion;
+    readonly payload: Uint8Array;
+    readonly objectGeneration: bigint;
+    readonly authorityOwnerGeneration: bigint;
+    readonly ownerId: string;
+    readonly ownerLeaseGeneration: bigint;
+    readonly allocation: ZLinkPlacementAllocation;
+    readonly pendingCreation?: ZLinkPendingObjectCreation;
+    readonly storeNow: Date;
+}
+export type ZLinkAuthorityReadResult = {
+    readonly kind: 'missing';
+    readonly storeNow: Date;
+} | ZLinkAuthoritySnapshot;
+export type ZLinkAuthorityMutation = {
+    readonly kind: 'put';
+    readonly payload: Uint8Array;
+    readonly generationTransition: 'preserve';
+} | {
+    /** Rebinds an authority retained by the same owner after lease recovery. */
+    readonly kind: 'rebindOwnerLease';
+    readonly payload: Uint8Array;
+    readonly expectedOwner: ZLinkLocationOwnerToken;
+    readonly targetOwner: ZLinkLocationOwnerToken;
+} | {
+    readonly kind: 'restore';
+    readonly payload: Uint8Array;
+    readonly expectedOwner: ZLinkLocationOwnerToken;
+} | {
+    readonly kind: 'delete';
+};
+export type ZLinkAuthorityCompareExchangeResult = ({
+    readonly kind: 'stored';
+} & Omit<ZLinkAuthoritySnapshot, 'kind'>) | {
+    readonly kind: 'deleted';
+    readonly storeVersion: ZLinkAuthorityStoreVersion;
+    readonly storeNow: Date;
+} | {
+    readonly kind: 'conflict';
+    readonly current: ZLinkAuthorityReadResult;
+} | {
+    readonly kind: 'generationExhausted';
+};
+export interface ZLinkAuthorityEntry {
+    readonly key: ZLinkAuthorityKey;
+    readonly snapshot: ZLinkAuthoritySnapshot;
+}
+export declare class ZLinkAuthorityScanCursor {
+    readonly encoded: string;
+    private constructor();
+    static from(encoded: string): ZLinkAuthorityScanCursor;
+}
+export interface ZLinkAuthorityPage {
+    readonly kind: 'page';
+    readonly items: readonly ZLinkAuthorityEntry[];
+    readonly nextCursor?: ZLinkAuthorityScanCursor;
+}
+export type ZLinkAuthorityScanResult = ZLinkAuthorityPage | {
+    readonly kind: 'scanExpired';
+};
+export interface ZLinkObjectCreationKey {
+    readonly kind: ZLinkPlacementObjectKind;
+    readonly globalId: string;
+}
+export interface ZLinkObjectCreationTarget {
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly nodeLifecycleGeneration: bigint;
+    readonly owner: ZLinkLocationOwnerToken;
+}
+export interface ZLinkObjectCreationIntent {
+    readonly stableType: string;
+    readonly requestContentReference: string;
+    readonly requestSha256: Uint8Array;
+    readonly requestEncodedSize: bigint;
+}
+export interface ZLinkCreationOperationId {
+    readonly high: bigint;
+    readonly low: bigint;
+}
+export interface ZLinkCreationOperationIdentity {
+    readonly sourceNodeRid: RoutingId;
+    readonly sourceNodeGeneration: bigint;
+    readonly operationId: ZLinkCreationOperationId;
+}
+export type ZLinkCreationTerminalState = 'created' | 'rejected' | 'failed';
+export interface ZLinkCreationTerminalPublication {
+    readonly operation: ZLinkCreationOperationIdentity;
+    readonly terminalEnvelope: Uint8Array;
+    readonly terminalEnvelopeSha256: Uint8Array;
+    /**
+     * The original operation deadline. Providers retain the terminal for five
+     * minutes after this absolute instant.
+     */
+    readonly operationDeadline: Date;
+}
+export interface ZLinkCreationTerminalRecord {
+    readonly state: ZLinkCreationTerminalState;
+    readonly operation: ZLinkCreationOperationIdentity;
+    readonly reservationId: string;
+    readonly objectKind: ZLinkPlacementObjectKind;
+    readonly terminalEnvelope: Uint8Array;
+    readonly terminalEnvelopeSha256: Uint8Array;
+    readonly expiresAt: Date;
+    readonly storeNow: Date;
+}
+export type ZLinkCreationTerminalReadResult = {
+    readonly kind: 'missing';
+    readonly storeNow: Date;
+} | {
+    readonly kind: 'found';
+    readonly record: ZLinkCreationTerminalRecord;
+};
+export interface ZLinkObjectReserveRequest {
+    readonly key: ZLinkObjectCreationKey;
+    readonly intent: ZLinkObjectCreationIntent;
+    readonly target: ZLinkObjectCreationTarget;
+    readonly creatingPayload: Uint8Array;
+    readonly capacity: ZLinkCapacityVector;
+}
+export type ZLinkObjectReserveResult = {
+    readonly kind: 'reserved';
+    readonly reservationId: string;
+    readonly creating: ZLinkAuthoritySnapshot;
+} | {
+    readonly kind: 'alreadyExists';
+    readonly current: ZLinkAuthoritySnapshot;
+} | {
+    readonly kind: 'typeMismatch';
+    readonly current: ZLinkAuthoritySnapshot;
+} | {
+    readonly kind: 'placementCapacityExhausted';
+} | {
+    readonly kind: 'conflict';
+    readonly current: ZLinkAuthorityReadResult;
+} | {
+    readonly kind: 'generationExhausted';
+};
+export interface ZLinkObjectCommitRequest {
+    readonly key: ZLinkObjectCreationKey;
+    readonly reservationId: string;
+    readonly expectedStoreVersion: string;
+    readonly target: ZLinkObjectCreationTarget;
+    readonly readyPayload: Uint8Array;
+}
+export type ZLinkObjectCommitResult = {
+    readonly kind: 'committed';
+    readonly ready: ZLinkAuthoritySnapshot;
+} | {
+    readonly kind: 'alreadyCommitted';
+    readonly ready: ZLinkAuthoritySnapshot;
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'generationExhausted';
+};
+export type ZLinkObjectCreationCompletion = {
+    readonly kind: 'created';
+    readonly readyPayload: Uint8Array;
+    readonly terminal: ZLinkCreationTerminalPublication;
+} | {
+    readonly kind: 'rejected' | 'failed';
+    readonly terminal: ZLinkCreationTerminalPublication;
+};
+export interface ZLinkObjectCreationCompleteRequest {
+    readonly key: ZLinkObjectCreationKey;
+    readonly reservationId: string;
+    readonly expectedStoreVersion: string;
+    readonly target: ZLinkObjectCreationTarget;
+    readonly completion: ZLinkObjectCreationCompletion;
+}
+export type ZLinkObjectCreationCompleteResult = {
+    readonly kind: 'created';
+    readonly ready: ZLinkAuthoritySnapshot;
+    readonly terminal: ZLinkCreationTerminalRecord;
+} | {
+    readonly kind: 'rejected' | 'failed' | 'alreadyCompleted';
+    readonly terminal: ZLinkCreationTerminalRecord;
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'generationExhausted';
+};
+export interface ZLinkObjectAbortRequest {
+    readonly key: ZLinkObjectCreationKey;
+    readonly reservationId: string;
+    readonly expectedStoreVersion: string;
+    readonly target: ZLinkObjectCreationTarget;
+}
+export type ZLinkObjectAbortResult = {
+    readonly kind: 'aborted';
+} | {
+    readonly kind: 'alreadyAborted';
+} | {
+    readonly kind: 'stale';
+};
+export interface ZLinkAggregateId {
+    readonly value: string;
+    readonly [zlinkAggregateIdBrand]: true;
+}
+export interface ZLinkAggregateParticipant {
+    readonly authorityKey: ZLinkAuthorityKey;
+    readonly expectedStoreVersion: ZLinkAuthorityStoreVersion;
+    readonly ownerTransition: 'preserve' | 'newOwner';
+    readonly authorityPayload: Uint8Array;
+    readonly membershipMutation: Uint8Array;
+}
+export interface ZLinkAggregatePrepareRequest {
+    readonly aggregateId: ZLinkAggregateId;
+    readonly aggregateGeneration: bigint;
+    readonly participants: readonly ZLinkAggregateParticipant[];
+    readonly inventoryDigest: Uint8Array;
+    readonly targetDescriptor: ZLinkMeshNodeDescriptorKey;
+    readonly targetDescriptorLifecycleGeneration: bigint;
+    readonly capacity: ZLinkCapacityVector;
+    readonly targetOwner: ZLinkLocationOwnerToken;
+}
+export interface ZLinkAggregateFence {
+    readonly aggregateId: ZLinkAggregateId;
+    readonly aggregateGeneration: bigint;
+}
+export type ZLinkAggregatePrepareResult = {
+    readonly kind: 'prepared';
+    readonly fence: ZLinkAggregateFence;
+} | {
+    readonly kind: 'alreadyPrepared';
+    readonly fence: ZLinkAggregateFence;
+} | {
+    readonly kind: 'conflict';
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'generationExhausted';
+};
+export type ZLinkAggregateCommitResult = {
+    readonly kind: 'committed';
+} | {
+    readonly kind: 'alreadyCommitted';
+} | {
+    readonly kind: 'stale';
+} | {
+    readonly kind: 'generationExhausted';
+};
+export type ZLinkAggregateAbortResult = {
+    readonly kind: 'aborted';
+} | {
+    readonly kind: 'alreadyAborted';
+} | {
+    readonly kind: 'stale';
+};
+export {};

package/dist/contracts/Locations/Authority.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkAuthorityScanCursor = void 0;
+class ZLinkAuthorityScanCursor {
+    encoded;
+    constructor(encoded) {
+        this.encoded = encoded;
+    }
+    static from(encoded) {
+        const byteLength = Buffer.byteLength(encoded, 'utf8');
+        if (byteLength < 1 || byteLength > 4096) {
+            throw new RangeError('Authority scan cursor must contain 1..4096 UTF-8 bytes.');
+        }
+        return new ZLinkAuthorityScanCursor(encoded);
+    }
+}
+exports.ZLinkAuthorityScanCursor = ZLinkAuthorityScanCursor;

package/dist/contracts/Locations/Diagnostics.d.ts

@@ -0,0 +1,42 @@
+import type { RoutingId } from '../Common';
+export interface ZLinkLocationRuntimeStatus {
+    readonly storeHealthy: boolean;
+    readonly watchEnabled: boolean;
+    readonly pollingIntervalMs: number;
+    readonly lastRefreshAt?: Date;
+    readonly lastError?: string;
+    readonly ownerLeaseHealthy: boolean;
+    readonly ownerLeaseRenewedAt?: Date;
+}
+export declare enum ZLinkLocationTopologyState {
+    Discovered = 1,
+    Connecting = 2,
+    Ready = 3,
+    Lost = 4,
+    Error = 5,
+    Stopped = 6
+}
+export interface ZLinkLocationTopologyFilter {
+    readonly meshName?: string;
+    readonly nodeRid?: RoutingId;
+    readonly state?: ZLinkLocationTopologyState;
+}
+export interface ZLinkLocationTopologyEntry {
+    readonly meshName: string;
+    readonly nodeRid: RoutingId;
+    readonly endpoint: string;
+    readonly draining: boolean;
+    readonly state: ZLinkLocationTopologyState;
+    readonly updatedAt: Date;
+}
+export interface ZLinkLocationServiceSummaryFilter {
+    readonly meshName?: string;
+}
+export interface ZLinkLocationServiceSummary {
+    readonly meshName: string;
+    readonly totalCount: number;
+    readonly readyCount: number;
+    readonly errorCount: number;
+    readonly stoppedCount: number;
+    readonly lastUpdatedAt: Date;
+}

package/dist/contracts/Locations/Diagnostics.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZLinkLocationTopologyState = void 0;
+var ZLinkLocationTopologyState;
+(function (ZLinkLocationTopologyState) {
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Discovered"] = 1] = "Discovered";
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Connecting"] = 2] = "Connecting";
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Ready"] = 3] = "Ready";
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Lost"] = 4] = "Lost";
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Error"] = 5] = "Error";
+    ZLinkLocationTopologyState[ZLinkLocationTopologyState["Stopped"] = 6] = "Stopped";
+})(ZLinkLocationTopologyState || (exports.ZLinkLocationTopologyState = ZLinkLocationTopologyState = {}));