@spine-event-engine/deployment-gce 2.0.0-snapshot.2

package/dist/discovery/gce-node-discovery.d.ts

@@ -0,0 +1,56 @@
+import { type ApplicationNode, type LeasedNodeRegistry, type NodeDiscovery, type NodeScheduler } from "@spine-event-engine/deployment";
+import type { ILogLayer } from "loglayer";
+/**
+ * Publishes GCE registry membership and closes its owned registry on stop.
+ */
+export declare class GceNodeDiscovery implements NodeDiscovery {
+    #private;
+    /**
+     * Creates a registry-backed GCE discovery owner.
+     *
+     * @param options Supplies the registry this owner closes and optional deterministic refresh seams.
+     */
+    constructor(options: GceNodeDiscoveryOptions);
+    /**
+     * Starts complete registry snapshot delivery.
+     *
+     * @param onSnapshot Receives each complete live-node snapshot.
+     * @returns Stops discovery and closes the owned registry.
+     */
+    watch(onSnapshot: (nodes: readonly ApplicationNode[]) => void): () => Promise<void>;
+    /**
+     * Stops discovery before closing the owned registry.
+     *
+     * @returns Completes after both owned resources settle.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Configures one GCE registry-backed discovery owner.
+ */
+export interface GceNodeDiscoveryOptions {
+    /**
+     * Supplies the owned leased registry.
+     */
+    readonly registry: LeasedNodeRegistry;
+    /**
+     * Returns the clock time used to evaluate registry lease expiry.
+     *
+     * @returns The current Unix time in milliseconds.
+     */
+    readonly now?: () => number;
+    /**
+     * Supplies the refresh scheduler for deterministic tests.
+     */
+    readonly scheduler?: NodeScheduler;
+    /**
+     * Supplies the refresh interval in milliseconds.
+     */
+    readonly intervalMs?: number;
+    /**
+     * Application-owned logger reserved for component-local records. The component
+     * does not retain or close the supplied logger.
+     */
+    readonly logger?: ILogLayer;
+}
+//# sourceMappingURL=gce-node-discovery.d.ts.map

package/dist/discovery/gce-node-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-node-discovery.d.ts","sourceRoot":"","sources":["../../src/discovery/gce-node-discovery.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,aAAa,EACnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAI1C;;GAEG;AACH,qBAAa,gBAAiB,YAAW,aAAa;;IAKpD;;;;OAIG;gBACS,OAAO,EAAE,uBAAuB;IAS5C;;;;;OAKG;IACH,KAAK,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,KAAK,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;IAKnF;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CA4BvB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAGtC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IAEtC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B"}

package/dist/discovery/gce-node-discovery.js

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { ScheduledNodeDiscovery, } from "@spine-event-engine/deployment";
+import { GceRegistryReader } from "../registry/gce-registry-reader.js";
+/**
+ * Publishes GCE registry membership and closes its owned registry on stop.
+ */
+export class GceNodeDiscovery {
+    #registry;
+    #discovery;
+    #closing;
+    /**
+     * Creates a registry-backed GCE discovery owner.
+     *
+     * @param options Supplies the registry this owner closes and optional deterministic refresh seams.
+     */
+    constructor(options) {
+        this.#registry = options.registry;
+        this.#discovery = new ScheduledNodeDiscovery({
+            reader: new GceRegistryReader(options.registry, options.now),
+            ...(options.scheduler === undefined ? {} : { scheduler: options.scheduler }),
+            ...(options.intervalMs === undefined ? {} : { intervalMs: options.intervalMs }),
+        });
+    }
+    /**
+     * Starts complete registry snapshot delivery.
+     *
+     * @param onSnapshot Receives each complete live-node snapshot.
+     * @returns Stops discovery and closes the owned registry.
+     */
+    watch(onSnapshot) {
+        this.#discovery.watch(onSnapshot);
+        return () => this.close();
+    }
+    /**
+     * Stops discovery before closing the owned registry.
+     *
+     * @returns Completes after both owned resources settle.
+     */
+    close() {
+        this.#closing ??= this.#close();
+        return this.#closing;
+    }
+    async #close() {
+        let discoveryError;
+        try {
+            await this.#discovery.close();
+        }
+        catch (error) {
+            discoveryError = error;
+        }
+        try {
+            await this.#registry.close();
+        }
+        catch (registryError) {
+            if (discoveryError !== undefined)
+                throw new AggregateError([this.#error(discoveryError), this.#error(registryError)], "GCE discovery and registry close both failed.");
+            throw this.#error(registryError);
+        }
+        if (discoveryError !== undefined)
+            throw this.#error(discoveryError);
+    }
+    #error(value) {
+        return value instanceof Error ? value : new Error(String(value));
+    }
+}
+//# sourceMappingURL=gce-node-discovery.js.map

