@zlink-systems/framework 0.19.0 → 0.21.0

package/dist/runtime/locations/in-memory-authority-store.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ZLinkInMemoryAuthorityStore = void 0;
 const node_crypto_1 = require("node:crypto");
 const authority_key_codec_1 = require("./authority-key-codec");
+const opaque_record_key_1 = require("./opaque-record-key");
 const MAX_GENERATION = 0x7fffffffffffffffn;
 const MAX_PAYLOAD_BYTES = 1024 * 1024;
 const CREATION_TERMINAL_RETENTION_MS = 5 * 60 * 1000;
@@ -278,7 +279,7 @@ class ZLinkInMemoryAuthorityStore {
         if (request.completion.kind === 'created') {
             validatePayload(request.completion.readyPayload);
         }
-        const terminalRecord = validateTerminalForMutation(request.completion.terminal, request.completion.kind, request.reservationId, request.key.kind, this.now());
+        const terminalRecord = validateTerminalForMutation(request.completion.terminal, this.now());
         const existingTerminal = this.operationTerminals.get(creationOperationKey(terminalRecord.operation));
         if (existingTerminal !== undefined
             && existingTerminal.expiresAt.getTime() > this.now().getTime()) {
@@ -352,7 +353,7 @@ class ZLinkInMemoryAuthorityStore {
             this.operationTerminals.delete(key);
             return { kind: 'missing', storeNow: this.now() };
         }
-        return { kind: 'found', record: copyTerminalRecord(record) };
+        return { kind: 'found', terminalEnvelope: Buffer.from(record.terminalEnvelope) };
     }
     creationTerminalAvailable(record) {
         const key = creationOperationKey(record.operation);
@@ -634,7 +635,7 @@ function validateCreationOperation(operation) {
         throw new TypeError('Creation terminal source node RID must contain 1..255 UTF-8 bytes without NUL.');
     }
     if (operation.sourceNodeGeneration < 1n
-        || operation.sourceNodeGeneration > MAX_GENERATION
+        || operation.sourceNodeGeneration > MAX_U64
         || operation.operationId.high < 0n
         || operation.operationId.high > MAX_U64
         || operation.operationId.low < 0n
@@ -643,17 +644,12 @@ function validateCreationOperation(operation) {
         throw new RangeError('Creation terminal source generation and operation ID are invalid.');
     }
 }
-function validateTerminalForMutation(publication, state, reservationId, objectKind, storeNow) {
+function validateTerminalForMutation(publication, storeNow) {
     if (publication === undefined)
         return undefined;
     validateCreationOperation(publication.operation);
-    if (publication.terminalEnvelope.byteLength > MAX_PAYLOAD_BYTES
-        || publication.terminalEnvelopeSha256.byteLength !== 32) {
-        throw new RangeError('Creation terminal envelope must not exceed 1 MiB and requires a SHA-256 digest.');
-    }
-    const actualSha = (0, node_crypto_1.createHash)('sha256').update(publication.terminalEnvelope).digest();
-    if (!(0, node_crypto_1.timingSafeEqual)(actualSha, Buffer.from(publication.terminalEnvelopeSha256))) {
-        throw new TypeError('Creation terminal envelope SHA-256 does not match its bytes.');
+    if (publication.terminalEnvelope.byteLength > MAX_PAYLOAD_BYTES) {
+        throw new RangeError('Creation terminal envelope must not exceed 1 MiB.');
     }
     const deadlineMs = publication.operationDeadline.getTime();
     const expiresAtMs = deadlineMs + CREATION_TERMINAL_RETENTION_MS;
@@ -663,23 +659,14 @@ function validateTerminalForMutation(publication, state, reservationId, objectKi
         throw new RangeError('Creation terminal expiry must be the live operation deadline plus five minutes.');
     }
     return {
-        state,
         operation: copyCreationOperation(publication.operation),
-        reservationId: requireText(reservationId, 'creation reservation ID'),
-        objectKind,
         terminalEnvelope: Buffer.from(publication.terminalEnvelope),
-        terminalEnvelopeSha256: Buffer.from(publication.terminalEnvelopeSha256),
         expiresAt: new Date(expiresAtMs),
         storeNow: new Date(storeNow.getTime())
     };
 }
 function creationOperationKey(operation) {
-    return [
-        String(operation.sourceNodeRid),
-        operation.sourceNodeGeneration.toString(),
-        operation.operationId.high.toString(16).padStart(16, '0'),
-        operation.operationId.low.toString(16).padStart(16, '0')
-    ].join('\0');
+    return (0, opaque_record_key_1.creationTerminalPreimage)(operation);
 }
 function copyCreationOperation(operation) {
     return {
@@ -696,7 +683,6 @@ function copyTerminalRecord(record) {
         ...record,
         operation: copyCreationOperation(record.operation),
         terminalEnvelope: Buffer.from(record.terminalEnvelope),
-        terminalEnvelopeSha256: Buffer.from(record.terminalEnvelopeSha256),
         expiresAt: new Date(record.expiresAt),
         storeNow: new Date(record.storeNow)
     };

package/dist/runtime/locations/location-store-repository.js

@@ -7,6 +7,7 @@ const contracts_1 = require("../../contracts");
 const Locations_1 = require("../../contracts/Locations");
 const in_memory_location_store_1 = require("./in-memory-location-store");
 const in_memory_provider_location_store_1 = require("./in-memory-provider-location-store");
+const opaque_record_key_1 = require("./opaque-record-key");
 const authority_key_codec_1 = require("./authority-key-codec");
 const aggregate_inventory_store_1 = require("./aggregate-inventory-store");
 const routing_id_1 = require("../routing-id");
@@ -840,7 +841,6 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 capacity: cloneCapacity(request.capacity)
             };
             const record = {
-                reservationId,
                 snapshot: {
                     payload: Buffer.from(request.creatingPayload),
                     objectGeneration: generation,
@@ -909,14 +909,14 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 return { kind: 'stale' };
             const record = decodeAuthorityRecord(current.value.bytes);
             if (record.terminal === 'committed'
-                && record.reservationId === request.reservationId
+                && record.snapshot.pendingCreation === undefined
                 && record.snapshot.allocation.state === 'active') {
                 return {
                     kind: 'alreadyCommitted',
                     ready: authoritySnapshot(record.snapshot, current.value.version, current.value.storeNow)
                 };
             }
-            if (record.reservationId !== request.reservationId
+            if (record.snapshot.pendingCreation?.reservationId !== request.reservationId
                 || current.value.version.value !== request.expectedStoreVersion
                 || record.snapshot.allocation.state !== 'reserved'
                 || !sameCreationTarget(record.snapshot, request.target)) {
@@ -937,7 +937,6 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 ? emptyCapacityRecord()
                 : decodeJson(capacityRead.value.bytes);
             const ready = {
-                reservationId: request.reservationId,
                 terminal: 'committed',
                 snapshot: {
                     ...record.snapshot,
@@ -985,7 +984,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             if (current.kind === 'missing')
                 return { kind: 'stale' };
             const record = decodeAuthorityRecord(current.value.bytes);
-            if (record.reservationId !== request.reservationId
+            if (record.snapshot.pendingCreation?.reservationId !== request.reservationId
                 || current.value.version.value !== request.expectedStoreVersion
                 || record.snapshot.allocation.state !== 'reserved'
                 || !sameCreationTarget(record.snapshot, request.target)) {
@@ -1047,13 +1046,13 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             if (existingTerminal.kind === 'found') {
                 return {
                     kind: 'alreadyCompleted',
-                    terminal: reviveCreationTerminal(decodeJson(existingTerminal.value.bytes))
+                    terminal: retainedCreationTerminal(terminal.operation, existingTerminal.value.bytes, existingTerminal.value.expiresAt, existingTerminal.value.storeNow)
                 };
             }
             if (current.kind === 'missing')
                 return { kind: 'stale' };
             const record = decodeAuthorityRecord(current.value.bytes);
-            if (record.reservationId !== request.reservationId
+            if (record.snapshot.pendingCreation?.reservationId !== request.reservationId
                 || current.value.version.value !== request.expectedStoreVersion
                 || record.snapshot.allocation.state !== 'reserved'
                 || !sameCreationTarget(record.snapshot, request.target)) {
@@ -1088,7 +1087,6 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                         kind: 'put',
                         key: rowKey,
                         bytes: encodeAuthorityRecord({
-                            reservationId: request.reservationId,
                             terminal: 'committed',
                             snapshot: {
                                 ...record.snapshot,
@@ -1131,7 +1129,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                     {
                         kind: 'put',
                         key: terminalRowKey,
-                        bytes: encodeJson(terminalAtStore),
+                        bytes: terminalAtStore.terminalEnvelope,
                         retentionMs
                     }
                 ]
@@ -1150,7 +1148,6 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                 throw new Error('Actor creation completion did not return an authority row version.');
             }
             const readyRecord = decodeAuthorityRecord(encodeAuthorityRecord({
-                reservationId: request.reservationId,
                 terminal: 'committed',
                 snapshot: {
                     ...record.snapshot,
@@ -1173,7 +1170,7 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
             ? { kind: 'missing', storeNow: result.storeNow }
             : {
                 kind: 'found',
-                record: reviveCreationTerminal(decodeJson(result.value.bytes))
+                terminalEnvelope: Buffer.from(result.value.bytes)
             };
     }
     async claimOwnerLease(ownerId, leaseTtlMs, signal) {
@@ -1569,11 +1566,12 @@ class ZLinkLocationStoreRepository extends in_memory_location_store_1.ZLinkInMem
                     removed += 1n;
                 continue;
             }
-            if (record.reservationId === undefined)
+            const reservationId = record.snapshot.pendingCreation?.reservationId;
+            if (reservationId === undefined)
                 continue;
             const aborted = await this.abort({
                 key: identity,
-                reservationId: record.reservationId,
+                reservationId,
                 expectedStoreVersion: current.value.version.value,
                 target: {
                     meshName: record.snapshot.allocation.descriptor.meshName,
@@ -2286,12 +2284,12 @@ function sha256Hex(bytes) {
 // literal NUL bytes -- the same scheme the opaque record store hashes with
 // SHA-256 to derive the Redis key -- so a runtime in one language can read a
 // record another language wrote. Not used for framework-internal-only rows
-// (aggregate/capacity/creation-terminal/spot/actor/route), which stay on the
-// legacy PREFIX scheme since they aren't part of the public opaque contract.
+// (aggregate/capacity/spot/actor/route), which stay on the legacy PREFIX
+// scheme since they aren't part of the public opaque contract.
 function ownerKey(ownerId) {
-    return (0, in_memory_provider_location_store_1.storeKey)(`owner-lease\0${requireNoNul(ownerId, 'OwnerId')}`);
+    return (0, in_memory_provider_location_store_1.storeKey)((0, opaque_record_key_1.opaqueRecordPreimage)('owner-lease', requireNoNul(ownerId, 'OwnerId')));
 }
-const AUTHORITY_PREIMAGE_PREFIX = 'authority\0';
+const AUTHORITY_PREIMAGE_PREFIX = `${(0, opaque_record_key_1.opaqueRecordPreimage)('authority')}\0`;
 function authorityKey(value) {
     return (0, in_memory_provider_location_store_1.storeKey)(authorityPreimage(value));
 }
@@ -2300,7 +2298,7 @@ function authorityPreimage(value) {
     // §2.3: Entry|User|Instance Spot kinds share one segment ("spot") -- one
     // Id has exactly one authority row regardless of spot kind.
     const segment = decoded.kind === 'actor' ? 'actor' : 'spot';
-    return `${AUTHORITY_PREIMAGE_PREFIX}${segment}\0${requireNoNul(decoded.globalId, 'Authority Id')}`;
+    return (0, opaque_record_key_1.opaqueRecordPreimage)('authority', segment, requireNoNul(decoded.globalId, 'Authority Id'));
 }
 // Reverses authorityPreimage(): recovers the framework-internal zla1-encoded
 // ZLinkAuthorityKey contract value from a scanned opaque record's logical
@@ -2351,35 +2349,25 @@ function capacityKey(meshName, nodeRid) {
 }
 function creationTerminalKey(operation) {
     validateCreationOperation(operation);
-    return (0, in_memory_provider_location_store_1.storeKey)(`${PREFIX}creation-terminal:${[
-        String(operation.sourceNodeRid),
-        operation.sourceNodeGeneration.toString(),
-        operation.operationId.high.toString(16).padStart(16, '0'),
-        operation.operationId.low.toString(16).padStart(16, '0')
-    ].map(encodeURIComponent).join(':')}`);
+    return (0, in_memory_provider_location_store_1.storeKey)((0, opaque_record_key_1.creationTerminalPreimage)(operation));
 }
 function meshPrefix(meshName) {
-    return `mesh-node\0${requireNoNul(meshName, 'MeshName')}\0`;
+    return `${(0, opaque_record_key_1.opaqueRecordPreimage)('mesh-node', requireNoNul(meshName, 'MeshName'))}\0`;
 }
 function meshKey(meshName, nodeRid) {
-    return (0, in_memory_provider_location_store_1.storeKey)(`${meshPrefix(meshName)}${routingIdHexSegment(nodeRid)}`);
+    return (0, in_memory_provider_location_store_1.storeKey)((0, opaque_record_key_1.opaqueRecordPreimage)('mesh-node', requireNoNul(meshName, 'MeshName'), (0, opaque_record_key_1.routingIdHexSegment)(nodeRid)));
 }
 function clientServerPrefix(channelName) {
-    return `client-server\0${requireNoNul(channelName, 'ChannelName')}\0`;
+    return `${(0, opaque_record_key_1.opaqueRecordPreimage)('client-server', requireNoNul(channelName, 'ChannelName'))}\0`;
 }
 function clientServerKey(channelName, serverRid) {
-    return (0, in_memory_provider_location_store_1.storeKey)(`${clientServerPrefix(channelName)}${routingIdHexSegment(serverRid)}`);
-}
-// {hex(RoutingId)}: lowercase hex of the RoutingId's raw bytes
-// (21-location-runtime.md#2.4).
-function routingIdHexSegment(rid) {
-    return (0, routing_id_1.encodeRoutingIdStorageHex)(rid).toLowerCase();
+    return (0, in_memory_provider_location_store_1.storeKey)((0, opaque_record_key_1.opaqueRecordPreimage)('client-server', requireNoNul(channelName, 'ChannelName'), (0, opaque_record_key_1.routingIdHexSegment)(serverRid)));
 }
 function fanoutPrefix(channelName) {
-    return `fanout-publisher\0${requireNoNul(channelName, 'ChannelName')}\0`;
+    return `${(0, opaque_record_key_1.opaqueRecordPreimage)('fanout-publisher', requireNoNul(channelName, 'ChannelName'))}\0`;
 }
 function fanoutKey(channelName, publisherRid) {
-    return (0, in_memory_provider_location_store_1.storeKey)(`${fanoutPrefix(channelName)}${routingIdHexSegment(publisherRid)}`);
+    return (0, in_memory_provider_location_store_1.storeKey)((0, opaque_record_key_1.opaqueRecordPreimage)('fanout-publisher', requireNoNul(channelName, 'ChannelName'), (0, opaque_record_key_1.routingIdHexSegment)(publisherRid)));
 }
 function spotKey(meshName, spotId) {
     return (0, in_memory_provider_location_store_1.storeKey)(`${PREFIX}spot:${encodeURIComponent(meshName)}:${encodeURIComponent(spotId)}`);
@@ -2651,8 +2639,6 @@ function encodeAuthorityRecord(record) {
     // These fields gate Node-only creation/aggregate recovery.  They are absent
     // from normal authority values (including the golden vector), while the
     // interoperable envelope above remains byte-canonical.
-    if (record.reservationId !== undefined)
-        envelope.reservationId = record.reservationId;
     if (record.terminal !== undefined)
         envelope.terminal = record.terminal;
     if (record.aggregate !== undefined)
@@ -2670,7 +2656,6 @@ function decodeAuthorityRecord(bytes) {
     const pending = value.pendingCreation;
     const objectKind = runtimePlacementObjectKind(String(allocation.objectKind));
     return {
-        reservationId: typeof value.reservationId === 'string' ? value.reservationId : undefined,
         terminal: value.terminal,
         aggregate: value.aggregate === undefined
             ? undefined
@@ -2755,13 +2740,8 @@ function runtimeSpotPlacementObjectKind(kind) {
 function createTerminalRecord(request, now) {
     const publication = request.completion.terminal;
     validateCreationOperation(publication.operation);
-    if (publication.terminalEnvelope.byteLength > MAX_CREATION_TERMINAL_BYTES
-        || publication.terminalEnvelopeSha256.byteLength !== 32) {
-        throw new RangeError('Creation terminal envelope must not exceed 1 MiB and requires a SHA-256 digest.');
-    }
-    const actualSha = (0, node_crypto_1.createHash)('sha256').update(publication.terminalEnvelope).digest();
-    if (!(0, node_crypto_1.timingSafeEqual)(actualSha, Buffer.from(publication.terminalEnvelopeSha256))) {
-        throw new TypeError('Creation terminal envelope SHA-256 does not match its bytes.');
+    if (publication.terminalEnvelope.byteLength > MAX_CREATION_TERMINAL_BYTES) {
+        throw new RangeError('Creation terminal envelope must not exceed 1 MiB.');
     }
     const deadlineMs = publication.operationDeadline.getTime();
     const expiresAtMs = deadlineMs + CREATION_TERMINAL_RETENTION_MS;
@@ -2774,32 +2754,29 @@ function createTerminalRecord(request, now) {
         validatePayloadSize(request.completion.readyPayload, 'Actor ready payload');
     }
     return {
-        state: request.completion.kind,
         operation: {
             sourceNodeRid: publication.operation.sourceNodeRid,
             sourceNodeGeneration: publication.operation.sourceNodeGeneration,
             operationId: { ...publication.operation.operationId }
         },
-        reservationId: requireText(request.reservationId, 'creation reservation ID'),
-        objectKind: request.key.kind,
         terminalEnvelope: Buffer.from(publication.terminalEnvelope),
-        terminalEnvelopeSha256: Buffer.from(publication.terminalEnvelopeSha256),
         expiresAt: new Date(expiresAtMs),
         storeNow: new Date(now)
     };
 }
-function reviveCreationTerminal(record) {
+function retainedCreationTerminal(operation, terminalEnvelope, expiresAt, storeNow) {
+    if (expiresAt === undefined) {
+        throw new Error('Retained creation terminal is missing its expiration.');
+    }
     return {
-        ...record,
         operation: {
-            ...record.operation,
-            sourceNodeRid: String(record.operation.sourceNodeRid),
-            operationId: { ...record.operation.operationId }
+            sourceNodeRid: operation.sourceNodeRid,
+            sourceNodeGeneration: operation.sourceNodeGeneration,
+            operationId: { ...operation.operationId }
         },
-        terminalEnvelope: Buffer.from(record.terminalEnvelope),
-        terminalEnvelopeSha256: Buffer.from(record.terminalEnvelopeSha256),
-        expiresAt: reviveDate(record.expiresAt),
-        storeNow: reviveDate(record.storeNow)
+        terminalEnvelope: Buffer.from(terminalEnvelope),
+        expiresAt: new Date(expiresAt),
+        storeNow: new Date(storeNow)
     };
 }
 function validateCreationOperation(operation) {
@@ -2809,7 +2786,7 @@ function validateCreationOperation(operation) {
         throw new TypeError('Creation terminal source node RID must contain 1..255 UTF-8 bytes without NUL.');
     }
     if (operation.sourceNodeGeneration < 1n
-        || operation.sourceNodeGeneration > MAX_GENERATION
+        || operation.sourceNodeGeneration > MAX_U64
         || operation.operationId.high < 0n
         || operation.operationId.high > MAX_U64
         || operation.operationId.low < 0n

package/dist/runtime/locations/opaque-record-key.d.ts

@@ -0,0 +1,5 @@
+import type { RoutingId } from '../../contracts/Common/CoreTypes';
+import type { ZLinkCreationOperationIdentity } from './internal-location-contracts';
+export declare function opaqueRecordPreimage(record: string, ...segments: readonly string[]): string;
+export declare function creationTerminalPreimage(operation: ZLinkCreationOperationIdentity): string;
+export declare function routingIdHexSegment(routingId: RoutingId): string;

package/dist/runtime/locations/opaque-record-key.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.opaqueRecordPreimage = opaqueRecordPreimage;
+exports.creationTerminalPreimage = creationTerminalPreimage;
+exports.routingIdHexSegment = routingIdHexSegment;
+const routing_id_1 = require("../routing-id");
+function opaqueRecordPreimage(record, ...segments) {
+    return [record, ...segments].join('\0');
+}
+function creationTerminalPreimage(operation) {
+    return opaqueRecordPreimage('creation-terminal', routingIdHexSegment(operation.sourceNodeRid), operation.sourceNodeGeneration.toString(), operation.operationId.high.toString(16).padStart(16, '0')
+        + operation.operationId.low.toString(16).padStart(16, '0'));
+}
+function routingIdHexSegment(routingId) {
+    return (0, routing_id_1.encodeRoutingIdStorageHex)(routingId).toLowerCase();
+}

package/dist/runtime/locations/runtime.d.ts

@@ -57,6 +57,10 @@ export interface ZLinkLocationEventSink {
 export declare class ZLinkOwnerCleanupError extends Error {
     constructor(cause: unknown);
 }
+export declare class ZLinkOwnerLeaseClaimError extends Error {
+    readonly kind: 'conflict' | 'generationExhausted';
+    constructor(kind: 'conflict' | 'generationExhausted');
+}
 export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     readonly ownerId: string;
     private readonly options;
@@ -90,6 +94,7 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     get isStarted(): boolean;
     get nodeRid(): RoutingId | undefined;
     get currentOwnerToken(): ZLinkLocationOwnerToken | undefined;
+    closeOwnerLeaseAdmission(error: unknown): void;
     reclaimOwnerAuthorities(signal?: AbortSignal): Promise<void>;
     private readAllAuthorityEntries;
     addOwnershipLostHandler(handler: (event: ZLinkOwnershipLostEvent) => void): void;
@@ -103,6 +108,8 @@ export declare class ZLinkLocationRuntime implements ZLinkLocationRuntimeQuery {
     cleanupOwner(signal?: AbortSignal): Promise<void>;
     renewOwnerLeaseOnce(signal?: AbortSignal): Promise<boolean>;
     private claimFreshOwnerLease;
+    private claimOwnerLeaseWithConfirmation;
+    private confirmOwnerLease;
     private setOwnerLeaseDeadline;
     publishDraining(signal?: AbortSignal): Promise<boolean>;
     writeMeshNode(descriptor: Omit<ZLinkMeshNodeDescriptor, 'ownerId' | 'leaseGeneration' | 'updatedAt'>, intent: ZLinkLocationWriteIntent, signal?: AbortSignal): Promise<ZLinkLocationWriteResult>;