@serve.zone/appstore 32.27.0 → 33.1.0

package/readme.md

@@ -1,6 +1,8 @@
 # @serve.zone/appstore
 
-This repository is the curated App Store index consumed by serve.zone runtimes. It publishes `@serve.zone/appstore`, a small TypeScript client that parses and resolves App Store metadata, linked `servezone.appstore.json` manifests, and Docker digest-tracked image sources.
+The serve.zone App Store: the curated app templates, the publisher that turns them into one signed runtime catalog, and the client Onebox and Cloudly use to load that catalog at runtime.
+
+A consumer never bundles App Store data. It loads the signed catalog from an npm registry in the background, verifies it against the signing keys its own release trusts, keeps the last verified catalog as its last-known-good copy, and picks up new apps and versions without a release of its own. The App Store is never a startup blocker: while no verified catalog is active, only App Store install, upgrade and upgrade-preview are refused.
 
 ## Issue Reporting and Security
 
@@ -18,41 +20,43 @@ The client speaks the `@serve.zone/interfaces` 32 App Store contracts. The stora
 
 | File or directory | Purpose |
 | --- | --- |
-| `appstore.json` | Top-level App Store index with app IDs, display names, descriptions, categories, icons, latest versions, and tags. |
-| `apps/<app>/app.json` | App-specific metadata, maintained version list, and optional links. |
-| `apps/<app>/versions/<version>/config.json` | Deployable version definition: image, internal port, environment variables, platform requirements, and compatibility metadata. |
-| `ts_client/` | Published `@serve.zone/appstore` parser and resolver client. |
-| `source.type=repoManifest` | Optional link to a `servezone.appstore.json` file owned by the upstream app repo. |
+| `apps/<app>/app.json` | The app's catalog `info` (`id`, `name`, `description`, `category`, optional `iconName`, `iconUrl`, `tags`, `maintainer`, `links`), its `latestVersion` and the `versions` it publishes, in order. |
+| `apps/<app>/versions/<version>/config.json` | The version config: digest-pinned image, ports, environment, storage, platform requirements, compatibility minimums and upgrade flags. |
+| `apps/<app>/versions/<version>/withdrawn.json` | Present once a version is withdrawn: `{ "at", "reason" }`. A withdrawal is final. |
+| `catalog.lock.json` | The publication record: every published `app@version` with its config digest and withdrawal. It only grows. |
+| `ts_publisher/` | The catalog publisher (not published): builds `dist_catalog/`, signs it, maintains the lock. |
+| `ts_client/` | The published `@serve.zone/appstore` client: the catalog loader, catalog lookups and the storage handoff. |
+| `dist_catalog/` | Build output, published with the package: `catalog.json`, `catalog.digest` and, in a release, the signed `catalog.envelope.json`. |
 
-Changes are reviewed by reading the JSON data, running the client tests, and testing affected templates in Onebox or Cloudly.
+Nothing else may sit in an app or version folder; the publisher refuses any other file.
 
 ## Current App Store
 
-The App Store currently lists 21 app templates.
-
-| App ID | Name | App Store category | Image | Port |
-| --- | --- | --- | --- | --- |
-| `adminer` | Adminer | Dev Tools | `adminer:latest` | `8080` |
-| `cloudly` | Cloudly | Dev Tools | `code.foss.global/serve.zone/cloudly@sha256:700bb723fef408a6bf8079f643f9990247bffe6541403fd421d064ba8128a447` | `3000` |
-| `ghost` | Ghost | CMS | `ghost:latest` | `2368` |
-| `gitea` | Gitea | Dev Tools | `gitea/gitea:latest` | `3000` |
-| `gitops` | GitOps | Dev Tools | `code.foss.global/serve.zone/gitops:2.13.0` | `3000` |
-| `grafana` | Grafana | Monitoring | `grafana/grafana:latest` | `3000` |
-| `mariadb` | MariaDB | Database | `mariadb:latest` | `3306` |
-| `mattermost` | Mattermost | Communication | `mattermost/mattermost-team-edition:latest` | `8065` |
-| `n8n` | N8N | Automation | `n8nio/n8n:latest` | `5678` |
-| `nextcloud` | Nextcloud | Storage | `nextcloud:latest` | `80` |
-| `nginx` | Nginx | Web Server | `nginx:alpine` | `80` |
-| `openbao` | OpenBao | Security | `openbao/openbao:2.6.0` | `8200` |
-| `plausible` | Plausible Analytics | Analytics | `plausible/analytics:latest` | `8000` |
-| `portainer` | Portainer | Dev Tools | `portainer/portainer-ce:latest` | `9000` |
-| `postgres` | PostgreSQL | Database | `postgres:16-alpine` | `5432` |
-| `valkey` | Valkey | Database | `valkey/valkey:9.1.0-alpine` | `6379` |
-| `rustdesk-server` | RustDesk Server | Remote Access | `rustdesk/rustdesk-server-s6:latest` | `21116` |
-| `siprouter` | SIP Router | Communication | `code.foss.global/serve.zone/siprouter:1.28.0` | `3060` |
-| `uptime-kuma` | Uptime Kuma | Monitoring | `louislam/uptime-kuma:latest` | `3001` |
-| `vaultwarden` | Vaultwarden | Security | `vaultwarden/server:latest` | `80` |
-| `wordpress` | WordPress | CMS | `wordpress:latest` | `80` |
+The catalog lists 19 apps. Every image is pinned to the digest of its multi-platform index.
+
+| App ID | Name | App Store category | Latest | Image | Port |
+| --- | --- | --- | --- | --- | --- |
+| `adminer` | Adminer | Dev Tools | `1.0.0` | `adminer@sha256:74f29c416e148b98305e84446a18db7cd2c1038264dec464359d36774ef080ce` | `8080` |
+| `cloudly` | Cloudly | Dev Tools | `1.28.0` | `code.foss.global/serve.zone/cloudly@sha256:b28e53772c0148470df3a4bf57a4fcd2bcee273f002e3faa8eb71957ffd580a5` | `3000` |
+| `ghost` | Ghost | CMS | `1.0.0` | `ghost@sha256:9482099b1c8700764dc3d38c293e09c16d70f8bacc14af589c47d90b4bebd017` | `2368` |
+| `gitea` | Gitea | Dev Tools | `1.0.0` | `gitea/gitea@sha256:a9dc25679ebdd33356242d2e0667cc220043745e8339922879f187c20329a42e` | `3000` |
+| `grafana` | Grafana | Monitoring | `1.0.0` | `grafana/grafana@sha256:b28bae15e219c998fb0e0424ed724930cc61b1f61fb404d47c862f9a23f9e572` | `3000` |
+| `mariadb` | MariaDB | Database | `1.0.0` | `mariadb@sha256:f1bba652ba57bea3099ca2fe1af692af537c27d96e0bcde39dce29e2ba1ec4f3` | `3306` |
+| `mattermost` | Mattermost | Communication | `1.0.0` | `mattermost/mattermost-team-edition@sha256:6ad5912b45875ef2fafc41886b5a70a3ec1b6c17ec706e0492566e8a2fd8aa85` | `8065` |
+| `n8n` | N8N | Automation | `1.0.0` | `n8nio/n8n@sha256:240eaa2a3d491adac5817aa4c3f1c521bb18ec79f6e448517158d5220ee0f37b` | `5678` |
+| `nextcloud` | Nextcloud | Storage | `1.0.0` | `nextcloud@sha256:4ba2af4695e1801b5f66ed4df863c0fa0f236f632ffd04b2fdc32ee0c2fefe42` | `80` |
+| `nginx` | Nginx | Web Server | `1.0.0` | `nginx@sha256:df221db836e1754089190208cee7eeda94f233197056426eda74a43ab1abeac2` | `80` |
+| `openbao` | OpenBao | Security | `1.0.0` | `openbao/openbao@sha256:900bb64d0671cd1d82b693c56206f7263b582445f3a3bb6ba6e5213f524a6653` | `8200` |
+| `plausible` | Plausible Analytics | Analytics | `1.0.0` | `plausible/analytics@sha256:cd5f75e1399073669b13b4151cc603332a825324d0b8f13dfc9de9112a3c68a1` | `8000` |
+| `portainer` | Portainer | Dev Tools | `1.0.0` | `portainer/portainer-ce@sha256:4d616db18cfeb5dd41a69c0958bc825c84483ea9cde1106eb82a5d26f3bd8b0e` | `9000` |
+| `postgres` | PostgreSQL | Database | `1.0.0` | `postgres@sha256:721873c34ceb9f8d8fc265984940dc982404c105f19ad51be9fdc5970a6080ea` | `5432` |
+| `rustdesk-server` | RustDesk Server | Remote Access | `1.0.0` | `rustdesk/rustdesk-server-s6@sha256:5974cd791a5aca6fbf01a167b37e7427db1d136e95b2710c33a34fdc9fea724c` | `21116` |
+| `uptime-kuma` | Uptime Kuma | Monitoring | `1.0.0` | `louislam/uptime-kuma@sha256:70233f4acb5163fd2a59a49909cf01e44415cecff13dba69e3a86647a2919f83` | `3001` |
+| `valkey` | Valkey | Database | `1.0.0` | `valkey/valkey@sha256:c9b77919daeba2c02ad954d0c844cc4e7142069d177b89c5fd771f405daf9e02` | `6379` |
+| `vaultwarden` | Vaultwarden | Security | `1.0.0` | `vaultwarden/server@sha256:efb3cde962015fcc036b2ea625242248611943b27212ebf4392841fb30fad055` | `80` |
+| `wordpress` | WordPress | CMS | `1.0.0` | `wordpress@sha256:736761c95c327cb21602ab9175ee4dba6e779b00f3f4895536a3e1af5ac4fe4c` | `80` |
+
+Cloudly `1.0.0` and `1.1.0` are withdrawn: they were floating-tag templates (`cloudly:latest`) and stay listed, pinned to the image that tag served when the catalog was created, only so that services installed from them keep reading their config. Install `1.21.0` or later.
 
 ## Platform Requirements
 