package/dist/discovery/gce-node-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-node-discovery.js","sourceRoot":"","sources":["../../src/discovery/gce-node-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,sBAAsB,GAKvB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAEvE;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAClB,SAAS,CAAqB;IAC9B,UAAU,CAAyB;IAC5C,QAAQ,CAA4B;IAEpC;;;;OAIG;IACH,YAAY,OAAgC;QAC1C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,IAAI,sBAAsB,CAAC;YAC3C,MAAM,EAAE,IAAI,iBAAiB,CAAC,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC;YAC5D,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;YAC5E,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;SAChF,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAuD;QAC3D,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAClC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,MAAM,EAAE,CAAC;QAChC,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,cAAuB,CAAC;QAC5B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QAChC,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,cAAc,GAAG,KAAK,CAAC;QACzB,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QAC/B,CAAC;QAAC,OAAO,aAAsB,EAAE,CAAC;YAChC,IAAI,cAAc,KAAK,SAAS;gBAC9B,MAAM,IAAI,cAAc,CACtB,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,EACzD,+CAA+C,CAChD,CAAC;YACJ,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,cAAc,KAAK,SAAS;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,CAAC,KAAc;QACnB,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnE,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { GceMetadataService, type GceMetadata, type GceMetadataProvider, } from "./metadata/gce-metadata-service.js";
+export { GceApplicationNode, type GceApplicationNodeOptions } from "./node/application-node.js";
+export { GceNodeDiscovery, type GceNodeDiscoveryOptions } from "./discovery/gce-node-discovery.js";
+export { type GceDeadlineFactory, type GceScheduler } from "./registrar/operations.js";
+export { GceRegistrar, type GceRegistrarLifecycle, type GceRegistrarOptions, } from "./registrar/gce-registrar.js";
+export { GceRegistryReader } from "./registry/gce-registry-reader.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,mBAAmB,GACzB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,KAAK,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AACnG,OAAO,EAAE,KAAK,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACvF,OAAO,EACL,YAAY,EACZ,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACzB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+export { GceMetadataService, } from "./metadata/gce-metadata-service.js";
+export { GceApplicationNode } from "./node/application-node.js";
+export { GceNodeDiscovery } from "./discovery/gce-node-discovery.js";
+export {} from "./registrar/operations.js";
+export { GceRegistrar, } from "./registrar/gce-registrar.js";
+export { GceRegistryReader } from "./registry/gce-registry-reader.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,kBAAkB,GAGnB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAkC,MAAM,4BAA4B,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAgC,MAAM,mCAAmC,CAAC;AACnG,OAAO,EAA8C,MAAM,2BAA2B,CAAC;AACvF,OAAO,EACL,YAAY,GAGb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,mCAAmC,CAAC"}

