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

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   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
+
+       http://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.

package/README.md

@@ -0,0 +1,373 @@
+# Deploy a Spine TS application on GCE
+
+`@spine-event-engine/deployment-gce` helps you run one Spine TS application
+across several Google Compute Engine (GCE) virtual machines. It includes an
+editable Terraform template and small TypeScript entrypoints. The template
+keeps application nodes, the Gateway, and the simple delivery server private;
+you provide the public TLS, authentication, and traffic-routing edge that fits
+your organisation.
+
+This experimental snapshot package is for operators who already own
+the application images and their Google Cloud environment. Install its library
+API when writing the application or Gateway entrypoints:
+
+```bash
+pnpm add @spine-event-engine/deployment-gce@snapshot
+```
+
+Copy the packaged Terraform directory into your deployment repository only
+when you want its GCE reference topology; installing the library neither
+creates cloud resources nor configures your application Gateway, authentication,
+sessions, secrets, or storage.
+
+For exact discovery, lease, and lifecycle behavior, read the
+[deployment reference](REFERENCE.md).
+
+## Before you begin
+
+You need an existing Google Cloud project, VPC network, regional subnetwork,
+and a service account with only the permissions required by your images and
+their application configuration. Install [Google Cloud CLI](https://cloud.google.com/sdk/docs/install)
+and Terraform 1.6 or newer. Authenticate Terraform through Application Default
+Credentials:
+
+```bash
+gcloud auth application-default login
+```
+
+Build and publish three immutable images: your application, one standalone
+Gateway, and the in-memory simple delivery server. Use image digests such as
+`@sha256:...`, not mutable tags. The template deliberately does not publish an
+image, choose Datastore, MySQL, or another storage backend, create secrets, or
+configure an identity provider.
+
+## First Terraform plan
+
+Copy the packaged template into an operator-owned deployment repository. The
+following commands assume its Terraform directory is your current directory;
+create a values file and obtain a validated plan before wiring advanced Gateway
+or registry behavior:
+
+```bash
+cp terraform.tfvars.example terraform.tfvars
+terraform init
+terraform fmt -check
+terraform validate
+terraform plan -var-file=terraform.tfvars
+```
+
+Replace every placeholder with your existing project, network, service account,
+and immutable image digests before `plan`. A plan showing only private Spine
+resources is the first success; review it before any `terraform apply`.
+
+## What this deployment creates
+
+The application managed instance group (MIG) is regional and distributes
+identical application nodes across your selected zones. A ready node registers
+its private listener in a durable application registry. The single
+Gateway reads the same registry every 10 seconds and routes commands, queries,
+and subscriptions to the live nodes.
+
+```mermaid
+flowchart LR
+  Edge["Your TLS and authentication edge"] --> Gateway["One private Gateway"]
+  Gateway --> Registry["Durable application node registry"]
+  Registry --> Gateway
+  Gateway --> AppA["Application node A"]
+  Gateway --> AppB["Application node B"]
+  AppA --> Delivery["One in-memory simple delivery server"]
+  AppB --> Delivery
+```
+
+The template gives the Gateway and delivery server separate one-instance MIGs
+and stable private addresses behind internal passthrough load balancers. This
+is easy to inspect and lets an operator move them to separate failure or
+resource boundaries. A smaller deployment may colocate the two processes, but
+the simple delivery server remains in-memory: it is neither durable nor highly
+available.
+
+This is a fixed, single-Gateway topology. Multiple Gateways and Cloud Run are
+outside the supported offering.
+
+Every listener receives only private VPC traffic and health checks. Terraform
+does not create an external IP, public load balancer, TLS certificate,
+authentication provider, or Internet firewall rule.
+
+## Configure the template
+
+Edit the existing `terraform.tfvars` copied for the first plan and replace every placeholder. Keep it outside source
+control because it identifies your network and deployment, even though it
+contains no secret values.
+
+Set the project, region, two or more application zones, VPC/subnetwork,
+least-privilege service-account email, and the three image digests. Set
+`registry_namespace` and `registry_storage_reference` identically for
+application and Gateway images. Each entrypoint passes that reference to its
+application-supplied `registryStorage.storageFactoryFor(reference)` resolver. The
+resolver chooses the shared durable `StorageFactory`; Terraform only transports
+the reference and never chooses a storage engine.
+
+`application_secret_reference` and `gateway_secret_reference` are identifiers
+your images resolve through the selected configuration mechanism. They are passed
+as environment values only. Terraform neither reads secret values nor writes
+them into state.
+
+Grant the VM service account `roles/artifactregistry.reader` on each Artifact
+Registry repository that stores these images. The template uses the broad
+`cloud-platform` OAuth scope so Google Cloud IAM can evaluate that role; the IAM
+role, not the scope alone, authorizes image pulls.
+
+Every image must use an Artifact Registry host such as
+`us-docker.pkg.dev`. Each COS startup script extracts that exact host from its
+configured immutable image name, creates a writable Docker configuration under
+`/var/lib/spine-docker`, and runs `docker-credential-gcr configure-docker` for
+that host before it pulls the image. The helper uses the attached VM service
+account; no registry credential or key is placed in Terraform, metadata, or the
+Docker command.
+
+## Connect your application entrypoints
+
+The application image starts a managed application node. Its private VM port is
+the Node Coordinator port; managed children are complete application replicas
+on loopback and are never discoverable directly. The deployer must set both
+`application_process_count` and `delivery_shard_count` in Terraform. They are
+independent: the first selects Node processes, while the second is passed to
+your context assembly for its explicit Delivery strategy.
+
+Use the complete, tested
+[`GceApplicationEntrypoint`](examples/application.ts) instead of copying only
+its happy path. It starts the managed application, publishes the Coordinator
+only after it is ready, withdraws that lease before shutdown, and preserves
+startup or cleanup failures. Supply your complete child assembly through
+`createServer`, and pass the same environment object when testing custom
+deployment values. The framework-owned `SPINE_MANAGED_SERVER_CHILD` marker is
+read from that environment so child executions do not publish separate leases.
+
+The Gateway resolves the same storage reference and namespace through its
+environment. It manages a GCE discovery lifecycle that refreshes the complete
+live-node registry snapshot every 10 seconds, stops that schedule when the
+browser server stops, and then closes its registry. Supply browser collaborators
+in `browserOptions`. Choose one admission mode there: authenticated mode
+supplies `sessions` and may supply named durable subscription bindings; public
+mode supplies `publicAccess: true`, and the framework owns process-local
+bindings. Public mode cannot supply bindings.
+
+<!-- docs-snippet-path: packages/deployment-gce/examples/gateway.ts -->
+
+```ts
+import { LeasedNodeRegistry } from "@spine-event-engine/deployment";
+import { GceNodeDiscovery } from "@spine-event-engine/deployment-gce";
+import { BrowserServer, type BrowserServerOptions } from "@spine-event-engine/server/browser";
+
+type GatewayBrowserOptions = BrowserServerOptions extends infer Options
+  ? Options extends BrowserServerOptions
+    ? Omit<Options, "host" | "port" | "discovery">
+    : never
+  : never;
+
+import {
+  GceDeploymentSettings,
+  type DeploymentEnvironment,
+  type RegistryStorageResolver,
+} from "./deployment-settings.js";
+
+export interface GatewayOptions {
+  readonly browser: GatewayBrowserOptions;
+  readonly registryStorage: RegistryStorageResolver;
+}
+
+export const GceGatewayEntrypoint = Object.freeze({
+  async run(
+    options: GatewayOptions,
+    environment: DeploymentEnvironment = process.env,
+  ): Promise<void> {
+    const registry = new LeasedNodeRegistry({
+      factory: options.registryStorage.storageFactoryFor(
+        GceDeploymentSettings.registryStorageReference(environment),
+      ),
+      namespace: GceDeploymentSettings.registryNamespace(environment),
+    });
+    const discovery = new GceNodeDiscovery({ registry });
+    await BrowserServer.run({
+      host: "0.0.0.0",
+      port: GceDeploymentSettings.port(environment, "PORT"),
+      ...options.browser,
+      discovery,
+    });
+  },
+});
+```
+
+The complete, packaged examples are
+[`examples/application.ts`](examples/application.ts) and
+[`examples/gateway.ts`](examples/gateway.ts). They deliberately keep business
+contexts, storage configuration, identity, and (when using authenticated mode)
+durable subscription bindings in your application code. The GCE entrypoint's returned handle withdraws its
+Coordinator lease before stopping child replicas; abrupt VM loss remains covered
+by the existing lease expiry. The managed child marker is framework-owned
+process state: it makes the shared module assemble a child replica without
+creating a competing VM lease.
+
+## Deploy
+
+Initialize the provider, then make the first safe success a formatting,
+validation, and plan review. Apply only the reviewed plan.
+
+```bash
+terraform init
+terraform fmt -check
+terraform validate
+terraform plan -out=tfplan
+terraform apply tfplan
+```
+
+The plan should contain one application MIG, one Gateway MIG, one delivery MIG,
+and private load balancers only. The [reference](REFERENCE.md) records scaling,
+replacement, rollback, registry, and image-pull limits before you change those
+operations.
+
+The first VM can take several minutes to start. Autohealing waits for the
+configured startup delay (120 seconds by default) before treating a failed
+application listener as unhealthy.
+
+The template uses Container-Optimized OS and runs each image with a startup
+script. It configures the exact Artifact Registry host with
+`docker-credential-gcr`, then uses `docker run --rm --network host`. If a
+container exits, Docker removes it and the listener health check fails; the MIG
+can then repair that VM after the startup delay. Use
+`journalctl -u google-startup-scripts.service` or the VM serial-console log to
+diagnose credential-helper, startup-script, and container failures.
+
+## Verify the deployment
+
+Check that GCE created the three groups and that all intended instances become
+healthy:
+
+```bash
+gcloud compute instance-groups managed list --regions=REGION
+gcloud compute instance-groups managed list-instances spine-application --region=REGION
+terraform output gateway_private_address
+```
+
+From a trusted VPC client or your operator-managed edge, reach the returned
+Gateway address. Post a command, query its Projection, and activate a durable
+subscription. The Gateway may need one 10-second refresh interval after a
+fresh application node becomes ready.
+
+Each VM obtains a unique registration identity for its ready Coordinator,
+renews its lease every 20 seconds, and leases it for 60 seconds. A graceful
+entrypoint close withdraws that lease before it stops its managed children. A
+crash may leave a row behind temporarily, but it is ignored after expiry;
+healthy registrars perform finite cleanup.
+
+## Scale application nodes
+
+With the default `autoscaling_enabled = false`, Terraform controls manual capacity:
+
+```bash
+terraform apply -var='application_replicas=4'
+terraform apply -var='application_replicas=0'
+terraform apply -var='application_replicas=2'
+```
+
+At zero nodes, the registry becomes empty after at most the 60-second lease
+expiry. The Gateway remains alive but reports backend unavailability until a
+node returns; it keeps refreshing every 10 seconds. If an autoscaler is already
+enabled, first remove it in the same transition:
+
+```bash
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+```
+
+To let Compute Engine scale the same application version, set
+`autoscaling_enabled = true`. For `autoscaling_signal = "cpu"`,
+`autoscaling_target` is the CPU utilization target. For
+`autoscaling_signal = "monitoring"`, choose the metric name, a filter that
+selects only the intended resource and series, a metric target kind, and the
+declared `per_instance` or `whole_group` scope. A per-instance filter must set
+`resource.type = "gce_instance"`; a whole-group filter must select another
+resource type, such as `global`. Terraform validates that relationship, then
+omits the MIG size and GCE is the sole capacity owner.
+
+CPU and per-instance metrics require a running VM, so they cannot scale from
+zero. For scale-from-zero, use a `whole_group` Cloud Monitoring metric that is
+produced while no application VM exists, and set
+`autoscaling_min_replicas = 0`; otherwise use an operator action or schedule.
+Internal passthrough load-balancer utilization is not a suitable autoscaling
+signal for this topology.
+
+## Replace an application version
+
+For a compatible change, publish a new immutable application digest, set it in
+`terraform.tfvars`, and apply. The regional MIG performs a proactive rolling
+replacement with one permitted surge instance for each selected application
+zone and no planned unavailable instance. Old and new nodes can overlap, so
+they must understand the same stored data and messages during the rollout.
+
+For an incompatible business-logic or data change, first disable any enabled
+autoscaler and set application capacity to zero. Wait until the old nodes exit,
+apply the new image while capacity remains zero, then restore manual capacity
+or explicitly enable the new autoscaler. This framework does not negotiate
+compatibility. Pending Inbox work may execute under the new version, so make
+the change safe for those messages before starting it.
+
+```bash
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+test -z "$(gcloud compute instance-groups managed list-instances spine-application --region=REGION --format='value(instance)')"
+# Set the new application_image digest in terraform.tfvars.
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=2'
+```
+
+The Gateway normally stays in place during an application replacement. A
+Gateway interruption disconnects browser clients. In authenticated mode, durable
+subscription definitions survive only when the supplied named bindings use the
+same persistent application storage. Public-mode definitions are process-local
+and end with the Gateway process. Clients reconnect and issue an authoritative query.
+Replacing `gateway_image` performs its explicit one-unavailable, zero-surge
+singleton update and therefore causes that interruption. Replacing
+`delivery_image` performs the same singleton update; the supplied in-memory
+delivery server loses its state whenever its process stops.
+
+## Roll back
+
+To roll back a compatible application image, restore the prior immutable digest
+and run `terraform apply`. GCE creates the previous instance template and
+performs the same rolling update. For an incompatible rollback, disable an
+enabled autoscaler, reduce the application group to zero, wait for shutdown,
+apply the prior image, then restore manual capacity or deliberately re-enable
+autoscaling. Confirm the group is empty before applying the prior image:
+
+```bash
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+test -z "$(gcloud compute instance-groups managed list-instances spine-application --region=REGION --format='value(instance)')"
+# Restore the prior application_image digest in terraform.tfvars.
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=2'
+```
+
+## Troubleshooting
+
+| Symptom                              | Check                                                                                                                                                             |
+| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Gateway has no backend               | Confirm the application group has healthy instances, registry references and namespace match, then allow a 10-second refresh.                                     |
+| A node remains listed after a crash  | Wait up to 60 seconds for lease expiry; cleanup is finite and does not make expired nodes routable.                                                               |
+| An application VM keeps restarting   | Check the image starts its listener on `HOST=0.0.0.0` and `PORT`, and increase the startup delay only when its real startup needs it.                             |
+| A client cannot reach the Gateway    | Reach the private output from the VPC or configure a separate TLS/authentication edge; this module creates no public path.                                        |
+| Autoscaling does not wake zero nodes | CPU and per-instance metrics cannot observe an empty group; use a whole-group metric with `autoscaling_min_replicas = 0` or set a manual/scheduled minimum.       |
+| Delivery state disappeared           | The supplied delivery server is in-memory and loses state whenever it is replaced or restarted. Do not describe it as durable or highly available.                |
+| A container fails during startup     | Read `journalctl -u google-startup-scripts.service` or serial-console output; `docker run --rm` removes an exited container and health checks trigger MIG repair. |
+
+## Remove the deployment
+
+Disable any enabled autoscaler and remove application capacity first when you
+need a controlled domain shutdown, then destroy the infrastructure:
+
+```bash
+terraform apply -var='autoscaling_enabled=false' -var='application_replicas=0'
+terraform destroy
+```
+
+`terraform destroy` removes only resources created by this template. It does not
+delete the application registry, application storage, externally managed
+secrets, images, VPC, or an operator-managed public edge.

package/REFERENCE.md

@@ -0,0 +1,98 @@
+# GCE deployment reference
+
+Read the [deployment guide](README.md) before using this exact template
+contract. It supports one Gateway; Multiple-Gateway routing and Cloud Run are
+outside this offering.
+
+The library supplies discovery and entrypoint helpers. The editable Terraform
+reference is a separate operator choice, and neither it nor this package owns
+the public Gateway policy, authentication/session implementation, secrets, or
+application storage.
+
+## Deployment template
+
+The packaged `terraform` directory is an editable Google Compute Engine
+reference topology. It requires existing private network/subnetwork, service
+account, external configuration/secret identifiers, immutable image digests,
+and application-selected durable storage. It creates a regional application
+MIG, a one-instance Gateway MIG, and a one-instance in-memory delivery-server
+MIG. Internal passthrough load balancers provide stable private Gateway and
+delivery addresses. It intentionally creates no public edge, TLS certificate,
+identity provider, storage engine, secret value, Cloud Run resource, or second
+Gateway.
+
+The application group has a 120-second default autohealing startup delay. Its
+manual target size is present only when `autoscaling_enabled` is false; an
+enabled regional autoscaler is the sole owner of capacity. CPU and
+per-instance Monitoring metrics cannot revive a zero-instance group. A
+whole-group Monitoring metric can, if the operator supplies one that continues
+to exist at zero capacity.
+
+The template uses Container-Optimized OS plus a `docker run` startup script. It
+does not use the deprecated container startup agent or a
+`gce-container-declaration` metadata value. Each immutable image must use an
+Artifact Registry `*-docker.pkg.dev` host. The relevant COS startup script
+extracts that host from the image, exports a writable
+`HOME=/var/lib/spine-docker` and `DOCKER_CONFIG=$HOME/.docker`, then invokes
+`docker-credential-gcr configure-docker --registries=<exact-host>` before its
+Docker pull. This stores only credential-helper configuration; the helper uses
+the attached service account, whose repository-level
+`roles/artifactregistry.reader` and `cloud-platform` OAuth scope authorize the
+pull.
+
+## Metadata and node identity
+
+`GceMetadataService.read(signal)` requests project ID, zone, numeric instance
+ID, and `network-interfaces/0/ip` from the GCE metadata service. Every request
+uses `Metadata-Flavor: Google`; unsuccessful, empty, or malformed responses
+reject, as does cancellation. `GceMetadataProvider` is injectable for tests or
+an operator-managed metadata integration.
+
+`GceApplicationNode.create(metadata, options)` returns the stable ID
+`gce/<project>/<zone>/<numeric-instance-id>`. `port` must be a safe TCP port.
+Without an override the endpoint is private-address HTTP; an explicit canonical
+HTTP(S) endpoint and compatible TLS server name override it. No public address
+is inferred. In a managed application entrypoint, this endpoint is the
+node-local Coordinator listener. Managed child listeners are loopback-only and
+are never published. The registrar persists this identity through the
+deployment package's approved application-node lease record and typed node ID.
+
+## Registrar
+
+`new GceRegistrar(options)` requires either a ready `node` or a metadata port.
+When `node` and `metadata` are both omitted, it creates `GceMetadataService`
+automatically. It creates a UUID registration identity unless `identity` is
+supplied. The injected `scheduler`, `now`, and `deadlines` seams make timing
+deterministic. `operationTimeoutMs` is a positive safe integer and defaults to
+20,000 milliseconds.
+
+Call `start()` only after listener readiness. The initial record expires after
+60,000 milliseconds; scheduled renewal runs at 20,000-millisecond intervals.
+Initial write failure or loss leaves the registrar unconfirmed. The next cycle
+looks up the exact row: the same live identity confirms it, while absence or a
+different identity permits one conditional register attempt. Renewal and
+cleanup are serialized with this confirmation work.
+
+`close()` fences future ticks, aborts and joins admitted cooperative work, and
+conditionally removes only the matching registration identity. It must finish
+before the listener network close. A deadline never detaches an operation: the
+registrar waits for the admitted promise to settle before deletion.
+
+## Discovery
+
+`GceRegistryReader.read(signal)` reads the full live registry snapshot at its
+injected clock time, which defaults to `Date.now`. `GceNodeDiscovery` manages one
+`LeasedNodeRegistry`, wraps that reader in `ScheduledNodeDiscovery`, and is the
+Gateway-facing `NodeDiscovery`. Its production scheduler is optional and
+unref'ed; expired rows are filtered immediately, so scale-to-zero produces an
+empty membership snapshot. A later registrar makes its node discoverable and
+also resumes bounded cleanup of abandoned expired rows. Registry-read failures
+retain the Gateway's previous valid membership until a later refresh succeeds.
+
+`watch(onSnapshot)` returns a stop operation. Calling that operation or
+`close()` permanently stops future refresh scheduling, waits for any admitted
+read, and then closes the registry it created. `close()` is idempotent: callers
+share the same promise and the registry closes once. The owner still attempts
+registry closure if stopping discovery fails. It rethrows one close failure;
+when both operations fail, it rejects with an `AggregateError` containing both
+causes. Do not separately close the registry passed to `GceNodeDiscovery`.