@@ -64,12 +68,11 @@ Some templates ask Onebox to provision local platform services and inject connec
 
 | App ID | Requirements | Notes |
 | --- | --- | --- |
-| `cloudly` | MongoDB, S3 | Version `1.27.0` pins Cloudly `33.17.3` and keeps the `1.26.0` runtime contract, including the Onebox `33.8.0` minimum: its platform Corestore `32.2.4` runs NoSQLDB `10.6.1` with the D3 write-conflict fix, and on an earlier engine a node's network plan loses every commit to a `WriteConflict`, so Cloudly `33.15` must not run on it. Cloudly `33.17.3` moves the data version from `0.28.0` to `0.30.0`: every upgrade runs the forward-only data steps `route-claim-absent-owners` to `0.29.0` (the stored nulls of absent owners are removed from every route claim) and `bounded-runtime-history` to `0.30.0` (every archived deployment record is deleted, the index `archiveState_1` is dropped and the accepted Spark observations are pruned to the rows the census reads), and every Cloudly before `33.17.3` refuses the `0.30.0` data. Runtime history is bounded from then on: a Coreflow report deletes the deployment records it no longer names instead of archiving them, `getDeployments` answers the current records whether or not it is asked to `includeArchived`, `deploymentArchiveRetentionDays` is accepted but has no effect, and the dashboard no longer offers archived deployments. A deployment preflight no longer fails `DEPLOYMENT_PREFLIGHT_UNAVAILABLE` on a route claim that stores an absent owner as `null`, and the deployment and adoption preflights log the cause of an unexpected failure. A node's requests no longer contend on the controller fence and share a 6 s budget below the cluster relay's 8 s forward deadline, a request out of budget is refused `controller-deadline`, which the node retries, and a node deletion refuses what a racing write bound to the node. Cloudly consumes the projection application receipts of Pallet `36.3.0`, so a flow a node's projection withdrew is granted again on the same leases once the node reports that it applied the withdrawal; an earlier Pallet keeps every withdrawal carried. Cloudly `33.17.2` starts a database below data version `0.25.0` that holds a runtime slot: the data step `runtime-log-attempts` read through models startup has not prepared and was refused, and now reads and writes through the driver; an install whose first start failed there stayed at data version `0.24.0` and upgrades to `1.27.0` normally. Cloudly `33.17.1` fixes the first start of `33.17.0`, which crash-looped on a database holding Pallet-era nodes: its first data step `cluster-node-hostname-intent` stated each intent through the node and cluster models, which startup has not prepared while it runs the data steps, and was refused before its first write; the step now reads and writes the stored node and cluster documents directly, like the other data steps. The migration ledger does not advance past a failed step, so an install on `1.25.0` whose first start failed stayed unchanged at data version `0.25.0` and upgrades to `1.27.0` normally. Cloudly `33.17.1` keeps the data steps of `33.17.0`, which move the data version from `0.25.0` to `0.28.0`: every upgrade from `1.24.0` or earlier, and from `1.25.0` whose first start failed, runs the forward-only data steps `cluster-node-hostname-intent` to `0.26.0` (every Pallet-era node gets the intent of the hostname it reports, and nothing is renamed), `deployment-operation-route-evidence` to `0.27.0` (a routeless deployment operation that succeeded records its empty route evidence) and `service-secret-target-predecessor` to `0.28.0` (a secret target state an earlier service deletion left behind is removed) before the `0.28.0` to `0.30.0` steps. The template stays marked breaking, migration-required, backup-before-upgrade and manual-review, because hosts read the flags from the target version alone and every upgrade runs the `0.28.0` to `0.30.0` steps, after the `0.25.0` to `0.28.0` steps from `1.24.0` or earlier; every upgrade from `1.19.0` or earlier runs the forward-only data step `runtime-log-attempts` from `0.24.0` to `0.25.0` before them (the log record of every slot's current attempt is written), and every upgrade from `1.15.0` or earlier runs `corestore-control-token-state` from `0.23.0` to `0.24.0` before that (a Corestore control token stored earlier is recorded as revision 1); every Cloudly before `33.17.3` refuses the migrated data: stop Cloudly and take a verified backup first, as rollback is full-restore-only. From `1.24.0` or earlier, Cloudly `33.17.0`'s changes apply too: Cloudly `33.17.0` lets a legacy import reserve: it takes over every route claim its legacy service holds in the import's organization, the cluster ingress keeps serving each hostname for the legacy service until the import's service declares it, and cleanup or rollback before promotion hands the claims back while the legacy service exists; `ROUTE_UNAVAILABLE` and `DEPLOYMENT_ROUTE_COLLISION` name each conflicting hostname and the services holding it. It owns the hostname a node should carry (interfaces `32.52.0`, `cloudly-worker-<name>` by default): `setClusterNodeHostname` renames a Pallet-era node and `resetClusterNodeHostname` sets the default, Spark reads the intent at `POST /spark/nodes/host`, and a Pallet service's gateway routes and inbound mail follow the node its runtime spec pins by id, so a rename moves no traffic. A routeless deployment records its empty route evidence when it succeeds; deleting a cluster's designated ingress service is refused `SERVICE_IS_CLUSTER_INGRESS`, `designateClusterIngress` recovers a designation whose bearer is no longer active, and a deleted service's secret target state goes with its row, so a service recreated under its id writes its secrets again. From `1.23.0` or earlier, Cloudly `33.16.0`'s changes apply too: Cloudly `33.16.0` captures a legacy service's runtime attestation from an administrator's host observation, without a Coreflow session: `captureLegacyServiceRuntimeAttestation` takes `hostObservation`, the legacy Swarm service's spec image and mode and, per replica, its node, Swarm task, container, image store, image id, `RepoDigests`, state and health, read at most 15 minutes before the capture; Cloudly judges it against the one root every replica runs, which it requires whole in its registry and which the legacy tag need not still name, and refuses incomplete evidence without storing anything. The registry prune keeps an attested root until a release's `cloudly-legacy-import` evidence names the attestation or the legacy service is retired. From `1.22.0` or earlier, Cloudly `33.15.3`'s changes apply too: Cloudly `33.15.3` serves a promoted route: a route's identity carried the service's runtime write fence `runtimeAuthorityFenceGeneration`, which every runtime write of the service advances, in a Pallet-born cluster the route join's own workload lease read included, so the route plan read after the cluster ingress's certificate fetch never matched the one before it and every refresh that fetched a certificate withdrew the cluster's whole route table; a route's identity now carries only the versions that change with its authority (the route intent, the runtime policy revision, and per endpoint its assignment, its node's session and its target), while a service being deleted or holding no runtime authority is still refused by the route join, so a revoked route is withdrawn as before, by name. A table withdrawn because its authority changed or its route sources could not be read names that withdrawal as the reason the cluster ingress serves none of its routes, so a failing route verification states it; that reason states facts about its own route only, because one table carries the routes of several organizations: a route whose authority changed names its changed field, every other route only that another route's authority (or the ingress designation) changed during the certificate fetch, and a source-read failure only that the route sources could not be read, its error staying in the operator log. From `1.21.0` or earlier, Cloudly `33.15.2`'s changes apply too: Cloudly `33.15.2` lets a promoted route reach CoreTraffic: a route's identity carries the route intent version `routeIntentGeneration` instead of the whole-document `routeStateGeneration`, so the status writes during the cluster ingress's certificate fetch no longer withdraw the cluster's route table, a plan change during the fetch withdraws it only when it revokes a route the table is about to serve, and the change is named by route and input. A cluster ingress flow that a compensated promotion withdrew and a later promotion wants again no longer stalls the node's network projection: Cloudly holds that flow back with its withdrawal carried and signs the rest of the node's network, while a workload or router grant wanted again while withdrawn withholds the node's projection as `withdrawn-grant-reissued` and any other contract refusal as `projection-rejected`, each naming what it holds; the cluster ingress leaves a route whose grant is held out by name, and a failed route verification states why no route is served for its hostname. A held flow is granted again only once the target or CoreTraffic runs under a new lease. From `1.20.0` or earlier, Cloudly `33.15.1`'s changes apply too: Cloudly `33.15.1` fixes the deployment preflight of an existing service Pallet runs: it read the current runtime from Coreflow alone and answered NO-GO (`CURRENT_RUNTIME_DIGEST_MISSING`, `RUNTIME_ATTESTATION_MISMATCH`) for a service whose rollout status was verified, and now reads the runs of the service's current plan, the evidence its deployment status reads, when Pallet executes that plan on every cluster it targets. It also lets a route promotion survive the status writes of its own gateway sync: the promotion fenced on `routeStateGeneration`, the service's whole-document version, which the route status its gateway sync records, Coreflow's reconciliation reports and its own verified-route status all advance, so every promotion failed `DEPLOYMENT_ROUTE_FENCE_CONFLICT` with no route evidence; it now fences on `routeIntentGeneration`, which only a write that changes the service's domains advances, so a concurrent route change, a change and back included, still fails it fenced, and a promotion interrupted under `33.15.0` is recovered as fenced (retryable), without a rollback. From `1.19.0` or earlier, Cloudly `33.15.0`'s changes apply too: Cloudly `33.15.0` keeps workload logs: a Pallet node's log batches are kept per attempt, their payloads in Cloudly's own bucket (the template's `S3_BUCKET`) under `runtime-logs/`, bounded to 8 MiB and 8192 batches per attempt and the newest 8 attempts per slot, each batch for its config's `logs.retentionMs`, and read with `getServiceRuntimeLogAttempts` and `getRuntimeAssignmentLogs` (interfaces `32.47.0`) or the service page's Logs tab. A Pallet-executed rollout that succeeded stays succeeded when a replica later fails or is replaced; a failing service runtime pass names its step, and a database error its code name and number. A launcher secret written before a service's first image plan no longer leaves the service refused `secrets-unsupported`, because every image plan is written with the service's secret deployment plan in one transaction. The designated cluster ingress runs with `SERVEZONE_CLUSTER_RELAY_ORIGIN` and `SERVEZONE_CLUSTER_NODE_ID`, which Cloudly writes into that workload's environment (a cluster without a valid relay refuses it `cluster-relay-missing`); the template sets neither. From `1.18.0` or earlier, Cloudly `33.14.1` and `33.14.2`'s changes apply too: Cloudly `33.14.2` completes a rollout Pallet executes: Cloudly reports on every rollout whose target clusters are all on Pallet, one reporter per cluster (`pallet/<clusterId>`) over the runs of exactly the current desire, so it moves to `succeeded` (or `ready-for-route`) once its runs are ready at the requested digest and fails when a run fails, and `getServiceDeploymentStatus` reads its runtime tasks from the runtime manager instead of Coreflow, so tsdeploy no longer times out on a Pallet-attached service. A launcher-secret run admitted after a Cloudly restart, reconnect or credential rotation gets its material again instead of waiting `secret-mount-uncertain` (`secret-recipient-inactive`) until its node process restarts, because a node's secret recipient is active for every session of the node process that enrolled it. A failing producer pass is logged under its producer's subject once per change of cause, with how long it ran and a value-free cause naming the failing step and check (such as `network-projection-rejected`), and its recovery once; a failed sweep the timer started is no longer dropped. From `1.17.0` or earlier, Cloudly `33.14.0`'s changes apply too: it gives a platform-owned service's published ports infrastructure-administrator authority: an administrator designates a platform organization's service (an organization id carrying `:`) with `designatePlatformOwnedService`, withdraws it with `undesignatePlatformOwnedService` and reads it with `getServicePlatformOwnership` (interfaces `32.45.0`), after which only a verified administrator reads and writes its published ports, any other organization id is refused `organization-not-platform`, and the designation, stored on the service document, is read inside the published-port request's one admitted operation; every organization service keeps the organization-owner rule. It also names and logs every assignment dispatch outcome under a closed, value-free reason, pushes a refused or unanswered push again on the next pass, and keeps a run its node refused (cause `refused`) instead of replacing it on the failure backoff until its input changes. From `1.16.0` or earlier, Cloudly `33.13.3` and `33.13.4`'s changes apply too: Cloudly `33.13.4` delivers a run's secret material through the WorkloadInit launcher again (Corestore's `MONGODB_URI` included), remembers a successful WorkloadInit approval verification per artifact, and names the check of every refused material request with a closed, value-free `reason`; since Cloudly `33.13.3` a node's session is pushed each assignment revision once instead of on every delivery pass. From `1.15.0` or earlier, Cloudly `33.11.0` to `33.13.2`'s changes apply too: they let an administrator set the Corestore control token without an exec into Cloudly's container (`setCorestoreControlToken`, interfaces `32.42.0`, with its revision and value-free receipts in the new collections `cloudly_corestore_control_token_state` and `cloudly_corestore_control_token_receipts`, and `servezone corestore set-control-token`), keep every managed VPN member across a protected-authority step that only adds, retire a node and its egress owner (`retireClusterNode`, interfaces `32.43.0`), ask a retiring node on interfaces `32.44.0` to withdraw its allocation protection so that a stopped or offline node no longer blocks allocation, and keep a stopping workload's lease in its node's projection until the node's stop receipt is accepted. From `1.14.0` or earlier, Cloudly `33.10.0`'s changes apply too: it lets an operator obtain a cluster relay's bearer without an exec into Cloudly's process: `exportClusterRelayAuthorization` (interfaces `32.41.0`) requires a freshly signed-in administrator, proves the delivered credential version against the hash its generation issued, commits an audit receipt fenced at that generation before it answers the bearer, and never logs it; the receipts live in the new collection `cloudly_cluster_relay_authorization_exports`, installed at startup and listed by `getClusterRelayAuthorizationExports`, and `servezone relay export-authorization` (`@serve.zone/cli` `33.10.0`) writes the bearer as a new `0600` file. From `1.14.0` or earlier, Cloudly `33.9.0`'s changes apply too: a node's managed VPN member is kept across its network projection changes instead of being withdrawn from the hub network on every workload change (`bindGetRuntimeManagedVpnCredentialSuccessor`, interfaces `32.39.0`), the failure cause a node reports with a failed run (interfaces `32.40.0`) is stored and shown in the runtime assignment views and the dashboard's Cause column, and `deleteServiceById` answers success once a service is marked for deletion while another deleting service drains, naming its refusals `SERVICE_LIFECYCLE_BUSY`, `SERVICE_ORGANIZATION_AUTHORITY_REQUIRED` and `SERVICE_MANAGER_STOPPING` instead of an internal error. From `1.13.0` or earlier, Cloudly `33.8.3`'s fix applies too: it lets `deleteServiceById` retire a legacy service whose Corestore resources a successor adopted: its live Corestore bindings are tombstoned with the ordinary config push once every claimed legacy resource of each binding's capability has passed to the successor's live adopting binding, while a service without such a handover is still refused `CORESTORE_CLEANUP_TARGET_AUTHORITY_REQUIRED`. A legacy service whose runtime attestation a legacy-import operation still uses (`reserving`, `reserved`, `provisioning` or `awaiting-image`) is refused `SERVICE_LEGACY_IMPORT_PENDING` (retryable) and keeps running; import and deletion are serialized on the registry repository, so an import that starts after the check refuses as `LEGACY_IMPORT_SOURCE_MISMATCH`, and a deletion that proceeds deletes the attestations no release consumed. From `1.12.0` or earlier, Cloudly `33.8.2`'s fix applies too: Cloudly names why it refused a node's report: a refused `reportRuntimeNetworkProtection`, `reportRuntimeAssignmentTerminalReceipt`, `reportRuntimeAssignmentObservation` or `reportRuntimeAssignmentLogs` is logged as a warning once per node, report and distinct reason, and the node is answered with the unchanged error text plus `{ code: 'runtime-session-report-refused', reason }` as the error's data. From `1.11.0` or earlier, Cloudly `33.8.1`'s fix applies too: deploy before any Pallet that sends `discardedCaptures` or a `not-kept` log loss reaches a fleet node, since it accepts those log batch fields of interfaces `32.38.0`, which Cloudly `33.8.0` refuses on every retry, and still keeps no workload logs. From `1.10.0` or earlier, Cloudly `33.8.0`'s changes apply too: deploy before any Pallet that captures workload output reaches a fleet node, since Cloudly `33.8.0` answers a Pallet's `reportRuntimeAssignmentLogs` (interfaces `32.37.0`) with `not-kept`, which an earlier Cloudly leaves unhandled. Cloudly `33.8.0` lets a legacy `deployOnPush` service without deployable source move to a greenfield successor that runs the exact image it ran (`captureLegacyServiceRuntimeAttestation`, a `legacyImport` reservation under the capability `deployment:import-legacy`, and `importServiceDeploymentLegacyImage` in place of a push), judges promotion against the platforms of the service's rollout target, refuses a registry repository that belongs to another service as `REGISTRY_REPOSITORY_MISMATCH`, promotes and routes a service with a Corestore `database` or `objectstorage` binding again, and reads a node whose last report is older than 180 seconds as `offline`. Its web UI moved to path URLs and a regrouped menu, so bookmarks of the old UI locations open the not-found screen; server paths such as `/status` and the OIDC callback are unchanged. From `1.9.0` or earlier, Cloudly `33.7.0`'s changes apply: Cloudly `33.7.0` lets a fresh greenfield service take over a legacy service's Corestore database and bucket with their data and retention intact: an `adoptCorestoreLegacyResources` selection entry may name `successorServiceId` (interfaces `32.34.0`, carried out by Corestore `33.2.0` or later), the successor must share the owner's organization, be an immutable-deployment service, own no legacy resource of the capability and hold no other binding of it, and each legacy resource is adopted by one service only (`legacy-resource-adopted-elsewhere`, `successor-organization-mismatch`, `successor-not-greenfield`, `successor-owns-legacy-resource`). Since Cloudly `33.6.1`, a deployment reservation whose release tag the registry already holds is refused `DEPLOYMENT_RELEASE_TAG_OCCUPIED` instead of waiting for its image forever, an administrator's manifest push to a release tag a deployment operation reserved is refused `409 release-tag-reserved`, and a binding status report reaches its cluster relay only when it changed what the relay reads. From `1.8.0` or earlier, startup runs the forward-only data step `deployment-machine-user-grants` from `0.22.0` to `0.23.0`, which keeps on every deployment machine user only the grants a capability check reads and permanently removes the rest (such as the `{ serviceId, capabilities }` grants of Cloudly 11); stop Cloudly and take a verified backup first, as the way back is the pre-upgrade backup. Cloudly `33.6.0`'s changes apply too: Cloudly stops gracefully on SIGTERM and SIGINT within 8 seconds, below the 10-second stop grace of Docker and Swarm, so a stop or restart no longer leaves a database transaction held and the next start no longer crash-loops on `EFENCE_BUSY`; a process ended by SIGKILL still holds its database session until the server's session timeout. Every new service gets its own deployment namespace, so two services of one project reserve without `DEPLOYMENT_RESOURCE_COLLISION`, while a deployed service keeps its namespace, and `getDeploymentMachineUsers` lists users configured under Cloudly 11 again. From `1.7.0` or earlier, Cloudly `33.5.0`'s changes apply: Cloudly reserves a deployment only for a deployment machine user: `reserveServiceDeployment` refuses an administrator with `DEPLOYMENT_MACHINE_IDENTITY_REQUIRED`, including a deployer that signs in with a username and password (such as tsdeploy with `TSDEPLOY_CLOUDLY_USERNAME`/`TSDEPLOY_CLOUDLY_PASSWORD`), so before upgrading create a deployment machine user per deployer (`mutateDeploymentMachineUser`, or Security → Access → Deployment machine users in the dashboard), attach its grants with `configureServiceDeploymentMachineUser` and switch the deployer to its token; an existing `api` machine user with its grants already qualifies. A machine identity or registry bearer issued by an earlier release is refused until its holder exchanges its token again with `getIdentityByToken`, and removing a token now ends the sessions opened with it. Let no deployment run during the upgrade: a run in progress keeps its pre-upgrade identity and is refused for the rest of that run (rerun it, or resume it with `deploy-retry`). From `1.3.0` through `1.6.0`, startup runs the forward-only data step `runtime-session-protocol-offer` from `0.21.0` to `0.22.0`, which states `protocol: null` on every Pallet session row recorded before Cloudly stored its node's protocol offer; stop Cloudly and take a verified backup first, as rollback is full-restore-only. From `1.6.0`, Cloudly `33.4.0`'s changes apply: Cloudly `33.4.0` lets `setServicePublishedPorts` publish a contiguous range through `hostPortEnd` (at most 1024 ports in 64 entries per protocol) and same-port outbound through `symmetric: true`, which needs public egress (`published-port-symmetric-without-egress`) and owns its inside ports (`published-port-symmetric-inside-overlap`). New handoff leases translate outbound flows only into `49152-65535`, whose ports are refused `published-port-reserved`; a node keeps its `1024-65535` lease until its router is re-created. A policy write for a service being deleted is refused `service-deleting`. A projection carrying a range or a symmetric entry is withheld as `node-contract-behind` from a Pallet node whose session states a release below interfaces `32.31.0`, or an unrecorded one, so ranges and symmetric entries take effect on a node only once it runs a Pallet release built on interfaces `32.31.0` or later. From `1.5.0`, Cloudly `33.3.0`'s changes apply: Cloudly `33.3.0` lets an administrator set a service's network egress with `setServiceNetworkEgress` (public internet, and the platform endpoints of the protected authority), and refuses a workload whose database or object-storage binding sits on a node whose Corestore endpoint its network does not select as `database-endpoint-unselected` or `objectstorage-endpoint-unselected`; a replica already running keeps running while its target reports the refusal. From `1.4.0`, Cloudly `33.2.0`'s changes apply: Cloudly takes a dcrouter admin token once through `bootstrapExternalGatewayCredential` to provision its own gateway-client credential, starts a first enrollment with the gateway settings, and stages a gateway settings change the held credential cannot carry until the next bootstrap. From `1.2.1` or earlier, startup runs the forward-only migration from `0.20.0` to `0.21.0` before that step, dropping the relay certificate and DNS collections of Cloudly's retired Cloudflare and Let's Encrypt integration and logging every relay name whose A record Cloudly had written at Cloudflare, which the operator removes at the provider. dcrouter holds every cluster relay name's A record and certificate from then on, `SERVEZONE_SSLMODE=letsencrypt` is refused, and the typed API changes as the Cloudly 33.0.0 changelog lists. Stop Cloudly and take a verified backup before upgrading; rollback is full-restore-only. Roll out Cloudly `33.17.3` before Coreflow `33.2.0`; Coreflow `33.1.0` is the minimum. From `1.3.0`, also roll out Cloudly before Coreflow and Corestore `33.0.0`, and set every node's Corestore database endpoint, because a database binding on a node without one is not granted and its service is refused `database-endpoint-missing`, and existing database bindings return no credentials until they are granted again for the endpoint. From `1.1.10` or earlier, startup first runs the `1.2.0` steps from `0.10.0` and needs completed Secrets v2 cutover retirement. Both the existing Secrets v2 keyring and operator-approved WorkloadInit authority are required encrypted inputs delivered as separate root-owned `0400` files; the public environment contains only their fixed paths. |
+| `cloudly` | MongoDB, S3 | Version `1.28.0` pins Cloudly `33.18.0` and keeps the `1.27.0` runtime contract, including the Onebox `33.8.0` minimum: its platform Corestore `32.2.4` runs NoSQLDB `10.6.1` with the D3 write-conflict fix, and on an earlier engine a node's network plan loses every commit to a `WriteConflict`, so Cloudly `33.15` must not run on it. Cloudly `33.18.0` loads the App Store catalog at runtime instead of bundling it, from the registries of its `appStoreCatalogRegistries` setting (empty means the npm registry), so a Cloudly template update needs an appstore release only; it ignores `APPSTORE_URL`, whose remote source is removed, and while no verified catalog is active it refuses App Store install details, upgrade preview and upgrade with `APPSTORE_CATALOG_UNAVAILABLE`. It adds no data step and keeps the data version `0.30.0`, so an upgrade from `1.27.0` runs none. From `1.26.0` or earlier, Cloudly `33.17.3`'s changes apply too: Cloudly `33.17.3` moves the data version from `0.28.0` to `0.30.0`: every upgrade from `1.26.0` or earlier runs the forward-only data steps `route-claim-absent-owners` to `0.29.0` (the stored nulls of absent owners are removed from every route claim) and `bounded-runtime-history` to `0.30.0` (every archived deployment record is deleted, the index `archiveState_1` is dropped and the accepted Spark observations are pruned to the rows the census reads), and every Cloudly before `33.17.3` refuses the `0.30.0` data. Runtime history is bounded from then on: a Coreflow report deletes the deployment records it no longer names instead of archiving them, `getDeployments` answers the current records whether or not it is asked to `includeArchived`, `deploymentArchiveRetentionDays` is accepted but has no effect, and the dashboard no longer offers archived deployments. A deployment preflight no longer fails `DEPLOYMENT_PREFLIGHT_UNAVAILABLE` on a route claim that stores an absent owner as `null`, and the deployment and adoption preflights log the cause of an unexpected failure. A node's requests no longer contend on the controller fence and share a 6 s budget below the cluster relay's 8 s forward deadline, a request out of budget is refused `controller-deadline`, which the node retries, and a node deletion refuses what a racing write bound to the node. Cloudly consumes the projection application receipts of Pallet `36.3.0`, so a flow a node's projection withdrew is granted again on the same leases once the node reports that it applied the withdrawal; an earlier Pallet keeps every withdrawal carried. Cloudly `33.17.2` starts a database below data version `0.25.0` that holds a runtime slot: the data step `runtime-log-attempts` read through models startup has not prepared and was refused, and now reads and writes through the driver; an install whose first start failed there stayed at data version `0.24.0` and upgrades to `1.28.0` normally. Cloudly `33.17.1` fixes the first start of `33.17.0`, which crash-looped on a database holding Pallet-era nodes: its first data step `cluster-node-hostname-intent` stated each intent through the node and cluster models, which startup has not prepared while it runs the data steps, and was refused before its first write; the step now reads and writes the stored node and cluster documents directly, like the other data steps. The migration ledger does not advance past a failed step, so an install on `1.25.0` whose first start failed stayed unchanged at data version `0.25.0` and upgrades to `1.28.0` normally. Cloudly `33.17.1` keeps the data steps of `33.17.0`, which move the data version from `0.25.0` to `0.28.0`: every upgrade from `1.24.0` or earlier, and from `1.25.0` whose first start failed, runs the forward-only data steps `cluster-node-hostname-intent` to `0.26.0` (every Pallet-era node gets the intent of the hostname it reports, and nothing is renamed), `deployment-operation-route-evidence` to `0.27.0` (a routeless deployment operation that succeeded records its empty route evidence) and `service-secret-target-predecessor` to `0.28.0` (a secret target state an earlier service deletion left behind is removed) before the `0.28.0` to `0.30.0` steps. The template stays marked breaking, migration-required, backup-before-upgrade and manual-review, because hosts read the flags from the target version alone and every upgrade from `1.26.0` or earlier runs the `0.28.0` to `0.30.0` steps, after the `0.25.0` to `0.28.0` steps from `1.24.0` or earlier; every upgrade from `1.19.0` or earlier runs the forward-only data step `runtime-log-attempts` from `0.24.0` to `0.25.0` before them (the log record of every slot's current attempt is written), and every upgrade from `1.15.0` or earlier runs `corestore-control-token-state` from `0.23.0` to `0.24.0` before that (a Corestore control token stored earlier is recorded as revision 1); every Cloudly before `33.17.3` refuses the migrated data: stop Cloudly and take a verified backup first, as rollback is full-restore-only. From `1.24.0` or earlier, Cloudly `33.17.0`'s changes apply too: Cloudly `33.17.0` lets a legacy import reserve: it takes over every route claim its legacy service holds in the import's organization, the cluster ingress keeps serving each hostname for the legacy service until the import's service declares it, and cleanup or rollback before promotion hands the claims back while the legacy service exists; `ROUTE_UNAVAILABLE` and `DEPLOYMENT_ROUTE_COLLISION` name each conflicting hostname and the services holding it. It owns the hostname a node should carry (interfaces `32.52.0`, `cloudly-worker-<name>` by default): `setClusterNodeHostname` renames a Pallet-era node and `resetClusterNodeHostname` sets the default, Spark reads the intent at `POST /spark/nodes/host`, and a Pallet service's gateway routes and inbound mail follow the node its runtime spec pins by id, so a rename moves no traffic. A routeless deployment records its empty route evidence when it succeeds; deleting a cluster's designated ingress service is refused `SERVICE_IS_CLUSTER_INGRESS`, `designateClusterIngress` recovers a designation whose bearer is no longer active, and a deleted service's secret target state goes with its row, so a service recreated under its id writes its secrets again. From `1.23.0` or earlier, Cloudly `33.16.0`'s changes apply too: Cloudly `33.16.0` captures a legacy service's runtime attestation from an administrator's host observation, without a Coreflow session: `captureLegacyServiceRuntimeAttestation` takes `hostObservation`, the legacy Swarm service's spec image and mode and, per replica, its node, Swarm task, container, image store, image id, `RepoDigests`, state and health, read at most 15 minutes before the capture; Cloudly judges it against the one root every replica runs, which it requires whole in its registry and which the legacy tag need not still name, and refuses incomplete evidence without storing anything. The registry prune keeps an attested root until a release's `cloudly-legacy-import` evidence names the attestation or the legacy service is retired. From `1.22.0` or earlier, Cloudly `33.15.3`'s changes apply too: Cloudly `33.15.3` serves a promoted route: a route's identity carried the service's runtime write fence `runtimeAuthorityFenceGeneration`, which every runtime write of the service advances, in a Pallet-born cluster the route join's own workload lease read included, so the route plan read after the cluster ingress's certificate fetch never matched the one before it and every refresh that fetched a certificate withdrew the cluster's whole route table; a route's identity now carries only the versions that change with its authority (the route intent, the runtime policy revision, and per endpoint its assignment, its node's session and its target), while a service being deleted or holding no runtime authority is still refused by the route join, so a revoked route is withdrawn as before, by name. A table withdrawn because its authority changed or its route sources could not be read names that withdrawal as the reason the cluster ingress serves none of its routes, so a failing route verification states it; that reason states facts about its own route only, because one table carries the routes of several organizations: a route whose authority changed names its changed field, every other route only that another route's authority (or the ingress designation) changed during the certificate fetch, and a source-read failure only that the route sources could not be read, its error staying in the operator log. From `1.21.0` or earlier, Cloudly `33.15.2`'s changes apply too: Cloudly `33.15.2` lets a promoted route reach CoreTraffic: a route's identity carries the route intent version `routeIntentGeneration` instead of the whole-document `routeStateGeneration`, so the status writes during the cluster ingress's certificate fetch no longer withdraw the cluster's route table, a plan change during the fetch withdraws it only when it revokes a route the table is about to serve, and the change is named by route and input. A cluster ingress flow that a compensated promotion withdrew and a later promotion wants again no longer stalls the node's network projection: Cloudly holds that flow back with its withdrawal carried and signs the rest of the node's network, while a workload or router grant wanted again while withdrawn withholds the node's projection as `withdrawn-grant-reissued` and any other contract refusal as `projection-rejected`, each naming what it holds; the cluster ingress leaves a route whose grant is held out by name, and a failed route verification states why no route is served for its hostname. A held flow is granted again only once the target or CoreTraffic runs under a new lease. From `1.20.0` or earlier, Cloudly `33.15.1`'s changes apply too: Cloudly `33.15.1` fixes the deployment preflight of an existing service Pallet runs: it read the current runtime from Coreflow alone and answered NO-GO (`CURRENT_RUNTIME_DIGEST_MISSING`, `RUNTIME_ATTESTATION_MISMATCH`) for a service whose rollout status was verified, and now reads the runs of the service's current plan, the evidence its deployment status reads, when Pallet executes that plan on every cluster it targets. It also lets a route promotion survive the status writes of its own gateway sync: the promotion fenced on `routeStateGeneration`, the service's whole-document version, which the route status its gateway sync records, Coreflow's reconciliation reports and its own verified-route status all advance, so every promotion failed `DEPLOYMENT_ROUTE_FENCE_CONFLICT` with no route evidence; it now fences on `routeIntentGeneration`, which only a write that changes the service's domains advances, so a concurrent route change, a change and back included, still fails it fenced, and a promotion interrupted under `33.15.0` is recovered as fenced (retryable), without a rollback. From `1.19.0` or earlier, Cloudly `33.15.0`'s changes apply too: Cloudly `33.15.0` keeps workload logs: a Pallet node's log batches are kept per attempt, their payloads in Cloudly's own bucket (the template's `S3_BUCKET`) under `runtime-logs/`, bounded to 8 MiB and 8192 batches per attempt and the newest 8 attempts per slot, each batch for its config's `logs.retentionMs`, and read with `getServiceRuntimeLogAttempts` and `getRuntimeAssignmentLogs` (interfaces `32.47.0`) or the service page's Logs tab. A Pallet-executed rollout that succeeded stays succeeded when a replica later fails or is replaced; a failing service runtime pass names its step, and a database error its code name and number. A launcher secret written before a service's first image plan no longer leaves the service refused `secrets-unsupported`, because every image plan is written with the service's secret deployment plan in one transaction. The designated cluster ingress runs with `SERVEZONE_CLUSTER_RELAY_ORIGIN` and `SERVEZONE_CLUSTER_NODE_ID`, which Cloudly writes into that workload's environment (a cluster without a valid relay refuses it `cluster-relay-missing`); the template sets neither. From `1.18.0` or earlier, Cloudly `33.14.1` and `33.14.2`'s changes apply too: Cloudly `33.14.2` completes a rollout Pallet executes: Cloudly reports on every rollout whose target clusters are all on Pallet, one reporter per cluster (`pallet/<clusterId>`) over the runs of exactly the current desire, so it moves to `succeeded` (or `ready-for-route`) once its runs are ready at the requested digest and fails when a run fails, and `getServiceDeploymentStatus` reads its runtime tasks from the runtime manager instead of Coreflow, so tsdeploy no longer times out on a Pallet-attached service. A launcher-secret run admitted after a Cloudly restart, reconnect or credential rotation gets its material again instead of waiting `secret-mount-uncertain` (`secret-recipient-inactive`) until its node process restarts, because a node's secret recipient is active for every session of the node process that enrolled it. A failing producer pass is logged under its producer's subject once per change of cause, with how long it ran and a value-free cause naming the failing step and check (such as `network-projection-rejected`), and its recovery once; a failed sweep the timer started is no longer dropped. From `1.17.0` or earlier, Cloudly `33.14.0`'s changes apply too: it gives a platform-owned service's published ports infrastructure-administrator authority: an administrator designates a platform organization's service (an organization id carrying `:`) with `designatePlatformOwnedService`, withdraws it with `undesignatePlatformOwnedService` and reads it with `getServicePlatformOwnership` (interfaces `32.45.0`), after which only a verified administrator reads and writes its published ports, any other organization id is refused `organization-not-platform`, and the designation, stored on the service document, is read inside the published-port request's one admitted operation; every organization service keeps the organization-owner rule. It also names and logs every assignment dispatch outcome under a closed, value-free reason, pushes a refused or unanswered push again on the next pass, and keeps a run its node refused (cause `refused`) instead of replacing it on the failure backoff until its input changes. From `1.16.0` or earlier, Cloudly `33.13.3` and `33.13.4`'s changes apply too: Cloudly `33.13.4` delivers a run's secret material through the WorkloadInit launcher again (Corestore's `MONGODB_URI` included), remembers a successful WorkloadInit approval verification per artifact, and names the check of every refused material request with a closed, value-free `reason`; since Cloudly `33.13.3` a node's session is pushed each assignment revision once instead of on every delivery pass. From `1.15.0` or earlier, Cloudly `33.11.0` to `33.13.2`'s changes apply too: they let an administrator set the Corestore control token without an exec into Cloudly's container (`setCorestoreControlToken`, interfaces `32.42.0`, with its revision and value-free receipts in the new collections `cloudly_corestore_control_token_state` and `cloudly_corestore_control_token_receipts`, and `servezone corestore set-control-token`), keep every managed VPN member across a protected-authority step that only adds, retire a node and its egress owner (`retireClusterNode`, interfaces `32.43.0`), ask a retiring node on interfaces `32.44.0` to withdraw its allocation protection so that a stopped or offline node no longer blocks allocation, and keep a stopping workload's lease in its node's projection until the node's stop receipt is accepted. From `1.14.0` or earlier, Cloudly `33.10.0`'s changes apply too: it lets an operator obtain a cluster relay's bearer without an exec into Cloudly's process: `exportClusterRelayAuthorization` (interfaces `32.41.0`) requires a freshly signed-in administrator, proves the delivered credential version against the hash its generation issued, commits an audit receipt fenced at that generation before it answers the bearer, and never logs it; the receipts live in the new collection `cloudly_cluster_relay_authorization_exports`, installed at startup and listed by `getClusterRelayAuthorizationExports`, and `servezone relay export-authorization` (`@serve.zone/cli` `33.10.0`) writes the bearer as a new `0600` file. From `1.14.0` or earlier, Cloudly `33.9.0`'s changes apply too: a node's managed VPN member is kept across its network projection changes instead of being withdrawn from the hub network on every workload change (`bindGetRuntimeManagedVpnCredentialSuccessor`, interfaces `32.39.0`), the failure cause a node reports with a failed run (interfaces `32.40.0`) is stored and shown in the runtime assignment views and the dashboard's Cause column, and `deleteServiceById` answers success once a service is marked for deletion while another deleting service drains, naming its refusals `SERVICE_LIFECYCLE_BUSY`, `SERVICE_ORGANIZATION_AUTHORITY_REQUIRED` and `SERVICE_MANAGER_STOPPING` instead of an internal error. From `1.13.0` or earlier, Cloudly `33.8.3`'s fix applies too: it lets `deleteServiceById` retire a legacy service whose Corestore resources a successor adopted: its live Corestore bindings are tombstoned with the ordinary config push once every claimed legacy resource of each binding's capability has passed to the successor's live adopting binding, while a service without such a handover is still refused `CORESTORE_CLEANUP_TARGET_AUTHORITY_REQUIRED`. A legacy service whose runtime attestation a legacy-import operation still uses (`reserving`, `reserved`, `provisioning` or `awaiting-image`) is refused `SERVICE_LEGACY_IMPORT_PENDING` (retryable) and keeps running; import and deletion are serialized on the registry repository, so an import that starts after the check refuses as `LEGACY_IMPORT_SOURCE_MISMATCH`, and a deletion that proceeds deletes the attestations no release consumed. From `1.12.0` or earlier, Cloudly `33.8.2`'s fix applies too: Cloudly names why it refused a node's report: a refused `reportRuntimeNetworkProtection`, `reportRuntimeAssignmentTerminalReceipt`, `reportRuntimeAssignmentObservation` or `reportRuntimeAssignmentLogs` is logged as a warning once per node, report and distinct reason, and the node is answered with the unchanged error text plus `{ code: 'runtime-session-report-refused', reason }` as the error's data. From `1.11.0` or earlier, Cloudly `33.8.1`'s fix applies too: deploy before any Pallet that sends `discardedCaptures` or a `not-kept` log loss reaches a fleet node, since it accepts those log batch fields of interfaces `32.38.0`, which Cloudly `33.8.0` refuses on every retry, and still keeps no workload logs. From `1.10.0` or earlier, Cloudly `33.8.0`'s changes apply too: deploy before any Pallet that captures workload output reaches a fleet node, since Cloudly `33.8.0` answers a Pallet's `reportRuntimeAssignmentLogs` (interfaces `32.37.0`) with `not-kept`, which an earlier Cloudly leaves unhandled. Cloudly `33.8.0` lets a legacy `deployOnPush` service without deployable source move to a greenfield successor that runs the exact image it ran (`captureLegacyServiceRuntimeAttestation`, a `legacyImport` reservation under the capability `deployment:import-legacy`, and `importServiceDeploymentLegacyImage` in place of a push), judges promotion against the platforms of the service's rollout target, refuses a registry repository that belongs to another service as `REGISTRY_REPOSITORY_MISMATCH`, promotes and routes a service with a Corestore `database` or `objectstorage` binding again, and reads a node whose last report is older than 180 seconds as `offline`. Its web UI moved to path URLs and a regrouped menu, so bookmarks of the old UI locations open the not-found screen; server paths such as `/status` and the OIDC callback are unchanged. From `1.9.0` or earlier, Cloudly `33.7.0`'s changes apply: Cloudly `33.7.0` lets a fresh greenfield service take over a legacy service's Corestore database and bucket with their data and retention intact: an `adoptCorestoreLegacyResources` selection entry may name `successorServiceId` (interfaces `32.34.0`, carried out by Corestore `33.2.0` or later), the successor must share the owner's organization, be an immutable-deployment service, own no legacy resource of the capability and hold no other binding of it, and each legacy resource is adopted by one service only (`legacy-resource-adopted-elsewhere`, `successor-organization-mismatch`, `successor-not-greenfield`, `successor-owns-legacy-resource`). Since Cloudly `33.6.1`, a deployment reservation whose release tag the registry already holds is refused `DEPLOYMENT_RELEASE_TAG_OCCUPIED` instead of waiting for its image forever, an administrator's manifest push to a release tag a deployment operation reserved is refused `409 release-tag-reserved`, and a binding status report reaches its cluster relay only when it changed what the relay reads. From `1.8.0` or earlier, startup runs the forward-only data step `deployment-machine-user-grants` from `0.22.0` to `0.23.0`, which keeps on every deployment machine user only the grants a capability check reads and permanently removes the rest (such as the `{ serviceId, capabilities }` grants of Cloudly 11); stop Cloudly and take a verified backup first, as the way back is the pre-upgrade backup. Cloudly `33.6.0`'s changes apply too: Cloudly stops gracefully on SIGTERM and SIGINT within 8 seconds, below the 10-second stop grace of Docker and Swarm, so a stop or restart no longer leaves a database transaction held and the next start no longer crash-loops on `EFENCE_BUSY`; a process ended by SIGKILL still holds its database session until the server's session timeout. Every new service gets its own deployment namespace, so two services of one project reserve without `DEPLOYMENT_RESOURCE_COLLISION`, while a deployed service keeps its namespace, and `getDeploymentMachineUsers` lists users configured under Cloudly 11 again. From `1.7.0` or earlier, Cloudly `33.5.0`'s changes apply: Cloudly reserves a deployment only for a deployment machine user: `reserveServiceDeployment` refuses an administrator with `DEPLOYMENT_MACHINE_IDENTITY_REQUIRED`, including a deployer that signs in with a username and password (such as tsdeploy with `TSDEPLOY_CLOUDLY_USERNAME`/`TSDEPLOY_CLOUDLY_PASSWORD`), so before upgrading create a deployment machine user per deployer (`mutateDeploymentMachineUser`, or Security → Access → Deployment machine users in the dashboard), attach its grants with `configureServiceDeploymentMachineUser` and switch the deployer to its token; an existing `api` machine user with its grants already qualifies. A machine identity or registry bearer issued by an earlier release is refused until its holder exchanges its token again with `getIdentityByToken`, and removing a token now ends the sessions opened with it. Let no deployment run during the upgrade: a run in progress keeps its pre-upgrade identity and is refused for the rest of that run (rerun it, or resume it with `deploy-retry`). From `1.3.0` through `1.6.0`, startup runs the forward-only data step `runtime-session-protocol-offer` from `0.21.0` to `0.22.0`, which states `protocol: null` on every Pallet session row recorded before Cloudly stored its node's protocol offer; stop Cloudly and take a verified backup first, as rollback is full-restore-only. From `1.6.0`, Cloudly `33.4.0`'s changes apply: Cloudly `33.4.0` lets `setServicePublishedPorts` publish a contiguous range through `hostPortEnd` (at most 1024 ports in 64 entries per protocol) and same-port outbound through `symmetric: true`, which needs public egress (`published-port-symmetric-without-egress`) and owns its inside ports (`published-port-symmetric-inside-overlap`). New handoff leases translate outbound flows only into `49152-65535`, whose ports are refused `published-port-reserved`; a node keeps its `1024-65535` lease until its router is re-created. A policy write for a service being deleted is refused `service-deleting`. A projection carrying a range or a symmetric entry is withheld as `node-contract-behind` from a Pallet node whose session states a release below interfaces `32.31.0`, or an unrecorded one, so ranges and symmetric entries take effect on a node only once it runs a Pallet release built on interfaces `32.31.0` or later. From `1.5.0`, Cloudly `33.3.0`'s changes apply: Cloudly `33.3.0` lets an administrator set a service's network egress with `setServiceNetworkEgress` (public internet, and the platform endpoints of the protected authority), and refuses a workload whose database or object-storage binding sits on a node whose Corestore endpoint its network does not select as `database-endpoint-unselected` or `objectstorage-endpoint-unselected`; a replica already running keeps running while its target reports the refusal. From `1.4.0`, Cloudly `33.2.0`'s changes apply: Cloudly takes a dcrouter admin token once through `bootstrapExternalGatewayCredential` to provision its own gateway-client credential, starts a first enrollment with the gateway settings, and stages a gateway settings change the held credential cannot carry until the next bootstrap. From `1.2.1` or earlier, startup runs the forward-only migration from `0.20.0` to `0.21.0` before that step, dropping the relay certificate and DNS collections of Cloudly's retired Cloudflare and Let's Encrypt integration and logging every relay name whose A record Cloudly had written at Cloudflare, which the operator removes at the provider. dcrouter holds every cluster relay name's A record and certificate from then on, `SERVEZONE_SSLMODE=letsencrypt` is refused, and the typed API changes as the Cloudly 33.0.0 changelog lists. Stop Cloudly and take a verified backup before upgrading; rollback is full-restore-only. Roll out Cloudly `33.18.0` before Coreflow `33.2.0`; Coreflow `33.1.0` is the minimum. From `1.3.0`, also roll out Cloudly before Coreflow and Corestore `33.0.0`, and set every node's Corestore database endpoint, because a database binding on a node without one is not granted and its service is refused `database-endpoint-missing`, and existing database bindings return no credentials until they are granted again for the endpoint. From `1.1.10` or earlier, startup first runs the `1.2.0` steps from `0.10.0` and needs completed Secrets v2 cutover retirement. Both the existing Secrets v2 keyring and operator-approved WorkloadInit authority are required encrypted inputs delivered as separate root-owned `0400` files; the public environment contains only their fixed paths. |
 | `ghost` | MariaDB | Uses MySQL-style `database__connection__*` environment variables. |
 | `gitea` | MariaDB | Uses Gitea database environment variables with `${MARIADB_*}` placeholders. |
 | `nextcloud` | MariaDB, Valkey | Uses MySQL-compatible database variables. Valkey is declared as a platform requirement. |
 | `plausible` | ClickHouse | Declares ClickHouse as a platform requirement. |
-| `siprouter` | MongoDB, S3 | Uses SmartData state and object storage for telephony-related runtime data. |
 | `wordpress` | MariaDB | Uses standard WordPress database environment variables. |
 
 Standalone templates such as `nginx`, `adminer`, `valkey`, `portainer`, `mattermost`, `n8n`, `uptime-kuma`, and `vaultwarden` currently define only image and port unless their version config adds explicit environment variables. `rustdesk-server` uses the official all-in-one s6 image and requires `RELAY` to advertise the public relay endpoint; RustDesk clients also require firewall access to TCP `21115`, TCP/UDP `21116`, TCP `21117`, and optional web-client TCP `21118`/`21119`.
@@ -80,7 +83,7 @@ Version configs use a small, pragmatic schema understood by serve.zone runtimes:
 
 ```jsonc
 {
-  "image": "container/image:tag",
+  "image": "container/image@sha256:<64 lower-case hex>",
   "port": 8080,
   "envVars": [
     {
@@ -125,8 +128,12 @@ Secret declarations never contain values. Each declares exactly one `file` or
 required by upstream images; secret and platform-owned environment identities
 remain uppercase canonical keys.
 
-`platformRequirements.s3: true` and `volumes` are legacy inputs. The resolver
-normalizes them deterministically for existing templates, but new templates use
+Every image is digest-pinned (`name@sha256:…`); the catalog contract refuses a
+tag-only image.
+
+`platformRequirements.s3: true` and `volumes` are legacy inputs.
+`normalizeAppStoreStorageConfig` normalizes them deterministically for existing
+templates, but new templates use
 portable, template-local `storageClasses` and stable named `storageRequests`.
 Legacy `platformRequirements.s3: true` cannot coexist with an explicit
 `objectStorage` request. Legacy volume objects may retain `name`, `mountPath`,
@@ -253,21 +260,20 @@ identities, host paths, drivers, and driver options are rejected instead of
 being passed through. Unknown `storage.*` feature IDs also fail closed. Request
 IDs are stable across upgrades, restores, and migrations.
 
-Before provisioning, a runtime must advertise its supported feature IDs and
-call the resolver's fail-closed normalization entry point:
+Every version config is judged by the catalog contract of `@serve.zone/interfaces`
+(`appstore.validateAppStoreCatalog`, which applies `appstore.validateAppStoreVersionConfig`
+to every config); this package has no validator of its own. Before provisioning, a
+runtime advertises its supported feature IDs and calls the fail-closed normalization
+entry point:
 
 ```ts
-const normalizedStorage = resolver.normalizeStorageConfig(config, {
+import { normalizeAppStoreStorageConfig } from '@serve.zone/appstore';
+
+const normalizedStorage = normalizeAppStoreStorageConfig(catalogVersion.config, {
   supportedFeatures: capabilityAdvertisement.featureIds,
 });
 ```
 
-The package also exports the pure `validateAppStoreStorageConfig()` and
-`normalizeAppStoreStorageConfig()` functions, `parseStorageCapacityQuantity()`,
-and the normalized storage handoff types. Structural validation is useful for
-catalog ingestion; only normalization with a target's `supportedFeatures` is a
-valid pre-fulfillment gate.
-
 The result contains canonical `storageClasses`, `storageRequests`,
 `requestOrigins`, and `requiredFeatureIds`. `requestOrigins` marks explicit,
 legacy-volume, and legacy-S3 requests so fulfillment adapters can preserve old
@@ -281,79 +287,142 @@ unavailable.
 
 Environment variable keys must start with a letter or underscore and may contain letters, numbers, and underscores. Mixed-case keys are supported because some upstream images, including Ghost and Gitea, require lowercase nested configuration segments such as `database__connection__host` or `GITEA__database__HOST`.
 
-Linked app manifests use the same runtime schema and let the upstream app repo own its install and upgrade metadata:
+## The Runtime Catalog
 
-```jsonc
-{
-  "app": {
-    "id": "cloudly",
-    "name": "Cloudly",
-    "description": "Multi-node serve.zone control plane.",
-    "category": "Dev Tools"
-  },
-  "latestVersion": "latest",
-  "source": {
-    "type": "dockerImage",
-    "image": "code.foss.global/serve.zone/cloudly:latest",
-    "tracking": "digest"
-  },
-  "runtime": {
-    "image": "code.foss.global/serve.zone/cloudly:latest",
-    "port": 3000
-  }
-}
-```
+The catalog is one document, `IAppStoreCatalog` of the `@serve.zone/interfaces` App Store catalog contract: every app, every published version and every version's full config with its `configDigest`, plus `contract`, `revision`, `publishedAt` and `sourceRevision`. A release ships it as an `IAppStoreCatalogEnvelope`: the catalog, its `catalogDigest` and one or more Ed25519 signatures.
+
+- `revision` is `major × 10¹² + minor × 10⁶ + patch` of the package version (`33.0.0` → `33000000000000`). Package versions only grow, so every release's catalog has a greater revision than the one before, and a consumer refuses any catalog whose revision is not greater than its active one (`revisionRegressed`). A prerelease version is refused. A catalog published from an older release line therefore never replaces a newer one.
+- `sourceRevision` is the commit the catalog was built from and `publishedAt` that commit's committer time, so the same commit always builds the same catalog.
+- Apps are ordered by id; versions in the order `app.json` lists them.
+- A published `app@version` never changes and never disappears. A version is retired by withdrawing it (`withdrawn.json`); it stays listed with its config and is refused as an install or upgrade target. `catalog.lock.json` records every published version, and the build and the test suite refuse a catalog that removes, rewrites or reinstates one. Consumers apply the same rules between two catalogs (`publishedVersionRemoved`, `publishedVersionMutated`, `publishedWithdrawalChanged`).
+
+## Publishing A Catalog
+
+| Command | What it does |
+| --- | --- |
+| `pnpm build` | Compiles, then writes `dist_catalog/catalog.json` and `dist_catalog/catalog.digest`. Signs as well when `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` is set. |
+| `pnpm run build:release` | The release build (`.smartconfig.json` `release.preflight.buildCommand`). Refuses a dirty working tree, any version `catalog.lock.json` does not record, and a missing signing key; writes the signed `dist_catalog/catalog.envelope.json`. |
+| `pnpm run catalog:lock` | Records every new version (and every new withdrawal) in `catalog.lock.json`; refuses a catalog that violates it. Run it, and commit the lock, with every new version or withdrawal. |
+| `pnpm run catalog:trustedkey` | Prints the `{ keyId, publicKey }` record consumers ship for the configured signing key. |
+
+`SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` names a file holding the PKCS#8 PEM of an Ed25519 private key (`openssl genpkey -algorithm ed25519`); the key itself never appears in arguments or logs. A release refuses to ship without it twice: `build:release` fails, and the package exports `./catalog.envelope.json`, so gitzone's entry-point check refuses a tarball that does not carry the envelope.
+
+### Signing Key And Rotation
+
+A release signs with exactly one key: the one `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` names. Consumers ship the trusted keys (`IAppStoreCatalogTrustedKey`, printed by `pnpm run catalog:trustedkey`) with their own release, and an envelope verifies when one of its signatures is by a key the consumer trusts. Rotating the key is therefore trust first, switch second:
 
-When `tracking` is `digest`, Onebox resolves the Docker manifest digest and treats digest changes as App Store upgrades while keeping the image reference simple for deployment.
+1. Generate the new key and print its trusted-key record.
+2. Release Onebox and Cloudly trusting both the current and the new key. Catalogs signed with the current key keep activating everywhere.
+3. Once every running consumer trusts the new key, point the variable at the new key file for the next App Store release. A consumer that still trusts only the old key refuses that catalog (`signatureInvalid`, no signature by a trusted key) and keeps its last-known-good catalog until it is upgraded.
+4. Release Onebox and Cloudly without the old key.
 
-Neither the index nor a linked manifest states a schema version. Published documents that still carry a `schemaVersion` member are read unchanged — the readers ignore it — so a catalog can be republished without the member at any time.
+A compromised key follows the same steps, with step 2 dropping the compromised key at once: consumers then refuse every catalog until the first one signed with the new key is published. The contract allows up to eight signatures per envelope, but this publisher signs with one key; signing with two keys at once is not supported.
 
-## Client Usage
+### Signing Key Custody
+
+The signing key is a key file on the release machine, outside every repository, held by the release operator; nothing in this repository, its CI or its logs carries it. A release runs with `SERVEZONE_APPSTORE_CATALOG_SIGNING_KEY_FILE` naming that file:
+
+- gitzone passes its environment to the release build, which it runs as `pnpm run build:release` in a clean checkout of the release commit; the publisher reads the file (`importAppStoreCatalogSigningKeyPem` of `@serve.zone/interfaces/runtime`), signs the catalog, verifies the envelope against the key's own trusted-key record and writes `dist_catalog/catalog.envelope.json` into the package gitzone publishes. It logs the key id and public key only.
+- The Gitea tag workflow (`.gitea/workflows/release.yml`) has no key: it builds the unsigned catalog of the tag and attaches `catalog.json` and `catalog.digest`, whose digest equals the published envelope's `catalogDigest`.
+- Generate a key with `openssl genpkey -algorithm ed25519 -out <key file>` on the release machine and keep the file readable by the release user only; `pnpm run catalog:trustedkey` with the variable set prints the record Onebox and Cloudly ship. Losing the file means rotating to a new key as above.
+
+## Loading The Catalog
 
 ```ts
-import { AppStoreResolver } from '@serve.zone/appstore';
+import { AppStoreCatalogLoader } from '@serve.zone/appstore';
+
+const loader = new AppStoreCatalogLoader({
+  trustedKeys,                        // IAppStoreCatalogTrustedKey[] shipped with this release
+  supportedFeatureIds,                // the requiresFeatures ids this consumer fulfils
+  registries: configuredRegistries,   // empty or absent: the default, npmjs
+  requestTimeoutMs: 30_000,           // per request, body included; the default
+});
 
-const resolver = new AppStoreResolver();
-const appStore = await resolver.getAppStoreIndex();
-const cloudly = await resolver.getAppMeta('cloudly');
-const config = await resolver.getAppVersionConfig('cloudly', cloudly.latestVersion);
+// At start: the stored last-known-good envelope, verified again against today's trust.
+const restored = await loader.restoreEnvelopeText(storedText, { origin: storedOrigin, loadedAt: storedLoadedAt });
+// 'restored'  activate restored.envelope; status.active = restored.active
+// 'refused'   no active catalog: status unavailable, cause 'refused', refused = restored.refused
+
+// On the consumer's schedule, never awaited by startup or a request:
+const result = await loader.loadFromRegistries(activeEnvelope ?? null, { signal: stopController.signal });
+// 'activated'  store result.envelope as last-known-good; status.active = result.active
+// 'unchanged'  nothing to store
+// 'refused'    keep the active catalog; status.refused = result.refused
+// 'failed'     keep the active catalog; retry with backoff
+// Always: status.lastAttempt = result.attempt; result.registries reports each registry's answer.
+// An aborted signal rejects the load with its reason: the consumer is stopping, nothing is recorded.
 ```
 
-The resolver defaults to the App Store data bundled in the published `@serve.zone/appstore` package. Tests and explicit remote consumers can inject a custom `fetch` implementation and base URL. Remote operations default to a 30-second timeout, configurable with a positive-integer `requestTimeoutMs`.
+One load asks every configured registry for the package its `latest` dist-tag names, downloads the tarball (bounded in time and size, its unpacked size bounded too), checks it against the registry's `dist.integrity`, extracts `dist_catalog/catalog.envelope.json`, verifies it with `verifyAppStoreCatalogEnvelope` (shape, digest, a signature by a trusted key, contract, schema with the consumer's `supportedFeatureIds`, every config digest) and judges it against the active catalog with `judgeAppStoreCatalogSuccession`. The first registry whose catalog activates ends the load; otherwise the result is the first `unchanged`, else the first `refused`, else `failed`. Transport, integrity and packaging failures and every refusal are results, never exceptions; an envelope the verifier cannot read is refused as `schemaInvalid`.
 
-Catalog resolution fails closed when index and app metadata IDs or latest versions disagree, when metadata latest is absent from its version list, or when an all-semver list does not select its highest semantic value. Repo manifests with multiple non-semver versions require explicit latest or channel intent; array position never determines latest.
+The registry list follows the one rule of `@serve.zone/interfaces`: `appstore.validateAppStoreCatalogRegistries` (`https:` base URLs without credentials, query or fragment, each registry once) and `appstore.resolveAppStoreCatalogRegistries` (an empty list means `appStoreCatalogDefaultRegistries`). A consumer validates an operator's setting with the same function before it stores it.
 
-Only include keys that are actually needed by a template. For example, `nginx` is currently just:
+The loader holds the consumer's options and nothing else: no catalog, no timer, no schedule, no persistence. The consumer's catalog runtime owns the one schedule of its process. The cadence Onebox and Cloudly follow, as guidance:
 
-```json
-{
-  "image": "nginx:alpine",
-  "port": 80
-}
+- restore the stored envelope at start and start the first load in the background, without waiting for it;
+- load every 15 minutes while the last attempt activated or answered `unchanged` or `refused`;
+- after a `failed` attempt, retry after 1 minute, doubling to at most 30 minutes, and return to 15 minutes after the next success;
+- run one load at a time, abort it with the signal on stop, and answer an administrator's refresh with one load now.
+
+An operator-imported envelope (an offline signed bundle, or the envelope a package carries at `@serve.zone/appstore/catalog.envelope.json`) is judged the same way with `judgeImportedEnvelope(value, active)` or `judgeImportedEnvelopeText(text, active)`; its activation reports `origin: 'operatorImport'`.
+
+### Showing The Catalog
+
+```ts
+import { getAppStoreCatalogListing, projectAppStoreCatalogApp } from '@serve.zone/appstore';
+
+const consumer = { supportedFeatureIds, consumer: { kind: 'onebox', version: oneboxVersion } };
+const apps = getAppStoreCatalogListing(activeCatalog, consumer); // IAppStoreApp[] for getAppStoreTemplates
+const projection = projectAppStoreCatalogApp(catalogApp, consumer);
+// projection.versions:                every listed version, each with installRefusal (null, versionWithdrawn,
+//                                     featuresUnsupported or consumerVersionTooOld)
+// projection.latestInstallableVersion the newest version this consumer may install, or null
+// projection.display                  { app: IAppStoreApp, meta: IAppStoreAppMeta }, or null without an install target
 ```
 
+The display shapes list only the versions this consumer may install in `versions` and name the newest of them as `latestVersion`, so a version picker built from them never offers a withdrawn version, one gated on a feature the consumer lacks or one that needs a newer consumer release; `versionStates` states every listed version with its refusal. Under `semver` the newest install target is the highest one; under `branch` it is the catalog's `latestVersion` when that is an install target, and otherwise the app has none.
+
+### Testing A Consumer
+
+`@serve.zone/appstore/testing` serves a consumer's tests, never its runtime: `createAppStoreTestSigningKey` makes a throwaway key and its trusted-key record, `createAppStoreTestCatalog` and `createAppStoreTestVersionConfig` a catalog the contract accepts, `signAppStoreTestCatalog` its envelope, `createAppStoreTestPackageTarball` the package tarball carrying it, `createAppStoreTestRegistry` a registry stub and `createAppStoreTestFetch` the `fetch` a loader under test is given.
+
+The published Cloudly templates are qualified here (`test/test.cloudlytemplates.node.ts`: pinned image, Onebox minimum, upgrade flags and platform OIDC of every template), so a template release needs no host test change.
+
+## Migrating From 32.x
+
+- `AppStoreResolver` and its `package` and `remote` source modes are gone, with the bundled `data.generated.ts`, `appStorePackageMetadata`, `appStoreDefaultRemoteBaseUrl` and `getSourceInfo()`. Load the signed catalog with `AppStoreCatalogLoader`, keep the last verified envelope in your database (restore it with `restoreEnvelopeText`), and read apps and versions from it (`findAppStoreCatalogApp`, `findAppStoreCatalogVersion`). Snapshot a service's version config and `configDigest` at install and upgrade; runtime paths read that snapshot, not the catalog.
+- Linked `servezone.appstore.json` manifests (`source.type=repoManifest`), `dockerImage` sources and digest tracking (`upgradeStrategy: 'dockerDigest'`) are gone: every version is a catalog entry with a digest-pinned image. `parseAppStoreIndex`, `parseServezoneAppStoreManifest`, `parseDockerImageReference` and `createAppStoreVersionForDockerSource` are removed.
+- `resolver.getApps()` is `getAppStoreCatalogListing(catalog, { supportedFeatureIds, consumer })` and `resolver.getAppMeta(appId)` is `projectAppStoreCatalogApp(app, { supportedFeatureIds, consumer }).display?.meta`; `resolver.getAppVersionConfig(appId, version)` is `findAppStoreCatalogVersion(catalog, appId, version)?.config`.
+- Executable `migrate-from-*.ts` scripts are no longer supported; a version folder holds only `config.json` and `withdrawn.json`.
+- Validation is owned by `@serve.zone/interfaces`: use `appstore.validateAppStoreVersionConfig` instead of `resolver.validateAppStoreVersionConfig`, and the storage contract instead of `validateAppStoreStorageConfig` and `parseStorageCapacityQuantity`.
+- `resolver.normalizeStorageConfig(config, options, label)` is `normalizeAppStoreStorageConfig(config, options, label)`, and `resolver.normalizeVolumes(volumes)` is `normalizeAppStoreVolumes(config, label)`; both read the catalog version config shape (`appstore.TAppStoreCatalogVersionConfig`).
+- The package no longer ships `apps/`, `appstore.json` or `appstore.resolved.json`; `appstore.json` is folded into each `app.json`.
+
 ## Working With Templates
 
-- Keep `appstore.json`, `apps/<app>/app.json`, and each version config in sync when adding or changing an app.
-- Prefer package-published App Store data for runtime consumers. Use `source.type=repoManifest` only when the linked manifest is intentionally reachable from the runtime environment, or pre-resolve it before publishing an App Store package.
+- A new version is a new `apps/<app>/versions/<version>/config.json`, listed in `app.json` `versions` (and `latestVersion` when it is the highest). Never edit a published version: publish a new one, and withdraw the old one with `withdrawn.json` when it must not be installed any more.
+- Pin every image to the digest of its multi-platform index (`name@sha256:…`) and record the tag and digest in the changelog.
+- Run `pnpm run catalog:lock` and commit `catalog.lock.json` with every new version or withdrawal; the test suite fails on an unlocked or changed version.
+- Gate a version that uses a config member newer than the catalog contract's minor on a feature id in `requiresFeatures`, so older consumers keep loading the rest of the catalog.
 - Prefer explicit environment variable descriptions because Onebox surfaces them to users during installation.
 - Use platform placeholders such as `${MARIADB_HOST}`, `${MARIADB_PORT}`, `${MARIADB_DATABASE}`, `${MARIADB_USER}`, `${MARIADB_PASSWORD}`, `${MONGODB_URI}`, `${S3_BUCKET}`, `${S3_ACCESS_KEY}`, `${S3_SECRET_KEY}`, `${MAIL_FROM}`, `${SMTP_HOST}`, `${SMTP_PORT}`, `${SMTP_USERNAME}`, and `${SMTP_PASSWORD}` only when the matching platform service is declared.
 - Use named `objectStorage` requests instead of `platformRequirements.s3` in new templates, with a distinct delivery destination for every binding.
 - Use named `filesystem` requests instead of `volumes` in new templates. Never put provider, host-mount, protocol, identity, driver, or driver-option details in portable manifests.
-- Keep template images boring and operationally safe unless there is a reason to pin a more specific upstream tag.
 - Validate non-trivial templates by installing them through Onebox instead of only checking JSON syntax.
 
 ## Project Map
 
 ```text
 appstore/
-├── appstore.json
-├── ts_client/
-└── apps/
-    ├── cloudly/
-    │   ├── app.json
-    │   └── versions/<version>/config.json
-    └── ...
+├── apps/
+│   ├── cloudly/
+│   │   ├── app.json
+│   │   └── versions/<version>/config.json (+ withdrawn.json)
+│   └── ...
+├── catalog.lock.json
+├── ts_publisher/   catalog builder, signing, lock (not published)
+├── ts_client/      AppStoreCatalogLoader, catalog lookups, storage handoff
+└── dist_catalog/   build output: catalog.json, catalog.digest, catalog.envelope.json
 ```
 
 ## License and Legal Information

package/ts_client/catalog.ts

@@ -0,0 +1,26 @@
+import type * as plugins from './plugins.js';
+
+type TCatalog = plugins.servezoneInterfaces.appstore.IAppStoreCatalog;
+type TCatalogApp = plugins.servezoneInterfaces.appstore.IAppStoreCatalogApp;
+type TCatalogVersion = plugins.servezoneInterfaces.appstore.IAppStoreCatalogVersion;
+
+/** The npm package that carries the signed App Store catalog. */
+export const appStoreCatalogPackageName = '@serve.zone/appstore';
+
+/** Where the signed envelope sits inside the published package (and its `./catalog.envelope.json` export). */
+export const appStoreCatalogEnvelopePackagePath = 'dist_catalog/catalog.envelope.json';
+
+/** The app a catalog lists under `appIdArg`. */
+export const findAppStoreCatalogApp = (catalogArg: TCatalog, appIdArg: string): TCatalogApp | undefined =>
+  catalogArg.apps.find((appArg) => appArg.info.id === appIdArg);
+
+/**
+ * The listed `app@version`, withdrawn ones included: an installed service keeps reading its
+ * version. Whether it is an install or upgrade target is `appstore.judgeAppStoreCatalogInstallTarget`.
+ */
+export const findAppStoreCatalogVersion = (
+  catalogArg: TCatalog,
+  appIdArg: string,
+  versionArg: string,
+): TCatalogVersion | undefined =>
+  findAppStoreCatalogApp(catalogArg, appIdArg)?.versions.find((entryArg) => entryArg.version === versionArg);

package/ts_client/index.ts

@@ -1,3 +1,5 @@
-export * from './classes.appstoreresolver.js';
+export * from './catalog.js';
+export * from './loader.js';
+export * from './projection.js';
 export * from './storage.js';
 export * from './types.js';