package/dist/metadata/gce-metadata-service.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Supplies the trusted GCE metadata used to derive one stable application node.
+ */
+export interface GceMetadata {
+    /**
+     * Identifies the Google Cloud project containing the instance.
+     */
+    readonly projectId: string;
+    /**
+     * Identifies the GCE zone containing the instance.
+     */
+    readonly zone: string;
+    /**
+     * Identifies the numeric GCE instance.
+     */
+    readonly instanceId: string;
+    /**
+     * Supplies the instance's private IPv4 or IPv6 address.
+     */
+    readonly privateAddress: string;
+}
+/**
+ * Retrieves trusted instance metadata from the GCE metadata service.
+ */
+export interface GceMetadataProvider {
+    /**
+     * Reads the identity and private address of the current instance.
+     *
+     * @param signal Cancels the metadata request during registrar shutdown.
+     * @returns The validated metadata values.
+     */
+    read(signal: AbortSignal): Promise<GceMetadata>;
+}
+/**
+ * Reads GCE metadata using the required metadata-service request header.
+ */
+export declare class GceMetadataService implements GceMetadataProvider {
+    /**
+     * Reads and validates the instance identity and private address.
+     *
+     * @param signal Cancels all four metadata-service reads.
+     * @returns The normalized GCE metadata.
+     * @throws Error When a response is unsuccessful or contains invalid identity data.
+     */
+    read(signal: AbortSignal): Promise<GceMetadata>;
+}
+//# sourceMappingURL=gce-metadata-service.d.ts.map

package/dist/metadata/gce-metadata-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-metadata-service.d.ts","sourceRoot":"","sources":["../../src/metadata/gce-metadata-service.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,WAAW,WAAW;IAG1B;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;;;;OAKG;IACH,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACjD;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,mBAAmB;IAG5D;;;;;;OAMG;IACG,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;CAuCtD"}

package/dist/metadata/gce-metadata-service.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Reads GCE metadata using the required metadata-service request header.
+ */
+export class GceMetadataService {
+    // prettier-ignore
+    /**
+     * Reads and validates the instance identity and private address.
+     *
+     * @param signal Cancels all four metadata-service reads.
+     * @returns The normalized GCE metadata.
+     * @throws Error When a response is unsuccessful or contains invalid identity data.
+     */
+    async read(signal) {
+        const root = "http://metadata.google.internal/computeMetadata/v1";
+        const requests = new AbortController();
+        const requestSignal = AbortSignal.any([signal, requests.signal]);
+        const get = async (path) => {
+            const response = await fetch(`${root}/${path}`, {
+                signal: requestSignal,
+                headers: { "Metadata-Flavor": "Google" },
+            });
+            if (!response.ok)
+                throw new Error("GCE metadata request failed.");
+            return response.text();
+        };
+        const [projectId, zonePath, instanceId, privateAddress] = await Promise.all([
+            get("project/project-id"),
+            get("instance/zone"),
+            get("instance/id"),
+            get("instance/network-interfaces/0/ip"),
+        ]).catch((error) => {
+            requests.abort();
+            throw error;
+        });
+        const normalizedProjectId = projectId.trim();
+        const zone = (zonePath.split("/").at(-1) ?? "").trim();
+        const normalizedInstanceId = instanceId.trim();
+        const normalizedPrivateAddress = privateAddress.trim();
+        if (!normalizedProjectId ||
+            !zone ||
+            !/^\d+$/.test(normalizedInstanceId) ||
+            !normalizedPrivateAddress)
+            throw new Error("GCE metadata response is invalid.");
+        return {
+            projectId: normalizedProjectId,
+            zone,
+            instanceId: normalizedInstanceId,
+            privateAddress: normalizedPrivateAddress,
+        };
+    }
+}
+//# sourceMappingURL=gce-metadata-service.js.map

package/dist/metadata/gce-metadata-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-metadata-service.js","sourceRoot":"","sources":["../../src/metadata/gce-metadata-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA4CH;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC7B,kBAAkB;IAElB;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,MAAmB;QAC5B,MAAM,IAAI,GAAG,oDAAoD,CAAC;QAClE,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;QACvC,MAAM,aAAa,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjE,MAAM,GAAG,GAAG,KAAK,EAAE,IAAY,EAAE,EAAE;YACjC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,EAAE;gBAC9C,MAAM,EAAE,aAAa;gBACrB,OAAO,EAAE,EAAE,iBAAiB,EAAE,QAAQ,EAAE;aACzC,CAAC,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;YAClE,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;QACzB,CAAC,CAAC;QACF,MAAM,CAAC,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YAC1E,GAAG,CAAC,oBAAoB,CAAC;YACzB,GAAG,CAAC,eAAe,CAAC;YACpB,GAAG,CAAC,aAAa,CAAC;YAClB,GAAG,CAAC,kCAAkC,CAAC;SACxC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC;YACjB,MAAM,KAAK,CAAC;QACd,CAAC,CAAC,CAAC;QACH,MAAM,mBAAmB,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,oBAAoB,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;QAC/C,MAAM,wBAAwB,GAAG,cAAc,CAAC,IAAI,EAAE,CAAC;QACvD,IACE,CAAC,mBAAmB;YACpB,CAAC,IAAI;YACL,CAAC,OAAO,CAAC,IAAI,CAAC,oBAAoB,CAAC;YACnC,CAAC,wBAAwB;YAEzB,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,OAAO;YACL,SAAS,EAAE,mBAAmB;YAC9B,IAAI;YACJ,UAAU,EAAE,oBAAoB;YAChC,cAAc,EAAE,wBAAwB;SACzC,CAAC;IACJ,CAAC;CACF"}

