@zlink-systems/framework 0.10.0

package/src/contracts/Handlers/IZLinkChannelHandlers.ts

@@ -0,0 +1,69 @@
+import type { ZLinkActor } from '../Actors';
+import type { ZLinkEntrySpot } from '../Spots';
+import type { ZLinkTimerTick } from '../Timers';
+import type {
+  ZLinkMessageContext,
+  ZLinkPublishMessageContext,
+  ZLinkRouteMessageContext
+} from './Contexts';
+
+export interface ZLinkRequestHandler<TRequest, TResponse> {
+  handle(request: TRequest, context: ZLinkMessageContext): Promise<TResponse>;
+}
+
+export interface ZLinkSendHandler<TMessage> {
+  handle(message: TMessage, context: ZLinkMessageContext): Promise<void>;
+}
+
+export interface ZLinkRouteSendHandler<TMessage> {
+  handle(message: TMessage, context: ZLinkRouteMessageContext): Promise<void>;
+}
+
+export interface ZLinkRouteRequestHandler<TRequest, TReply> {
+  handle(request: TRequest, context: ZLinkRouteMessageContext): Promise<TReply>;
+}
+
+export interface ZLinkFanoutHandler<TMessage> {
+  handle(message: TMessage, context: ZLinkPublishMessageContext): Promise<void>;
+}
+
+export interface ZLinkSpotPacketHandler<TSpot, TMessage> {
+  handle(spot: TSpot, message: TMessage, context: ZLinkMessageContext): Promise<void>;
+}
+
+export interface ZLinkSpotRequestHandler<TSpot, TRequest, TReply> {
+  handle(spot: TSpot, request: TRequest, context: ZLinkMessageContext): Promise<TReply>;
+}
+
+export interface ZLinkSpotSubscriptionHandler<TSpot, TEvent> {
+  handle(spot: TSpot, event: TEvent, context: ZLinkPublishMessageContext): Promise<void>;
+}
+
+export interface ZLinkSpotTimerHandler<TSpot> {
+  handle(spot: TSpot, tick: ZLinkTimerTick): Promise<void>;
+}
+
+export interface ZLinkSpotActorSendHandler<TSpot, TActor extends ZLinkActor, TMessage> {
+  handle(spot: TSpot, actor: TActor, context: ZLinkMessageContext, message: TMessage): Promise<void>;
+}
+
+export interface ZLinkSpotActorRequestHandler<TSpot, TActor extends ZLinkActor, TRequest, TReply> {
+  handle(spot: TSpot, actor: TActor, context: ZLinkMessageContext, request: TRequest): Promise<TReply>;
+}
+
+export interface ZLinkEntrySpotActorSendHandler<
+  TEntrySpot extends ZLinkEntrySpot<TActor>,
+  TActor extends ZLinkActor,
+  TMessage
+> {
+  handle(spot: TEntrySpot, actor: TActor, context: ZLinkMessageContext, message: TMessage): Promise<void>;
+}
+
+export interface ZLinkEntrySpotActorRequestHandler<
+  TEntrySpot extends ZLinkEntrySpot<TActor>,
+  TActor extends ZLinkActor,
+  TRequest,
+  TReply
+> {
+  handle(spot: TEntrySpot, actor: TActor, context: ZLinkMessageContext, request: TRequest): Promise<TReply>;
+}

package/src/contracts/Handlers/IZLinkHandlerFilter.ts

@@ -0,0 +1,22 @@
+import type { ZLinkHandlerFilterNext } from './ZLinkHandlerFilterNext';
+import type { ZLinkMessageContext } from './Contexts';
+
+export enum ZLinkHandlerDispatchKind {
+  NodeDirectSend = 'nodeDirectSend',
+  NodeDirectRequest = 'nodeDirectRequest',
+  ChannelSend = 'channelSend',
+  ChannelRequest = 'channelRequest',
+  ClassicFanout = 'classicFanout'
+}
+
+export interface ZLinkHandlerFilterContext extends ZLinkMessageContext {
+  readonly dispatchKind: ZLinkHandlerDispatchKind;
+}
+
+export interface ZLinkHandlerFilter {
+  invoke(
+    context: ZLinkHandlerFilterContext,
+    next: ZLinkHandlerFilterNext,
+    signal?: AbortSignal
+  ): Promise<void>;
+}

package/src/contracts/Handlers/JsonContract.ts

@@ -0,0 +1,172 @@
+/** 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;
+}
+
+const ZLINK_PACKET_JSON_CONTRACTS = Symbol.for('@zlink-systems/framework:packet-json-contracts');
+
+export function defineZLinkPacketJsonContract(
+  packetName: string,
+  contract: ZLinkPacketJsonContract
+): ZLinkPacketJsonContract {
+  if (packetName.trim().length === 0) {
+    throw new TypeError('ZLink packet name must not be empty.');
+  }
+  const runtimeContract: unknown = contract;
+  if (typeof runtimeContract !== 'object' || runtimeContract === null) {
+    throw new TypeError('ZLink packet JSON contract must be an object.');
+  }
+  const normalizedContract = runtimeContract as ZLinkPacketJsonContract;
+  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;
+}
+
+export function readZLinkPacketJsonContract(packetName: string): ZLinkPacketJsonContract | undefined {
+  return packetJsonContracts().get(packetName);
+}
+
+function normalizeJsonSchema(
+  schema: ZLinkJsonSchema,
+  parents: Set<object>,
+  depth: number
+): ZLinkJsonSchema {
+  // Keep the runtime boundary defensive for JavaScript callers even though
+  // the TypeScript signature describes the accepted shape.
+  const runtimeSchema: unknown = 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 as ZLinkJsonSchema;
+  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: unknown = 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: Record<string, ZLinkJsonSchema> = {};
+      for (const [name, property] of Object.entries(runtimeProperties as Record<string, ZLinkJsonSchema>)) {
+        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 as { type?: unknown }).type)}' is not supported.`);
+}
+
+function packetJsonContracts(): Map<string, ZLinkPacketJsonContract> {
+  const root = globalThis as typeof globalThis & Record<symbol, unknown>;
+  let contracts = root[ZLINK_PACKET_JSON_CONTRACTS] as Map<string, ZLinkPacketJsonContract> | undefined;
+  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: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonicalContract).join(',')}]`;
+  if (typeof value !== 'object' || value === null) return JSON.stringify(value);
+  return `{${Object.entries(value as Record<string, unknown>)
+    .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+    .map(([key, item]) => `${JSON.stringify(key)}:${canonicalContract(item)}`)
+    .join(',')}}`;
+}

package/src/contracts/Handlers/ZLinkHandlerFilterNext.ts

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

package/src/contracts/Handlers/index.ts

@@ -0,0 +1,17 @@
+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/src/contracts/Locations/ActorTransfer.ts

@@ -0,0 +1,84 @@
+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/src/contracts/Locations/Authority.ts

@@ -0,0 +1,308 @@
+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 class ZLinkAuthorityScanCursor {
+  private constructor(readonly encoded: string) {}
+
+  static from(encoded: string): ZLinkAuthorityScanCursor {
+    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);
+  }
+}
+
+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' };