@zlink-systems/framework 0.25.0 → 0.27.0

package/src/runtime/locations/in-memory-provider-location-store.ts

@@ -9,6 +9,17 @@ import type {
   ZLinkStoreWriteRequest,
   ZLinkStoreWriteResult
 } from '../../contracts';
+import {
+  ZLINK_PROVIDER_MAX_KEY_BYTES,
+  ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES,
+  ZLINK_PROVIDER_MAX_PAGE_SIZE,
+  ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES,
+  ZLINK_PROVIDER_MAX_VALUE_BYTES,
+  ZLINK_PROVIDER_MAX_VERSION_BYTES,
+  ZLINK_PROVIDER_MAX_WRITE_BYTES,
+  ZLINK_PROVIDER_MAX_WRITE_KEYS
+} from '../../contracts/Locations/Stores';
+export const PROVIDER_STORAGE_NAMESPACE_PREFIX = 'zlink:v11:';
 
 interface StoredValue {
   readonly bytes: Uint8Array;
@@ -59,6 +70,13 @@ export class ZLinkInMemoryProviderLocationStore implements ZLinkLocationStore {
       const current = this.liveValue(condition.key.value, storeNow);
       if (condition.kind === 'missing') {
         if (current !== undefined) return { kind: 'conflict', storeNow };
+      } else if (condition.kind === 'value') {
+        if (
+          current === undefined ||
+          !Buffer.from(current.bytes).equals(Buffer.from(condition.expected))
+        ) {
+          return { kind: 'conflict', storeNow };
+        }
       } else if (current?.version.value !== condition.expected.value) {
         return { kind: 'conflict', storeNow };
       }
@@ -70,12 +88,11 @@ export class ZLinkInMemoryProviderLocationStore implements ZLinkLocationStore {
         this.values.delete(mutation.key.value);
         continue;
       }
-      requireValue(mutation.bytes, mutation.retentionMs);
+      const retentionMs =
+        mutation.retentionMs === undefined ? undefined : Math.ceil(mutation.retentionMs);
       const version = storeVersion((++this.nextVersion).toString());
       const expiresAt =
-        mutation.retentionMs === undefined
-          ? undefined
-          : new Date(storeNow.getTime() + mutation.retentionMs);
+        retentionMs === undefined ? undefined : new Date(storeNow.getTime() + retentionMs);
       this.values.set(mutation.key.value, {
         bytes: mutation.bytes.slice(),
         version,
@@ -105,13 +122,26 @@ export class ZLinkInMemoryProviderLocationStore implements ZLinkLocationStore {
       };
       this.scans.set(snapshotId, snapshot);
     } else {
-      [snapshotId, offset] = parseCursor(request.cursor);
+      const cursor = parseCursor(request.cursor);
+      snapshotId = cursor?.[0] ?? '';
+      offset = cursor?.[1] ?? 0;
       snapshot = this.scans.get(snapshotId);
-      if (snapshot === undefined) return { kind: 'expired' };
+      if (snapshot === undefined || offset > snapshot.items.length) return { kind: 'expired' };
     }
 
-    const selected = snapshot.items.slice(offset, offset + request.limit);
-    const nextOffset = offset + selected.length;
+    let nextOffset = offset;
+    let encodedBytes = 0;
+    while (nextOffset < snapshot.items.length && nextOffset - offset < request.limit) {
+      const item = snapshot.items[nextOffset];
+      const itemBytes =
+        Buffer.byteLength(item.key.value, 'utf8') +
+        Buffer.byteLength(item.value.version.value, 'utf8') +
+        item.value.bytes.byteLength;
+      if (encodedBytes + itemBytes > ZLINK_PROVIDER_MAX_ENCODED_PAGE_BYTES) break;
+      encodedBytes += itemBytes;
+      nextOffset += 1;
+    }
+    const selected = snapshot.items.slice(offset, nextOffset);
     const nextCursor =
       nextOffset < snapshot.items.length ? scanCursor(`${snapshotId}:${nextOffset}`) : undefined;
     if (nextCursor === undefined) this.scans.delete(snapshotId);
@@ -155,12 +185,13 @@ function scanCursor(value: string): ZLinkStoreScanCursor {
   return { value } as ZLinkStoreScanCursor;
 }
 
-function parseCursor(cursor: ZLinkStoreScanCursor): [string, number] {
+function parseCursor(cursor: ZLinkStoreScanCursor): [string, number] | undefined {
   const separator = cursor.value.indexOf(':');
   const snapshotId = cursor.value.slice(0, separator);
-  const offset = Number(cursor.value.slice(separator + 1));
-  if (separator < 1 || !Number.isSafeInteger(offset) || offset < 0) {
-    throw new RangeError('Location Store scan cursor is invalid.');
+  const encodedOffset = cursor.value.slice(separator + 1);
+  const offset = Number(encodedOffset);
+  if (separator < 1 || !/^(0|[1-9][0-9]*)$/.test(encodedOffset) || !Number.isSafeInteger(offset)) {
+    return undefined;
   }
   return [snapshotId, offset];
 }
@@ -172,41 +203,89 @@ function requireWriteRequest(request: ZLinkStoreWriteRequest): void {
   if (
     new Set(conditionKeys).size !== conditionKeys.length ||
     new Set(mutationKeys).size !== mutationKeys.length ||
-    keys.length > 2_048
+    keys.length > ZLINK_PROVIDER_MAX_WRITE_KEYS
   ) {
-    throw new RangeError('Location Store write keys must be unique and bounded to 2,048.');
+    throw new RangeError(
+      `Location Store write keys must be unique and bounded to ${ZLINK_PROVIDER_MAX_WRITE_KEYS.toLocaleString('en-US')}.`
+    );
   }
   for (const key of keys) requireKey(key);
-  const encodedSize = request.mutations.reduce(
-    (sum, mutation) => sum + (mutation.kind === 'put' ? mutation.bytes.byteLength : 0),
-    0
-  );
-  if (encodedSize > 4 * 1024 * 1024) {
-    throw new RangeError('Location Store write exceeds 4 MiB.');
+  const encodedSize =
+    request.conditions.reduce((sum, condition) => {
+      const keyBytes = Buffer.byteLength(condition.key.value, 'utf8');
+      if (condition.kind === 'missing') return sum + keyBytes;
+      if (condition.kind === 'value') {
+        requireValue(condition.expected, undefined);
+        return sum + keyBytes + condition.expected.byteLength;
+      }
+      const versionBytes = Buffer.byteLength(condition.expected.value, 'utf8');
+      if (versionBytes < 1 || versionBytes > ZLINK_PROVIDER_MAX_VERSION_BYTES) {
+        throw new RangeError(
+          `Location Store version must contain 1..${ZLINK_PROVIDER_MAX_VERSION_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+        );
+      }
+      return sum + keyBytes + versionBytes;
+    }, 0) +
+    request.mutations.reduce((sum, mutation) => {
+      const keyBytes = Buffer.byteLength(mutation.key.value, 'utf8');
+      if (mutation.kind !== 'put') return sum + keyBytes;
+      requireValue(mutation.bytes, mutation.retentionMs);
+      return sum + keyBytes + mutation.bytes.byteLength;
+    }, 0);
+  if (encodedSize > ZLINK_PROVIDER_MAX_WRITE_BYTES) {
+    throw new RangeError(
+      `Location Store write exceeds ${ZLINK_PROVIDER_MAX_WRITE_BYTES / (1024 * 1024)} MiB.`
+    );
   }
 }
 
 function requireScanRequest(request: ZLinkStoreScanRequest): void {
-  if (Buffer.byteLength(request.prefix, 'utf8') > 1_024) {
-    throw new RangeError('Location Store scan prefix exceeds 1,024 UTF-8 bytes.');
+  if (request.cursor !== undefined) {
+    const bytes = Buffer.byteLength(request.cursor.value, 'utf8');
+    if (bytes < 1 || bytes > ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES) {
+      throw new RangeError(
+        `Location Store cursor must contain 1..${ZLINK_PROVIDER_MAX_SCAN_CURSOR_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+      );
+    }
   }
-  if (!Number.isSafeInteger(request.limit) || request.limit < 1 || request.limit > 1_000) {
-    throw new RangeError('Location Store scan limit must be in 1..1000.');
+  if (Buffer.byteLength(request.prefix, 'utf8') > ZLINK_PROVIDER_MAX_KEY_BYTES) {
+    throw new RangeError(
+      `Location Store scan prefix exceeds ${ZLINK_PROVIDER_MAX_KEY_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
+  }
+  if (
+    !Number.isSafeInteger(request.limit) ||
+    request.limit < 1 ||
+    request.limit > ZLINK_PROVIDER_MAX_PAGE_SIZE
+  ) {
+    throw new RangeError(
+      `Location Store scan limit must be in 1..${ZLINK_PROVIDER_MAX_PAGE_SIZE}.`
+    );
   }
 }
 
-function requireValue(bytes: Uint8Array, retentionMs: number | undefined): void {
-  if (bytes.byteLength > 1024 * 1024) {
-    throw new RangeError('Location Store value exceeds 1 MiB.');
+function requireValue(bytes: Uint8Array, retentionMs: number | undefined): number | undefined {
+  if (bytes.byteLength > ZLINK_PROVIDER_MAX_VALUE_BYTES) {
+    throw new RangeError(
+      `Location Store value exceeds ${ZLINK_PROVIDER_MAX_VALUE_BYTES / (1024 * 1024)} MiB.`
+    );
   }
-  if (retentionMs !== undefined && (!Number.isSafeInteger(retentionMs) || retentionMs < 1)) {
-    throw new RangeError('Location Store retention must be a positive safe integer.');
+  if (
+    retentionMs !== undefined &&
+    (!Number.isFinite(retentionMs) ||
+      retentionMs <= 0 ||
+      !Number.isSafeInteger(Math.ceil(retentionMs)))
+  ) {
+    throw new RangeError('Location Store retention must round to a positive safe integer.');
   }
+  return retentionMs === undefined ? undefined : Math.ceil(retentionMs);
 }
 
 function requireKey(value: string): void {
   const bytes = Buffer.byteLength(value, 'utf8');
-  if (bytes < 1 || bytes > 1_024) {
-    throw new RangeError('Location Store key must contain 1..1,024 UTF-8 bytes.');
+  if (bytes < 1 || bytes > ZLINK_PROVIDER_MAX_KEY_BYTES) {
+    throw new RangeError(
+      `Location Store key must contain 1..${ZLINK_PROVIDER_MAX_KEY_BYTES.toLocaleString('en-US')} UTF-8 bytes.`
+    );
   }
 }

package/src/runtime/locations/key-codec.ts

@@ -1,3 +1,4 @@
+import { ZLINK_MAX_SPOT_ID_BYTES } from '../../contracts/Common/CoreTypes';
 import type { RoutingId } from '../../contracts/Common';
 import {
   type ZLinkActorLocationKey,
@@ -49,8 +50,8 @@ function encodeSegments(...segments: readonly string[]): string {
 
 function requireSpotId(value: string): string {
   const bytes = Buffer.byteLength(value, 'utf8');
-  if (bytes < 1 || bytes > 255) {
-    throw new TypeError('SpotId must contain 1..255 UTF-8 bytes.');
+  if (bytes < 1 || bytes > ZLINK_MAX_SPOT_ID_BYTES) {
+    throw new TypeError(`SpotId must contain 1..${ZLINK_MAX_SPOT_ID_BYTES} UTF-8 bytes.`);
   }
   return value;
 }

package/src/runtime/locations/lease-tracker.ts

@@ -79,6 +79,10 @@ export class ZLinkOwnerLeaseTracker {
     );
   }
 
+  async isOwnerTokenLive(owner: ZLinkLocationOwnerToken, signal?: AbortSignal): Promise<boolean> {
+    return (await this.remainingOwnerTokenLeaseMs(owner, signal)) > 0;
+  }
+
   async getLiveOwnerSetVersion(signal?: AbortSignal): Promise<number> {
     const owners = await this.lane.run(() => [...this.snapshots.keys()]);
     const refreshed = await Promise.all(owners.map((ownerId) => this.getSnapshot(ownerId, signal)));
@@ -187,17 +191,15 @@ export class ZLinkOwnerLeaseTracker {
 }
 
 export class ZLinkLiveRowFilter {
-  constructor(private readonly leaseTracker: ZLinkOwnerLeaseTracker) {}
-
   async filter<TRow>(
     rows: readonly TRow[],
-    ownerIdOf: (row: TRow) => string,
+    isLive: (row: TRow, signal?: AbortSignal) => Promise<boolean>,
     signal?: AbortSignal,
     include?: (row: TRow) => boolean
   ): Promise<TRow[]> {
     const live: TRow[] = [];
     for (const row of rows) {
-      if ((include === undefined || include(row)) && (await this.isLive(row, ownerIdOf, signal))) {
+      if ((include === undefined || include(row)) && (await isLive(row, signal))) {
         live.push(row);
       }
     }
@@ -206,22 +208,14 @@ export class ZLinkLiveRowFilter {
 
   async resolve<TRow>(
     row: TRow | undefined,
-    ownerIdOf: (row: TRow) => string,
+    isLive: (row: TRow, signal?: AbortSignal) => Promise<boolean>,
     signal?: AbortSignal,
     include?: (row: TRow) => boolean
   ): Promise<TRow | undefined> {
     if (row === undefined || (include !== undefined && !include(row))) {
       return undefined;
     }
-    return (await this.isLive(row, ownerIdOf, signal)) ? row : undefined;
-  }
-
-  private async isLive<TRow>(
-    row: TRow,
-    ownerIdOf: (row: TRow) => string,
-    signal?: AbortSignal
-  ): Promise<boolean> {
-    return await this.leaseTracker.isOwnerLive(ownerIdOf(row), signal);
+    return (await isLive(row, signal)) ? row : undefined;
   }
 }
 

package/src/runtime/locations/lifecycle.ts

@@ -1,33 +1,34 @@
 import type { ActorRef, RoutingId } from '../../contracts/Common';
-import type { ZLinkActorLocation, ZLinkLocationWriteStatus } from './internal-location-contracts';
-import type { ZLinkActorLocationStore, ZLinkSpotLocationStore } from './internal-store-contracts';
 import { ZLinkSpotKind } from '../../contracts/Spots';
 import {
   ZLinkActorLocationClaims,
   type ZLinkActorClaimActivation,
   type ZLinkActorClaimResult
 } from './actor-location-claims';
+import { ZLinkActorSessionRouteClaims } from './actor-session-route-claims';
+import type { ZLinkActorLocation, ZLinkLocationWriteStatus } from './internal-location-contracts';
+import type {
+  ZLinkActorLocationStore,
+  ZLinkAuthorityStore,
+  ZLinkSpotLocationStore
+} from './internal-store-contracts';
+import type { IZLinkLocationLifecycleRuntime, ZLinkOwnershipLostEvent } from './lifecycle-runtime';
+import {
+  type ZLinkInstanceClosingAuthority,
+  type ZLinkTrackedInstanceAuthority,
+  ZLinkSpotLocationClaims
+} from './spot-location-claims';
 export {
   ZLinkActorClaimStatus,
   type ZLinkActorClaimActivation,
   type ZLinkActorClaimResult
 } from './actor-location-claims';
-import { ZLinkActorSessionRouteClaims } from './actor-session-route-claims';
-import { ZLinkSpotLocationClaims } from './spot-location-claims';
-import type {
-  ZLinkInstanceClosingAuthority,
-  ZLinkTrackedInstanceAuthority
-} from './spot-location-claims';
-import type { ZLinkAuthorityStore } from './internal-store-contracts';
-import type { IZLinkLocationLifecycleRuntime, ZLinkOwnershipLostEvent } from './lifecycle-runtime';
 export type { IZLinkLocationLifecycleRuntime, ZLinkOwnershipLostEvent } from './lifecycle-runtime';
 
 export class ZLinkLocationLifecycle {
   private readonly actorClaims: ZLinkActorLocationClaims;
-  private readonly actorCleanupTasks = new Map<string, Promise<void>>();
   private readonly spotClaims: ZLinkSpotLocationClaims;
   private readonly actorSessionRoutes: ZLinkActorSessionRouteClaims;
-  private disposed = false;
   private readonly ownershipLostHandler = (event: ZLinkOwnershipLostEvent) =>
     this.onOwnershipLost(event);
 
@@ -56,7 +57,6 @@ export class ZLinkLocationLifecycle {
   }
 
   dispose(): void {
-    this.disposed = true;
     this.runtime.removeOwnershipLostHandler(this.ownershipLostHandler);
   }
 
@@ -160,18 +160,6 @@ export class ZLinkLocationLifecycle {
     await this.actorClaims.release(actorType, actorId, actorRef);
   }
 
-  releaseActorEventually(actorType: string, actorId: string): Promise<void> {
-    const existing = this.actorCleanupTasks.get(actorId);
-    if (existing !== undefined) {
-      return existing;
-    }
-    const cleanup = this.retryActorRelease(actorType, actorId).finally(() =>
-      this.actorCleanupTasks.delete(actorId)
-    );
-    this.actorCleanupTasks.set(actorId, cleanup);
-    return cleanup;
-  }
-
   ownsActor(actorType: string, actorId: string): boolean {
     return this.actorClaims.owns(actorType, actorId);
   }
@@ -180,20 +168,6 @@ export class ZLinkLocationLifecycle {
     return this.actorClaims.snapshot(actorId);
   }
 
-  private async retryActorRelease(actorType: string, actorId: string): Promise<void> {
-    let retryDelayMs = 50;
-    while (!this.disposed) {
-      try {
-        await this.actorClaims.release(actorType, actorId);
-        return;
-      } catch {
-        await waitForRetry(retryDelayMs);
-        retryDelayMs = Math.min(retryDelayMs * 2, 1_000);
-      }
-    }
-    return;
-  }
-
   async claimSpot(
     meshName: string,
     spotId: RoutingId,
@@ -226,9 +200,10 @@ export class ZLinkLocationLifecycle {
 
   async beginInstanceSpotClosing(
     meshName: string,
-    spotId: RoutingId
+    spotId: RoutingId,
+    onCommitted: () => void
   ): Promise<ZLinkInstanceClosingAuthority | undefined> {
-    return await this.spotClaims.beginInstanceClosing(meshName, spotId);
+    return await this.spotClaims.beginInstanceClosing(meshName, spotId, onCommitted);
   }
 
   trackInstanceSpot(input: ZLinkTrackedInstanceAuthority): void {
@@ -271,7 +246,3 @@ function inferSpotStore(actorStore: ZLinkActorLocationStore): ZLinkSpotLocationS
   }
   return undefined;
 }
-
-function waitForRetry(delayMs: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, delayMs));
-}

package/src/runtime/locations/location-store-failure.ts

@@ -0,0 +1,4 @@
+/** Location Store §6: caller validation is terminal; provider failures may lose a result. */
+export function isIndeterminateLocationStoreFailure(error: unknown, signal?: AbortSignal): boolean {
+  return !(error instanceof TypeError || error instanceof RangeError) && signal?.aborted !== true;
+}

package/src/runtime/locations/location-store-pages.ts

@@ -0,0 +1,18 @@
+import type { ZLinkMeshNodeDescriptor } from '../../contracts/Locations/Models';
+import type { ZLinkMeshNodeLocationStore } from './internal-store-contracts';
+
+export async function listAllMeshNodeDescriptors(
+  store: ZLinkMeshNodeLocationStore,
+  meshName: string,
+  signal?: AbortSignal,
+  pageSize?: number
+): Promise<readonly ZLinkMeshNodeDescriptor[]> {
+  const rows: ZLinkMeshNodeDescriptor[] = [];
+  let continuationToken: string | undefined;
+  do {
+    const result = await store.listMeshNodes(meshName, { pageSize, continuationToken }, signal);
+    rows.push(...result.items);
+    continuationToken = result.continuationToken;
+  } while (continuationToken !== undefined);
+  return rows;
+}