package/dist/node/application-node.d.ts

@@ -0,0 +1,35 @@
+import { ApplicationNode } from "@spine-event-engine/deployment";
+import type { GceMetadata } from "../metadata/gce-metadata-service.js";
+/**
+ * Configures the reachable application endpoint derived from GCE metadata.
+ */
+export interface GceApplicationNodeOptions {
+    /**
+     * Supplies the reachable gRPC TCP port.
+     */
+    readonly port: number;
+    /**
+     * Overrides the default private HTTP origin for private DNS or a proxy.
+     */
+    readonly endpoint?: string;
+    /**
+     * Supplies the TLS authority required by an HTTPS endpoint.
+     */
+    readonly tlsServerName?: string;
+}
+/**
+ * Builds one canonical application node from trusted GCE metadata.
+ */
+export declare class GceApplicationNode {
+    /**
+     * Creates a stable GCE node using the private HTTP address by default.
+     *
+     * @param metadata Supplies trusted project, zone, numeric instance ID, and private address.
+     * @param options Supplies the port and optional canonical endpoint/TLS override.
+     * @returns A canonical application node whose ID is `gce/<project>/<zone>/<instance>`.
+     * @throws Error When metadata identity or endpoint/TLS values are invalid.
+     */
+    static create(metadata: GceMetadata, options: GceApplicationNodeOptions): ApplicationNode;
+    private static host;
+}
+//# sourceMappingURL=application-node.d.ts.map

package/dist/node/application-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-node.d.ts","sourceRoot":"","sources":["../../src/node/application-node.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,yBAAyB;IAGxC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AAEH,qBAAa,kBAAkB;IAG7B;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,WAAW,EAAE,OAAO,EAAE,yBAAyB,GAAG,eAAe;IAezF,OAAO,CAAC,MAAM,CAAC,IAAI;CAGpB"}

package/dist/node/application-node.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { ApplicationNode } from "@spine-event-engine/deployment";
+/**
+ * Builds one canonical application node from trusted GCE metadata.
+ */
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
+export class GceApplicationNode {
+    // prettier-ignore
+    /**
+     * Creates a stable GCE node using the private HTTP address by default.
+     *
+     * @param metadata Supplies trusted project, zone, numeric instance ID, and private address.
+     * @param options Supplies the port and optional canonical endpoint/TLS override.
+     * @returns A canonical application node whose ID is `gce/<project>/<zone>/<instance>`.
+     * @throws Error When metadata identity or endpoint/TLS values are invalid.
+     */
+    static create(metadata, options) {
+        if (!metadata.projectId.trim() || !metadata.zone.trim() || !/^\d+$/.test(metadata.instanceId))
+            throw new Error("GCE metadata identity is invalid.");
+        if (!Number.isSafeInteger(options.port) || options.port < 1 || options.port > 65_535)
+            throw new RangeError("GCE node port must be a valid TCP port.");
+        const endpoint = options.endpoint ??
+            `http://${GceApplicationNode.host(metadata.privateAddress)}:${String(options.port)}`;
+        return new ApplicationNode({
+            id: `gce/${metadata.projectId}/${metadata.zone}/${metadata.instanceId}`,
+            endpoint,
+            ...(options.tlsServerName === undefined ? {} : { tlsServerName: options.tlsServerName }),
+        });
+    }
+    static host(address) {
+        return address.includes(":") ? `[${address}]` : address;
+    }
+}
+//# sourceMappingURL=application-node.js.map

package/dist/node/application-node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-node.js","sourceRoot":"","sources":["../../src/node/application-node.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AA0BjE;;GAEG;AACH,kEAAkE;AAClE,MAAM,OAAO,kBAAkB;IAC7B,kBAAkB;IAElB;;;;;;;OAOG;IACH,MAAM,CAAC,MAAM,CAAC,QAAqB,EAAE,OAAkC;QACrE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC;YAC3F,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,GAAG,MAAM;YAClF,MAAM,IAAI,UAAU,CAAC,yCAAyC,CAAC,CAAC;QAClE,MAAM,QAAQ,GACZ,OAAO,CAAC,QAAQ;YAChB,UAAU,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACvF,OAAO,IAAI,eAAe,CAAC;YACzB,EAAE,EAAE,OAAO,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,UAAU,EAAE;YACvE,QAAQ;YACR,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;SACzF,CAAC,CAAC;IACL,CAAC;IAEO,MAAM,CAAC,IAAI,CAAC,OAAe;QACjC,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;IAC1D,CAAC;CACF"}

package/dist/registrar/gce-registrar-log.d.ts

@@ -0,0 +1,11 @@
+import type { ILogLayer } from "loglayer";
+/**
+ * Records a contained GCE renewal warning without changing registrar outcomes.
+ *
+ * @param logger Receives the contained record when supplied.
+ */
+export declare const gceRegistrarLog: Readonly<{
+    warnRenewal(logger: ILogLayer | undefined): void;
+    isPromiseLike(value: unknown): value is PromiseLike<unknown>;
+}>;
+//# sourceMappingURL=gce-registrar-log.d.ts.map

package/dist/registrar/gce-registrar-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-registrar-log.d.ts","sourceRoot":"","sources":["../../src/registrar/gce-registrar-log.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC;IACrC,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAAC;IACjD,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;CAC9D,CAyBC,CAAC"}

package/dist/registrar/gce-registrar-log.js

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Records a contained GCE renewal warning without changing registrar outcomes.
+ *
+ * @param logger Receives the contained record when supplied.
+ */
+export const gceRegistrarLog = Object.freeze({
+    warnRenewal(logger) {
+        if (logger === undefined)
+            return;
+        try {
+            const record = logger.withMetadata({
+                operation: "deployment.gce.registrar.renew",
+                reasonCode: "failed",
+            });
+            const emit = record.warn.bind(record);
+            const emitted = emit("deployment.gce.registrar.renew_failed");
+            if (gceRegistrarLog.isPromiseLike(emitted))
+                void Promise.resolve(emitted).catch(() => undefined);
+        }
+        catch {
+            // Logging must not affect the containing runtime outcome.
+        }
+    },
+    isPromiseLike(value) {
+        return ((typeof value === "object" || typeof value === "function") &&
+            value !== null &&
+            "then" in value &&
+            typeof value.then === "function");
+    },
+});
+//# sourceMappingURL=gce-registrar-log.js.map

package/dist/registrar/gce-registrar-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-registrar-log.js","sourceRoot":"","sources":["../../src/registrar/gce-registrar-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAGvB,MAAM,CAAC,MAAM,CAAC;IACjB,WAAW,CAAC,MAA6B;QACvC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QACjC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC;gBACjC,SAAS,EAAE,gCAAgC;gBAC3C,UAAU,EAAE,QAAQ;aACrB,CAAC,CAAC;YACH,MAAM,IAAI,GAA+B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAClE,MAAM,OAAO,GAAG,IAAI,CAAC,uCAAuC,CAAC,CAAC;YAC9D,IAAI,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC;gBACxC,KAAK,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;IAED,aAAa,CAAC,KAAc;QAC1B,OAAO,CACL,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,UAAU,CAAC;YAC1D,KAAK,KAAK,IAAI;YACd,MAAM,IAAI,KAAK;YACf,OAAQ,KAA4B,CAAC,IAAI,KAAK,UAAU,CACzD,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/registrar/gce-registrar.d.ts

@@ -0,0 +1,90 @@
+import { type ApplicationNode, type LeasedNodeRegistry } from "@spine-event-engine/deployment";
+import type { ILogLayer } from "loglayer";
+import { type GceMetadataProvider } from "../metadata/gce-metadata-service.js";
+import { type GceDeadlineFactory, type GceScheduler } from "./operations.js";
+interface GceRegistrarBaseOptions {
+    readonly registry: LeasedNodeRegistry;
+    readonly identity?: string;
+    readonly scheduler?: GceScheduler;
+    readonly now?: () => number;
+    readonly deadlines?: GceDeadlineFactory;
+    readonly operationTimeoutMs?: number;
+}
+interface ExplicitRegistrarOptions extends GceRegistrarBaseOptions {
+    readonly node: ApplicationNode;
+    readonly metadata?: never;
+    readonly port?: never;
+}
+interface MetadataRegistrarOptions extends GceRegistrarBaseOptions {
+    readonly node?: undefined;
+    readonly metadata?: GceMetadataProvider;
+    readonly port: number;
+}
+/**
+ * Configures a ready-node registrar and its deterministic test seams.
+ *
+ * Supply either an explicit node or a metadata-derived node with its port.
+ */
+export type GceRegistrarOptions = (ExplicitRegistrarOptions & {
+    /**
+     * Application-owned logger reserved for component-local records. The registrar
+     * does not retain or close the supplied logger.
+     */
+    readonly logger?: ILogLayer;
+}) | (MetadataRegistrarOptions & {
+    /**
+     * Application-owned logger reserved for component-local records. The registrar
+     * does not retain or close the supplied logger.
+     */
+    readonly logger?: ILogLayer;
+});
+/**
+ * Couples registrar lifecycle work to an application listener lifecycle.
+ */
+export interface GceRegistrarLifecycle {
+    /**
+     * Starts registration only after the listener is reachable.
+     *
+     * @returns Completes after the initial registration attempt settles.
+     */
+    start(): Promise<void>;
+    /**
+     * Removes the owned lease before listener network shutdown.
+     *
+     * @returns Completes after all admitted work and removal settle.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Registers one ready GCE node and renews its lease.
+ */
+export declare class GceRegistrar {
+    #private;
+    /**
+     * Creates a registrar with twenty-second renewal and sixty-second leases by default.
+     *
+     * @param options Supplies registry ownership, node derivation, and deterministic seams.
+     */
+    constructor(options: GceRegistrarOptions);
+    /**
+     * Starts initial registration after the listener is ready.
+     *
+     * @returns Completes after the first registration attempt has settled.
+     * @throws Error When this registrar has already closed.
+     */
+    start(): Promise<void>;
+    /**
+     * Removes this registrar's lease after fencing scheduled work.
+     *
+     * @returns Completes after admitted work settles and owned-row removal is attempted.
+     */
+    close(): Promise<void>;
+    /**
+     * Exposes listener-ready start and pre-network-close removal to a server assembly.
+     *
+     * @returns The lifecycle callbacks accepted by `Server.addListenerLifecycle()`.
+     */
+    lifecycle(): GceRegistrarLifecycle;
+}
+export {};
+//# sourceMappingURL=gce-registrar.d.ts.map

package/dist/registrar/gce-registrar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gce-registrar.d.ts","sourceRoot":"","sources":["../../src/registrar/gce-registrar.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAE/F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAGnG,OAAO,EAIL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAEzB,UAAU,uBAAuB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,UAAU,wBAAyB,SAAQ,uBAAuB;IAChE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAC1B,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CACvB;AAED,UAAU,wBAAyB,SAAQ,uBAAuB;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAC3B,CAAC,wBAAwB,GAAG;IAG1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B,CAAC,GACF,CAAC,wBAAwB,GAAG;IAG1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B,CAAC,CAAC;AAEP;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAGpC;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,qBAAa,YAAY;;IAmBvB;;;;OAIG;gBACS,OAAO,EAAE,mBAAmB;IA0BxC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;;;OAIG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAc5B;;;;OAIG;IACH,SAAS,IAAI,qBAAqB;CAyEnC"}