@serve.zone/interfaces 31.8.0 → 32.0.0

package/readme.md

@@ -14,10 +14,10 @@ pnpm add @serve.zone/interfaces
 
 ## Public API
 
-The root export exposes five namespaces:
+The root export exposes six namespaces:
 
 ```typescript
-import { appstore, data, platform, platformservice, requests } from '@serve.zone/interfaces';
+import { appstore, data, platform, platformservice, protocol, requests } from '@serve.zone/interfaces';
 ```
 
 | Namespace | Purpose |
@@ -25,6 +25,7 @@ import { appstore, data, platform, platformservice, requests } from '@serve.zone
 | `appstore` | App Store catalog, manifest, service requirement, and upgrade contracts. |
 | `data` | Durable platform object shapes such as clusters, services, deployments, images, domains, DNS entries, secrets, users, status, settings, backups, registries, BaseOS metadata, and task executions. |
 | `requests` | TypedRequest contracts for Cloudly and serve.zone control-plane RPC methods. |
+| `protocol` | The handshake two peers exchange when a session opens: what each side speaks, the oldest peer it accepts, and the named refusal when they cannot serve one session. |
 | `platform` | Current platform-service contracts for email, SMS, push notifications, letters, AI, databases, object storage, logging, backups, and SIP. |
 | `platformservice` | Legacy platform-service namespace kept for older consumers that still depend on the previous layout. |
 
@@ -44,8 +45,8 @@ import {
 release identity, attestation, approval, authority, digest, and validator
 contracts. Its runtime dependency graph is limited to the immutable-image digest
 validator; unlike `@serve.zone/interfaces/runtime`, it does not load the general
-runtime graph, `plugins.js`, SmartCrypto, TypedRequest, Corestore, or settlement
-runtime modules.
+runtime graph, `plugins.js`, SmartCrypto, TypedRequest, or Corestore runtime
+modules.
 
 ### Directional Image Streams
 
@@ -94,7 +95,7 @@ these shared contracts alone do not implement an endpoint.
 unauthenticated request shape must update. Its response remains the public
 `IClusterNode`, never a persisted backend document.
 
-`data.INodeCredentialMetadataV1` separates `spark` and `pallet` purposes and
+`data.INodeCredentialMetadata` separates `spark` and `pallet` purposes and
 exposes lifecycle state, generation, rotation-required status and session epoch,
 but no bearer, hash, socket peer or controller process identity. Infrastructure
 credentials do not grant organization or workload permissions.
@@ -115,16 +116,39 @@ before enabling rotation or Pallet enrollment.
 
 ### Spark Host Reporting
 
-`data.sparkNodeHeartbeatV2Contract` defines the HTTPS POST endpoint
-`/spark/v2/nodes/heartbeat` and transport byte limits. Its exact request snapshot
-contains a Spark-purpose bearer and `ISparkNodeReportV2`: fractional host CPU,
-memory and disk observations, Linux host facts, and the verified bundle version,
-source commit and manifest digest. It has no Docker or container-count fields.
-Local runtime readiness remains distinct from unverified workload readiness.
+`data.sparkNodeHeartbeatContract` defines the HTTPS POST endpoint
+`/spark/nodes/heartbeat`, transport byte limits and `protocolRefusalStatus`, the
+status a refused offer is answered with. Its exact request snapshot contains a
+Spark-purpose bearer, the sender's `protocol` offer and `ISparkNodeReport`:
+fractional host CPU, memory and disk observations, Linux host facts, and the
+verified bundle version, source commit and manifest digest. It has no Docker or
+container-count fields. Local runtime readiness remains distinct from unverified
+workload readiness.
+
+The route reads the bounded body, reads the offer with `protocol.readProtocolOffer`,
+negotiates it against its own `sparkNode` offer and answers a refusal with
+`protocolRefusalStatus` and an `IProtocolRefusal` body — all before the node is
+authenticated, so a peer of another major is refused by name instead of by a
+credential verdict it cannot act on. The receipt carries the controller's own
+offer, so an accepted node judges the session it just reported into.
+
+The Swarm-era Spark runtime keeps its own four routes in
+`data.sparkSwarmNodeContracts`, each stating the same three facts as the route
+above — `heartbeat` (`/spark/swarm-nodes/heartbeat`), `metricsSample`, `actionResult`
+and `swarmObservation`, every one of them an `{ endpoint, maxRequestBytes,
+maxResponseBytes }` — so one bounded read serves every Spark route. The bounds
+differ because the bodies do: a heartbeat states the node's whole runtime
+description, a metrics-sample answer carries every action queued for that node, and
+one observation carries up to 1024 observed Swarm nodes. That is a second runtime,
+not an older version of this one: a worker in `coreflow-node` mode posts those
+bodies and a pallet node posts this one, and the family retires with coreflow
+rather than with this release. `ISparkSwarmNodeHeartbeatRequest` is now owned here,
+so Cloudly and Spark no longer carry private copies of it, and every Swarm-era body
+— request and answer alike — carries `protocol` and is judged in the same order.
 
 Cloudly must authenticate the bearer against current Spark authority and fence
 credential generation and session epoch transactionally before recording host
-liveness. `ISparkNodeHeartbeatReceiptV2` contains only server-derived acceptance
+liveness. `ISparkNodeHeartbeatReceipt` contains only server-derived acceptance
 evidence; the sender must match its node ID and credential generation to its exact
 active identity. Neither a receipt nor the sender's observation time grants
 current authority or workload readiness. Persist only the report and receipt in
@@ -138,27 +162,28 @@ listener, credentials, persistence, freshness or shutdown.
 
 ### Independent Node Enrollment
 
-`requests.node` defines `getNodeEnrollmentStateV1` for current Spark-authenticated
-adoption preconditions and `enrollNodeV1` for atomic Spark/Pallet enrollment. These
+`requests.node` defines `getNodeEnrollmentState` for current Spark-authenticated
+adoption preconditions and `enrollNode` for atomic Spark/Pallet enrollment. These
 contracts do not implement endpoints, authentication, a database or a daemon.
 
 The enrollment proposal binds the canonical HTTPS Cloudly origin, hostname,
 enrollment identity, original bootstrap proof hash and an exact ordered pair of
 independently prepared Spark/Pallet credential hashes and CAS counters. Fresh Jump
 starts both at zero; existing-node adoption rotates current Spark and requires
-Pallet authority to be absent. `snapshotNodeEnrollmentV1` returns a detached,
-frozen snapshot; `computeNodeEnrollmentV1Digest` hashes domain-separated strict
-canonical JSON. Neither helper generates or persists credential material.
+Pallet authority to be absent. `snapshotNodeEnrollment` returns a detached,
+frozen snapshot; `computeNodeEnrollmentDigest` hashes strict canonical JSON
+under `nodeEnrollmentContract.digestDomain`, `serve.zone/node-enrollment`.
+Neither helper generates or persists credential material.
 
 Transport proof is excluded from the digest to permit exact lost-response
 recovery. Bootstrap proof must hash to the original proof hash and is allowed only
 before a receipt exists. Pending-Spark proof must hash to the prepared Spark hash
-and is allowed only for an existing exact receipt. `verifyNodeEnrollmentProofV1`
+and is allowed only for an existing exact receipt. `verifyNodeEnrollmentProof`
 checks this binding and mode only: Cloudly must derive receipt state itself and
 fence live bootstrap/credential authority in the same owned transaction. Current
 Jump codes are 12 random bytes encoded as 16 canonical base64url characters.
 
-`bindNodeEnrollmentAcknowledgementV1` checks the complete digest, both owners,
+`bindNodeEnrollmentAcknowledgement` checks the complete digest, both owners,
 exact next generations and unchanged adopted node ID, returning a detached frozen
 acknowledgement. Authenticate Cloudly before accepting it. The acknowledgement is
 immutable commit evidence, not ongoing authority or workload readiness. Server
@@ -168,20 +193,20 @@ local activation independently and converge after restart; there is no shared
 plaintext vault or cross-local-database ACID claim. Never log proof/request bodies
 or hashes, put them in URLs, or expose them through transport hooks.
 
-`requests.pallet` defines the node-local `preparePalletNodeEnrollmentV1`,
-`bindPalletNodeEnrollmentV1` and `activatePalletNodeEnrollmentV1` methods. They
+`requests.pallet` defines the node-local `preparePalletNodeEnrollment`,
+`bindPalletNodeEnrollment` and `activatePalletNodeEnrollment` methods. They
 belong only on the protected root-owned Unix control socket, never a network
 router. Preparation requests initial Pallet authority (zero generation and
 session epoch) and returns only its independently retained credential hash.
-`snapshotPalletNodeEnrollmentPreparationV1` and
-`bindPalletNodeEnrollmentPreparationV1` validate that exact exchange.
+`snapshotPalletNodeEnrollmentPreparation` and
+`bindPalletNodeEnrollmentPreparation` validate that exact exchange.
 
 Local confirmations explicitly distinguish a durable pending binding from the
-exact current active Pallet identity. `bindPalletNodeEnrollmentBoundV1` verifies
+exact current active Pallet identity. `bindPalletNodeEnrollmentBound` verifies
 the whole enrollment digest and its pre-assignment node ID (null for fresh Jump).
-`snapshotPalletNodeEnrollmentActivationV1` captures the exact activation request,
+`snapshotPalletNodeEnrollmentActivation` captures the exact activation request,
 rejecting extra wrapper fields as well as malformed nested data.
-`bindPalletNodeEnrollmentActiveV1` takes that complete activation request and
+`bindPalletNodeEnrollmentActive` takes that complete activation request and
 verifies the full Cloudly acknowledgement, including both owners and the assigned
 node ID. Both confirmation binders return detached frozen
 snapshots captured before hashing. These are pure content checks: authenticate
@@ -189,7 +214,7 @@ the local transport separately, and have Pallet prove its current owned state
 before issuing a confirmation. A historical receipt is insufficient, and Pallet
 activation does not imply Spark activation or workload readiness.
 
-`palletNodeEnrollmentV1Contract` specifies one four-byte unsigned big-endian
+`palletNodeEnrollmentContract` specifies one four-byte unsigned big-endian
 length-prefixed UTF-8 JSON frame per direction, followed by write-half-close, at
 most 32768 request bytes and 16384 response bytes excluding the prefix. Implement
 the listener with half-open response support, strict EOF/trailing-byte rejection,
@@ -199,14 +224,14 @@ No bearer, generic rotation operation or database access is part of this IPC API
 
 ### Service Machine Credentials
 
-`requests.admin.getServiceMachineCredentialV1` inspects redacted metadata;
-`mutateServiceMachineCredentialV1` creates, rotates or revokes authority for one
+`requests.admin.getServiceMachineCredential` inspects redacted metadata;
+`mutateServiceMachineCredential` creates, rotates or revokes authority for one
 exact existing service and organization. `ensure` requires absent authority and
 a null expected generation. Rotation and revocation require the exact current
 generation. Retain the mutation ID and complete input for retry; a receipt replay
 returns historical metadata without restoring authority.
 
-`IServiceMachineGrantV1` currently grants only `platform:session`. This is separate
+`IServiceMachineGrant` currently grants only `platform:session`. This is separate
 from deployment grants, human membership and infrastructure permissions. The
 backend must authenticate each JWT against the current active credential
 generation, expiry and exact service ownership. Structural snapshot helpers do
@@ -224,7 +249,7 @@ each request against live canonical membership and policy, reserve aliases
 transactionally, reject cross-organization attachments, and retain historical
 receipts. These contracts do not implement the backend or node enforcement.
 
-`data.buildPrivateNetworkFqdnV1` produces
+`data.buildPrivateNetworkFqdn` produces
 `<alias>.n-<26 lowercase base32 characters>.o-<26 lowercase base32 characters>.internal.`
 from server-owned immutable DNS keys. Aliases are lowercase ASCII labels unique
 per network. Display-name edits do not rename DNS. A sole attachment selects its
@@ -233,7 +258,7 @@ suffix. Fully qualified names remain unambiguous across networks. Network policy
 permits member-to-member connectivity and explicitly configures or denies external
 DNS forwarding. Creating an alias does not publish public DNS, ingress or ports.
 
-`data.composeServicePrivateNetworkDnsPolicyV1(membership, networks)` derives the
+`data.composeServicePrivateNetworkDnsPolicy(membership, networks)` derives the
 service's network suffixes, the single selected search suffix, and the intersection
 of external forwarding permissions. Supply every attached network exactly once,
 with active state and matching canonical organization/DNS keys. Missing, extra,
@@ -254,7 +279,7 @@ one second. DNS expiry does not prove packet revocation or permit identity reuse
 Retirement and attachment responses describe desired or historical metadata;
 consumers must separately track outstanding node revocations and readiness.
 
-`IRuntimeNetworkProtectedAuthorityV1` declares the complete controller-owned IPv4
+`IRuntimeNetworkProtectedAuthority` declares the complete controller-owned IPv4
 protection set, disjoint private workload/transit pools, protected resolver and
 platform endpoints, and every affected egress authority, including offline nodes.
 Its snapshot and digest helpers bind the exact predecessor and all declaration
@@ -265,7 +290,7 @@ the declaration is not a revocation acknowledgement. Prefix arrays are sorted
 lexically and nonoverlapping; pools and endpoints are sorted by ID; egress owners
 are ordered by canonical JSON of `[nodeId, runtimeNamespace]`.
 
-`IRuntimeNetworkProtectionReceiptV1` reports a worker's durable, joined native
+`IRuntimeNetworkProtectionReceipt` reports a worker's durable, joined native
 protection journal separately from projection admission. It binds a complete
 protected-authority reference, node/controller scope, authenticated reporter,
 boot identity and exact native journal reference to a monotonic receipt chain.
@@ -273,10 +298,10 @@ A null `nativeBarrier` explicitly removes allocation eligibility. A boot or
 protection change requires new native journal evidence. These portable values
 do not inspect a kernel or authenticate their own producer.
 
-`reportRuntimeNetworkProtectionV1` uses the current authenticated physical peer.
+`reportRuntimeNetworkProtection` uses the current authenticated physical peer.
 Its request binder accepts a historical outbox only against receiver-owned
 reporter history and identifies that use as historical. The response must match
-the exact sent receipt. `bindRuntimeNetworkAllocationProtectionV1` requires the
+the exact sent receipt. `bindRuntimeNetworkAllocationProtection` requires the
 current persisted protection receipt and durable session for every declared
 egress owner, in canonical owner order. Missing, unavailable, stale-protection
 and superseded-session evidence reject. An offline owner cannot be omitted.
@@ -285,15 +310,15 @@ reserving any handoff or workload address. No generic independent-fence flag is
 provided; such a mechanism needs its own verified owner. Protection receipts
 neither prove workload readiness nor release packet/address/name quarantine.
 
-`IRuntimeNetworkHandoffLeaseV1` binds an immutable node/router incarnation to its
+`IRuntimeNetworkHandoffLease` binds an immutable node/router incarnation to its
 protected-authority reference, transit subnet and peers, protocol-qualified source
 ports, nonzero conntrack zone and 128-bit label. The label is exactly 32 lowercase
 hex characters. Port ranges are inclusive, sorted by protocol then first port,
-and disjoint within each protocol. `bindRuntimeNetworkHandoffLeaseV1` verifies both
+and disjoint within each protocol. `bindRuntimeNetworkHandoffLease` verifies both
 digests, scope and transit-pool containment and returns detached values. It does
 not authenticate a projection or attest to an actual namespace/interface.
 
-`snapshotRuntimeNetworkHandoffLedgerV1` verifies at most 256 retained leases for
+`snapshotRuntimeNetworkHandoffLedger` verifies at most 256 retained leases for
 one node/controller epoch, including quarantined allocations. It rejects host
 handoff-port collisions even across router/runtime namespace changes, and zone or
 label reuse within one router incarnation. The caller must transactionally supply
@@ -304,7 +329,7 @@ permits handoff identity reuse. Signed complete projections, live interface proo
 and the separate router/host apply journal remain responsibilities of Cloudly and
 Pallet; neither packet admission nor readiness follows from these helpers.
 
-`IRuntimeNetworkWorkloadLeaseV1` is the immutable material referenced by
+`IRuntimeNetworkWorkloadLease` is the immutable material referenced by
 `assignment.workload.network`. It binds one execution attempt and router
 incarnation to a workload pool, dedicated unbridged `linkSubnet`, workload
 `address`, exact `/32` `sourcePrefix`, and router-side `gateway`. The gateway
@@ -312,11 +337,11 @@ also supplies `dnsServer` on port 53, because CRI DNS settings cannot encode a
 port. Canonical private point-to-point subnets through `/31` are accepted; the
 owning CNI implementation must qualify its chosen layout. The source prefix,
 link subnet, VPN control prefix and host/router transit subnet have different
-roles. `bindRuntimeNetworkWorkloadLeaseToAssignmentV1` verifies immutable
+roles. `bindRuntimeNetworkWorkloadLeaseToAssignment` verifies immutable
 assignment identity without a circular assignment digest. Membership, aliases,
 readiness and projection revisions never change this address material.
 
-`IRuntimeNetworkProjectionV1` contains complete relevant network definitions,
+`IRuntimeNetworkProjection` contains complete relevant network definitions,
 service memberships and endpoint leases, including remote ready endpoints and
 declared services with no replicas. It carries the current protected authority,
 exact historical allocation authorities, local handoff, a maximum 15-minute DNS
@@ -329,7 +354,7 @@ and 4,096 directed grants. These transport bounds do not assert native capacity;
 the node must preflight the actual SmartVPN, Smartnftables and DNS limits before
 effectful application.
 
-`validateRuntimeNetworkProjectionV1` checks complete digest and scope bindings,
+`validateRuntimeNetworkProjection` checks complete digest and scope bindings,
 pool containment, disjoint link subnets, network/organization keys, aliases,
 resolver authorization and ready-replica uniqueness. It does not authenticate
 controller inventory, prove observation provenance or authorize allocation reuse.
@@ -338,7 +363,7 @@ retain all affected offline authorities and complete its allocation/barrier
 transactions before issuance.
 
 An endpoint may publish node ports through the optional
-`IRuntimeNetworkEndpointV1.publishedPorts`. Each `IRuntimeNetworkPublishedPortV1`
+`IRuntimeNetworkEndpoint.publishedPorts`. Each `IRuntimeNetworkPublishedPort`
 binds one `hostPort` (1..65535, unique per node and protocol across the
 projection) to the workload's `targetPort`, optionally on an explicit uplink
 `hostIp` (never the wildcard or loopback; binding it to the node's uplink is
@@ -349,23 +374,23 @@ An endpoint that publishes nothing omits the member entirely and keeps its exact
 canonical bytes and digest; a present member is never an empty list, so
 "publishes nothing" has exactly one encoding.
 
-Operators author that authorization through `getServicePublishedPortsV1` and
-`setServicePublishedPortsV1`, modelled on the private-network membership pair.
-`IServicePublishedPortsV1` returns the current authorized list with its policy
-`revision`, or null when a service never had one. `ISetServicePublishedPortsV1`
-returns the accepted `IServicePublishedPortsV1` document with its new
+Operators author that authorization through `getServicePublishedPorts` and
+`setServicePublishedPorts`, modelled on the private-network membership pair.
+`IServicePublishedPorts` returns the current authorized list with its policy
+`revision`, or null when a service never had one. `ISetServicePublishedPorts`
+returns the accepted `IServicePublishedPorts` document with its new
 `revision` and a `replayed` flag, and carries `expectedRevision` (null for the first document), a retained
-`mutationId` for replay, and `IRuntimeNetworkPublishedPortRequestV1` entries of
-exactly `protocol`, `hostPort` and `targetPort`: v1 accepts no `hostIp` (an
-omitted address means the node uplink) and no ranges. An empty list is a valid
+`mutationId` for replay, and `IRuntimeNetworkPublishedPortRequest` entries of
+exactly `protocol`, `hostPort` and `targetPort`: the request accepts no `hostIp`
+(an omitted address means the node uplink) and no ranges. An empty list is a valid
 policy meaning the service publishes nothing. Callers never supply an
 `authorization` reference: Cloudly derives each projection entry's reference
 from the accepted policy revision and digest, and node-level host-port placement
 stays Cloudly's decision.
 
-`getRuntimeNetworkProjectionPacketGrantsV1` derives directed member connectivity
+`getRuntimeNetworkProjectionPacketGrants` derives directed member connectivity
 and explicit local public/platform egress independently of DNS readiness.
-`composeRuntimeNetworkProjectionDnsViewsV1` builds one union view per local
+`composeRuntimeNetworkProjectionDnsViews` builds one union view per local
 workload source address, with every authorized FQDN and complete ready-replica A
 set. An empty array declares NODATA; absent/unauthorized names remain NXDOMAIN,
 and IPv4-only service names have AAAA NODATA. The view carries the existing
@@ -384,16 +409,16 @@ asynchronous validation and output retains projection order. This lets Pallet
 compose only its currently attached sources without duplicating membership rules;
 the references themselves do not prove native attachments or DNS authority.
 
-The optional `IRuntimeNetworkProjectionV1.router` member carries explicit
-router-origin egress selections and withdrawals. Existing persisted V1
-projections omit it, retain their exact canonical bytes/digest/signature and grant
-no router-origin flows. New issuers can select `resolverIds` and
+The optional `IRuntimeNetworkProjection.router` member carries explicit
+router-origin egress selections and withdrawals. A projection that omits it
+retains its exact canonical bytes, digest and signature and grants no
+router-origin flows. New issuers can select `resolverIds` and
 `platformEndpointIds` from the current protected inventory; an empty selection
 denies all router egress. DNS forwarding policy, workload egress and inventory
 presence alone supply no router grant. The whole member is signed with the
 projection; it is not an unsigned runtime option.
 
-`getRuntimeNetworkProjectionRouterPacketGrantsV1` validates the complete projection
+`getRuntimeNetworkProjectionRouterPacketGrants` validates the complete projection
 and returns up to 96 detached exact grants. Each binds the current local handoff
 reference and its router transit source address to a selected destination ID,
 IPv4 address, protocol and port. Resolver selection explicitly authorizes both
@@ -413,7 +438,7 @@ must compose both workload and router grants and their separate withdrawals;
 they must also fence the actual native source, routing and process lifetimes.
 DNS expiry or readiness changes do not revoke packet authority.
 
-`admitRuntimeNetworkProjectionV1` checks exact predecessor/replay identity and
+`admitRuntimeNetworkProjection` checks exact predecessor/replay identity and
 rejects changed same-generation content, regressed membership/readiness evidence,
 changed immutable address/DNS keys, and omitted packet grants without explicit
 withdrawal. Pending withdrawals/tombstones must carry forward until the caller
@@ -422,7 +447,7 @@ application receipt. That reference is never taken from an incoming ACK. Keep
 the accepted history and apply journal until native effects and DNS/allocation
 quarantine are settled; a complete new snapshot does not erase that history.
 
-`IRuntimeNetworkSigningAuthorityV1` is separate from human JWT signing. Install
+`IRuntimeNetworkSigningAuthority` is separate from human JWT signing. Install
 its current revision through the existing authenticated physical connection and
 commit it with a durable CAS fence. Newly enrolled nodes may bootstrap the
 controller's current key generation; existing trust cannot be reset to do so.
@@ -432,9 +457,12 @@ requires newly signed authority for DNS. It does not deny outstanding packets
 or permit allocation reuse.
 
 The Node-only `@serve.zone/interfaces/runtime` export supplies
-`createRuntimeNetworkSigningKeyV1`, `signRuntimeNetworkProjectionV1` and
-`verifyRuntimeNetworkProjectionV1`. The signature covers the complete canonical
-projection, signing-authority reference and dedicated signature domain. Verification
+`createRuntimeNetworkSigningKey`, `signRuntimeNetworkProjection` and
+`verifyRuntimeNetworkProjection`. Signing produces
+`ISignedRuntimeNetworkProjection { authority, projection, signature }`, and the signature
+covers the canonical envelope `{ domain, authority, projection }` under the dedicated
+`serve.zone/runtime-network-projection-signature` domain, so it binds the complete
+projection and the exact signing-authority revision. Verification
 requires receiver-owned trusted authority and node scope; an envelope contains
 no key to trust. Private KeyObjects stay process-local; Cloudly persists their
 exported material only through its encrypted internal secret store. The dedicated
@@ -442,17 +470,17 @@ exported material only through its encrypted internal secret store. The dedicate
 peer. Their response acknowledges durable admission only, never application,
 readiness, independent fencing or pool activation.
 
-The `getRuntimeManagedVpnCredentialV1` method contract in `requests.runtimesession`
-uses `IGetRuntimeManagedVpnCredentialRequestV1` and
-`IGetRuntimeManagedVpnCredentialResponseV1`. Its request carries the exact current
+The `getRuntimeManagedVpnCredential` method contract in `requests.runtimesession`
+uses `IGetRuntimeManagedVpnCredentialRequest` and
+`IGetRuntimeManagedVpnCredentialResponse`. Its request carries the exact current
 session and signed projection reference. The secret response repeats those
 bindings and supplies a QUIC relay tuple, managed authority ID, Noise server
 public key, client keypair and expiry in Unix milliseconds. Keep the response
 process-local; never persist, hash, log or embed it in a signed projection.
 
-`snapshotGetRuntimeManagedVpnCredentialRequestV1` and its response counterpart
+`snapshotGetRuntimeManagedVpnCredentialRequest` and its response counterpart
 capture closed detached JSON shapes and canonical 32-byte key encodings.
-`bindGetRuntimeManagedVpnCredentialRequestV1(request, projection, trustedSession)`
+`bindGetRuntimeManagedVpnCredentialRequest(request, projection, trustedSession)`
 validates the complete projection digest and binds node, controller, namespace,
 physical-session identity and projection reference. The response binder takes
 `(response, request, projection, trustedSession, now, renewal = null)` and additionally requires
@@ -557,6 +585,14 @@ and every window against its clock, when it admits it. The run must have:
 verifies no signature. `bindHoldRuntimeNetworkDnsLeaseRenewalsResponse(response, sentRequest)`
 requires `held` to equal the number of renewals sent.
 
+A hold is the one call whose outcome the controller cannot read back from its own records, so the
+refusal is the whole answer. `data.holdRuntimeNetworkDnsLeaseRenewalsRefusals` is the frozen list
+of names a relay leads its refusal with — `escrow-run-invalid`, `escrow-node-not-carried`,
+`escrow-run-foreign-session`, `escrow-run-stale`, `escrow-run-unordered` and `escrow-cloudly-only`
+— with `data.THoldRuntimeNetworkDnsLeaseRenewalsRefusal` as their union. The relay writes
+`<name>: <reason>` and the controller matches the name, so neither side keeps its own copy of the
+vocabulary.
+
 The horizon is also the revocation latency: a detached cluster keeps DNS authority until its last
 held window ends. So a controller must not release an address or a DNS name before the latest
 `expiresAt` it has signed for that node. Renewals extend DNS only. They grant no packet authority
@@ -568,7 +604,7 @@ node may use: the admitted renewal's if there is one, else the projection's own.
 bare `IRuntimeNetworkDnsLeaseRenewal` that admission takes and returns, which is what a node
 stores; Cloudly passes `signed.renewal`. It checks digests and that the renewal names exactly that
 projection, but verifies no signature. Controller and node use it for every limit tied to the
-window, and `bindGetRuntimeManagedVpnCredentialResponseV1` takes the same bare admitted renewal as
+window, and `bindGetRuntimeManagedVpnCredentialResponse` takes the same bare admitted renewal as
 an optional last argument, so a newly issued managed-VPN credential may run to the end of the
 renewed window instead of the projection's original one.
 
@@ -594,17 +630,83 @@ const { renewal: admittedRenewal } = await data.admitRuntimeNetworkDnsLeaseRenew
 const window = await data.getRuntimeNetworkEffectiveDnsWindow(admittedProjection, admittedRenewal);
 ```
 
+### Runtime Network Address Plan
+
+`data.IRuntimeNetworkAddressPlan` is the address space an administrator gives the runtime network,
+and the single input Cloudly composes the protected authority from:
+`{ id: 'address-plan', revision, prefixes, pools, resolvers, platformEndpoints, vpn: { controlPrefix, relay } }`.
+Pools, resolvers and platform endpoints use the protected authority's own element shapes, and the
+relay uses the managed-VPN credential's `{ id, address, port }`. `platformEndpoints` never lists the
+relay: the composed authority adds it, in id order, as the UDP platform endpoint every node dials.
+
+`snapshotRuntimeNetworkAddressPlan` refuses any plan that could describe an authority the authority
+contract refuses. It runs `snapshotRuntimeNetworkProtectedAuthority` twice, once over the plan's
+own sets and once with the relay added, so overlapping pools, more than 16 resolvers, a resolver or
+endpoint outside `prefixes` or inside a pool, and a relay that `prefixes` do not cover are all
+refused by that one validator. On top it requires the VPN `controlPrefix` to be a private prefix no
+longer than /30 (`runtimeNetworkAddressPlanContract.maximumControlPrefixLength`) inside `prefixes`
+that overlaps no pool and holds no resolver or platform endpoint, the relay included. No minimum
+length is stated: the private-range rule already keeps it at /8 or longer.
+`composeRuntimeNetworkProtectedAuthority(plan, frame)` is the composition itself: the producer
+supplies the frame (`TRuntimeNetworkProtectedAuthorityFrame`: authority id, generation, controller,
+previous reference and egress authorities) and receives the complete authority with its digest, so
+the validator and the protection producer can never compose differently.
+
+`admitRuntimeNetworkAddressPlanChange(previous | null, next)` is the pure decision for a plan write at
+the following revision; any other revision is a contract violation. Leases and the managed VPN
+outlive a plan revision, so it answers:
+
+- `unchanged` when the content equals the stored plan; Cloudly writes nothing;
+- `refused` with `plan-vpn-immutable` when the VPN differs, `plan-pool-removed` when any pool is gone
+  or changed its purpose or prefix, and `plan-prefix-shrunk` when the new prefixes, however split,
+  no longer cover every address the old ones did;
+- `accepted` with the ids of the resolvers and platform endpoints the change removes or changes. An
+  entry that keeps its id but differs in any field counts, so moving it goes through the same
+  reference check as removing it.
+
+`TRuntimeNetworkAddressPlanRefusal` adds `plan-resolver-referenced` and `plan-endpoint-referenced`,
+which only Cloudly can decide against live references, so every plan refusal has one type.
+`requests.network` carries `setRuntimeNetworkAddressPlan { identity, expectedRevision, plan }`
+(`expectedRevision: null` when no plan exists yet) and `getRuntimeNetworkAddressPlan`, which answers
+`null` until the first plan is set.
+
+### Node Network Readiness
+
+`requests.network.getRuntimeNetworkNodeReadiness { identity, nodeId }` answers
+`data.IRuntimeNetworkNodeReadiness`: `ready: true` with nothing missing, or `ready: false` with at
+least one `TRuntimeNetworkNodeReadinessGap`. The gaps follow the node producer's order: the node
+joins the protected authority's egress (`egress-pending`), every egress owner reports current
+protection (`protection-receipts-pending`, naming those `owners`, at least one), a handoff is reserved
+(`handoff-pending`), the router selection carries it (`selection-pending`), the node's acknowledged
+projection carries it (`projection-pending`), and the node is a managed VPN member
+(`vpn-member-pending`).
+
+`data.IRuntimeRouterIncarnation { id, incarnation }` is a node's router incarnation, from which its
+handoff and router incarnation ids derive; `snapshotRuntimeRouterIncarnation` checks the record.
+`reincarnateRuntimeNetworkRouter { identity, nodeId, expectedIncarnation }` advances it, so the node
+producer reserves the router a fresh handoff, and answers with the new incarnation.
+
 ### Node-Bound Runtime Assignments
 
-The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,
-`evaluateRuntimeAssignmentV1`, and assignment observation validators/evaluators
+The `data` namespace exports `IRuntimeAssignment`, canonical digest helpers,
+`evaluateRuntimeAssignment`, and assignment observation validators/evaluators
 for Cloudly/Onebox controllers and Pallet nodes. These are shared contracts;
 they do not install a runtime, schedule containers or expose an RPC endpoint.
 
 Each assignment binds a controller incarnation, organization, stable node and
 replica IDs, one immutable execution attempt, image/configuration and opaque
 network/storage/secret references. Group and site IDs are nullable topology
-provenance. All fields except the digest itself participate in a domain-separated
+provenance. Those workload references are also the authority vocabulary:
+`data.runtimeWorkloadAuthorities` is `['network', 'secrets', 'storage']`, and
+`data.requiredWorkloadAuthorities(workload)` names the ones this workload cannot
+run without — filtered out of that vocabulary and sorted, so the answer is
+duplicate-free and compares byte for byte against the `resolvedAuthorities` a node
+stated when it registered. `data.isResolvedWorkloadAuthorities(value)` is the same
+rule read the other way, for a receiver checking a list it was sent. Canonical is
+strictly increasing in the code-unit order of the names themselves — a rule a peer
+in another language implements from the vocabulary alone, rather than from the
+order this package happens to declare it in — and both directions compare through
+that one rule, so neither can drift from the other. All fields except the digest itself participate in a domain-separated
 SHA-256 digest. Digests provide integrity and compare-and-swap identity;
 authentication must separately establish the trusted controller/node scope.
 
@@ -630,10 +732,10 @@ does not authorize storage relocation or prove fencing.
 
 ### Resolved Runtime Configuration
 
-`data.IRuntimeConfigV1` seals the public environment, working directory, resource
+`data.IRuntimeConfig` seals the public environment, working directory, resource
 and identity policies, target ports, readiness timing and log limits together with
-the immutable image invocation. `computeRuntimeConfigV1Digest` hashes that exact
-content; `bindRuntimeConfigV1ToAssignment` checks the config reference, service,
+the immutable image invocation. `computeRuntimeConfigDigest` hashes that exact
+content; `bindRuntimeConfigToAssignment` checks the config reference, service,
 organization, image and selected platform against one assignment. Secret material,
 registry credentials and host paths remain outside the configuration.
 
@@ -648,14 +750,14 @@ Existing numeric configurations retain their exact meaning and digest.
 
 ### Authenticated Runtime Sessions
 
-`requests.runtimesession` defines `registerPalletRuntimeSessionV1`,
-`applyRuntimeAssignmentV1`, `reportRuntimeAssignmentObservationV1`, and
-`getRuntimeRegistryCredentialV1`. Pallet initiates WSS through its configured
+`requests.runtimesession` defines `registerPalletRuntimeSession`,
+`applyRuntimeAssignment`, `reportRuntimeAssignmentObservation`, and
+`getRuntimeRegistryCredential`. Pallet initiates WSS through its configured
 Cloudly HTTPS origin, or, on a relayed cluster, through the relay origin its
 cluster publishes in [`ICluster.data.relay`](#cluster-relay-block) while Cloudly
 remains the credential authority. The receiver derives the physical peer, process instance
 and registration idempotency; callers cannot supply those authorities. A serialized
-`IRuntimeSessionBindingV1` provides content to compare with authenticated peer
+`IRuntimeSessionBinding` provides content to compare with authenticated peer
 state and does not itself authenticate a connection. Registry credentials are
 ephemeral, bounded and authorized against an exact current `run` assignment.
 
@@ -670,14 +772,31 @@ classify content; authentication and atomic receipt persistence remain server-ow
 
 A registration is identified by its node, its credential generation and
 `nodeInstanceNonce`: a canonical lowercase UUID that Pallet generates once per
-process start and sends on every registration. Version 31.1 adds that optional
-field. One physical socket may carry the registrations of many nodes — a cluster
-relay forwards a whole cluster — so the transport alone can no longer tell a
-node restart from a replay. A controller must require the nonce whenever the
-registering peer is such a relay, and may accept its absence only from a
-directly connected node, whose own socket names its process. The nonce is not a
-secret, is not authentication, and grants nothing on its own: the bearer still
-authenticates every registration.
+process start and sends on every registration. From 32.0.0 the field is required,
+so a controller no longer has a nonce-less case to decide. One physical socket may
+carry the registrations of many nodes — a cluster relay forwards a whole cluster —
+so the transport alone can no longer tell a node restart from a replay. The nonce
+is not a secret, is not authentication, and grants nothing on its own: the bearer
+still authenticates every registration.
+
+The registration also states `resolvedAuthorities`: which of
+`data.runtimeWorkloadAuthorities` (`network`, `secrets`, `storage`) this node
+build can resolve, sorted and duplicate-free so a replay compares byte for byte.
+It is a capability of the registering build, never a permission: a controller
+refuses an assignment whose `data.requiredWorkloadAuthorities(workload)` the list
+does not cover, instead of a node accepting work it cannot carry out. It is not
+part of the registration identity — a changed build is a new process and
+therefore a new nonce — so a replay that states different authorities is a
+conflict rather than an update.
+
+Every registration carries `protocol`, and the controller judges the body in the
+one server order `protocol.readProtocolOffer` states: the bounded body, the offer,
+`protocol.negotiateProtocol` against this session kind's own offer, and only then
+the exact-key validator, the bearer and any mutation. For a node that order is what
+keeps a refused registration from touching its packet access.
+`registerPalletRuntimeSession` answers `{ session, protocol }`, and
+`data.bindRegisterPalletRuntimeSessionResponse` binds that answer to the request
+the node sent and negotiates the two offers from the node's side.
 
 A changed nonce, or a changed credential generation, is a new registration: the
 controller mints a new binding and a new session epoch and fences the node's
@@ -687,15 +806,16 @@ transport reconnect: a node that rotates behind a relay registers again with its
 unchanged nonce and its new generation on the same live socket, and the other
 nodes that socket carries are untouched.
 
-`registerCloudlyClientSessionV1` separately authenticates a current human or
-machine JWT on a physical TypedSocket so the server can own its identity tag.
-Both registration methods reject HTTP transport. Sensitive requests and registry
+`registerCloudlyClientSession` separately authenticates a current human or
+machine JWT on a physical TypedSocket so the server can own its identity tag; it
+carries the same offer, judged in the same order before the JWT, and answers with
+the server's own offer. Both registration methods reject HTTP transport. Sensitive requests and registry
 responses must be excluded from hooks, logs, diagnostics and durable journals.
 
 ### Joined Runtime Terminal Receipts
 
-`data.IRuntimeAssignmentTerminalReceiptV1` and
-`requests.runtimesession.reportRuntimeAssignmentTerminalReceiptV1` carry a separate
+`data.IRuntimeAssignmentTerminalReceipt` and
+`requests.runtimesession.reportRuntimeAssignmentTerminalReceipt` carry a separate
 receipt for the exact Pallet attempt's joined terminal execution. Sequence 1 binds
 the generation 2 stop assignment; sequence 2 binds generation 3 removal and the
 exact stop receipt digest. Both retain the original generation 1 run reference.
@@ -713,7 +833,7 @@ terminal operation but cannot skip the stop/remove chain.
 
 The synchronous snapshot helpers validate bounded exact data only. Digest,
 assignment-chain and receipt-chain helpers do not prove native execution or
-authenticate a reporter. `bindRuntimeReporterSessionV1` and the terminal report
+authenticate a reporter. `bindRuntimeReporterSession` and the terminal report
 binder require the current physical session and immutable server-indexed reporter
 history from their trusted owners. Reconnect recovery preserves every original
 receipt field and returns `historical-recovery`; it never restores active
@@ -727,26 +847,77 @@ only the named Pallet attempt. They do not authorize storage relocation, prove
 whole-host or Docker/Coreflow absence, grant another controller or organization
 authority, or replace independently qualified readiness and routing evidence.
 
-### Offline Database Settlement And Packaging
-
-The Node-only `@serve.zone/interfaces/runtime` export includes isolated V1
-metadata and control codecs for describing and validating settlement of one
-immutable `smartdb.database.export.v1` file offline. The protocol binds exact
-source bytes to source authority A, an
-HMAC-authenticated rehearsal, a distinct later production-transform authority
-B, an HMAC-authenticated transform authorization, exact transformed-core bytes,
-a deterministic HMAC-authenticated terminal journal, exact complete output
-bytes, an HMAC-authenticated complete-output receipt, and a bounded result.
-The journal ID seed excludes `_id` and `mac`; its HMAC input excludes only
-`mac`. Only the external complete-output receipt identifies the final output
-bytes. These contracts make no transaction or committed-write claim and leave
-the existing transaction settlement contracts unchanged. They neither carry
-the export bytes or Base64 content nor execute the settlement.
-
-The same runtime export provides metadata-only Corestore database-export
-package contracts. A package request carries exact input length and SHA-256,
-approved source-backup and complete-output-receipt digests, a path-safe attempt
-ID, and an explicit `absent` or `exact` allocation expectation. It never carries
+### Cluster Runtime Phase
+
+`data.IClusterRuntime { id, phase, generation, changedAt, changedBy }` records which runtime owns a
+cluster's workloads: `TClusterRuntimePhase` is `swarm`, `draining`, `switching` or `pallet`. It is
+stored beside the cluster document, because a cluster update merges caller data and no caller may
+move a phase with it; `generation` is its compare-and-swap counter. `snapshotClusterRuntime` checks
+the record. Which phase may follow which belongs to the cutover, whose requests ship with it.
+
+`requests.cluster.getClusterRuntime { identity, clusterId }` answers `{ runtime, blockers }`. Each
+`TClusterRuntimeBlocker` names what it is about: cluster-wide blockers (`relay-not-enabled`,
+`relay-not-registered`, `address-plan-missing`, `vpn-unconfigured`) name nothing, node blockers
+(`node-without-pallet-credential`, `node-arch-unsupported`) name the `nodeId`, and service blockers
+(`service-multi-cluster-scope`, `service-authority-unsupported`, `platform-binding-present`) name
+the `serviceId`.
+
+### Service Runtime Specs And Status
+
+`data.IServiceRuntimeSpec` is what Cloudly runs for one service on a Pallet cluster:
+`{ id, organizationId, clusterId, placement, replicasPerNode, hold, profile, network, revision }`.
+It is stored complete and beside the service document, so a hold written by a cutover never races
+an operator's service edit.
+
+- `placement` is `{ kind: 'every-node' }` or `{ kind: 'nodes', nodeIds }`, with `nodeIds` sorted,
+  unique, never empty and at most `maximumPinnedNodes`, the protected authority's egress limit.
+- `replicasPerNode` runs from 1 to 64; Cloudly refuses a service desiring more than `maximumReplicas` (64) as `replica-limit`.
+- `profile { cpuMillis, memoryBytes, readiness, logs, readonlyRootfs, runAs }` is the runtime config's
+  execution policy ahead of any image: the same readiness and log shapes, and the same CPU, memory
+  (at least 16 MiB), identity, log, readiness timing and HTTP request rules, which both validators
+  share. `runAs: null` runs the image's own OCI user. Only the service's target ports decide whether
+  a readiness probe's target exists: the runtime config requires the service to declare it, and the
+  producer refuses a service that does not as `readiness-target-undeclared`.
+- `network` is `{ mode: 'isolated' }` or `{ mode: 'attached', publicEgress, platformEndpointIds }`
+  with sorted unique endpoint ids.
+
+`snapshotServiceRuntimeSpec` checks all of that; whether the cluster, the nodes and the endpoints
+exist is Cloudly's. `requests.service.setServiceRuntimeSpec { identity, serviceId, expectedRevision, spec }`
+writes `TServiceRuntimeSpecWritableData`, and Cloudly copies the organization from the service.
+`getServiceRuntimeSpec` answers `{ spec, status }`: both `null` before the first spec, and `status`
+`null` until the producer first decides the spec. A status never comes without its spec.
+
+`data.IServiceRuntimeStatus { id, specRevision, state, reason, changedAt }` is the producer's verdict
+on one spec revision, and each reason belongs to exactly one state. `converged` and `converging`
+carry `reason: null`. `waiting` carries a `TServiceRuntimeWaitingReason`: `node-network-pending`,
+`conflict` or `failure-backoff`. `refused` carries a `TServiceRuntimeRefusal`:
+`cluster-runtime-missing`, `organization-missing`, `image-plan-missing`, `platform-unsupported`,
+`secrets-unsupported`, `volumes-unsupported`, `port-protocol-unsupported`,
+`readiness-target-undeclared`, `environment-too-large`, `no-eligible-node` or `replica-limit`. A
+refusal never retires running slots. `snapshotServiceRuntimeStatus` enforces the pairing.
+
+### Runtime Assignment Views
+
+`data.IServiceRuntimeAssignmentView` is one replica slot's current assignment as an administrator
+reads it: `serviceId`, `replicaId`, `nodeId`, the current `assignment` reference, its `disposition`,
+the latest accepted `observation { phase, ready, observedAt, sequence }` (which may cite an earlier
+revision), `terminalReceiptCount` (0 to 2) and `delivery`. `delivered` means the node's own evidence,
+an observation or a terminal receipt, cites the current revision; until then it is `undelivered`.
+
+`requests.service.getServiceRuntimeAssignments { identity, serviceId }` answers every slot of one
+service. `requests.cluster.getClusterRuntimeAssignments { identity, clusterId, cursor, limit }` pages
+through every slot on a cluster's nodes; `limit` runs from 1 to
+`serviceRuntimeContract.maximumAssignmentPageSize` (256), and Cloudly refuses any other.
+`requests.service.pushServiceRuntimeChanged { serviceId }` tells admin UIs that a service's spec,
+status or assignments changed; it carries no state, so a late push never overwrites a newer read.
+
+### Corestore Database Export Packaging
+
+The Node-only `@serve.zone/interfaces/runtime` export provides metadata-only
+Corestore database-export package contracts. A package request carries exact
+input length and SHA-256, approved source-backup and complete-output-receipt
+digests, a path-safe attempt ID, and an explicit `absent` or `exact` allocation
+expectation. It never carries
 the export bytes or Base64 content. Immutable completion binds the normal
 Corestore database backup receipt and exact closure identity; delivery wrappers
 may report exact replay without changing completion. Release is permitted only
@@ -754,10 +925,18 @@ against the caller's exact fsynced closure and receipt identities. API-token
 authentication remains transport authority, and these Corestore contracts do
 not claim to verify Cloudly authority-B HMACs.
 
-Exact source, transformed-core, and complete-output identities include one
-terminating LF and are limited to 96 MiB plus that LF. Journal-induced output
-growth is limited to 64 KiB. Package control metadata is limited to 16 KiB and
-keeps the existing 256 MiB Corestore closure limit.
+Exact input identities include one terminating LF and are limited to 96 MiB
+plus that LF. Package control metadata is limited to 16 KiB and keeps the
+existing 256 MiB Corestore closure limit.
+
+One media type and one backup format are stated here for every process that
+handles a Corestore database backup: `runtime.corestoreDatabaseBackupMediaType`
+(`application/vnd.serve-zone.corestore-database-backup`) is the type an archive
+is served and stored under, and `runtime.corestoreDatabaseBackupFormat`
+(`corestore.database.backup`) is the format a receipt states. Corestore's
+control server, its export packager, Onebox and the cluster relay import them
+instead of writing the bytes again, so the side that writes a transfer and the
+side that reads it cannot disagree about its type.
 
 Service creation carries canonical ownership separately from caller-writable
 service data. `requests.service.IRequest_Any_Cloudly_CreateService` requires a
@@ -766,13 +945,97 @@ server-managed ownership field. Consumers should use
 `data.validateOrganizationId()` to validate the identifier shape and verify
 the request's ownership authorization separately before persistence.
 
+## Protocol handshake
+
+The protocol version is the installed `@serve.zone/interfaces` release. There is no protocol
+number beside it, no per-shape version suffix and no `schemaVersion` field: one release of this
+package is exactly one contract, so naming the release states everything about what a peer sends
+and what it can read.
+
+Two peers exchange an offer when a session opens and refuse an incompatibility by name:
+
+```typescript
+import { protocol } from '@serve.zone/interfaces';
+import { TypedResponseError } from '@api.global/typedrequest';
+
+// One offer per session kind a deployable serves, built once at start-up. A deployable that
+// depends on nothing newer than its own major accepts that whole major.
+const [installedMajor] = protocol.protocolVersion.split('.');
+const ownOffer = protocol.createProtocolOffer(`${installedMajor}.0.0`);
+
+// Server, on every carrier: the bounded body, then the offer, then everything else — the
+// exact-key validator, the bearer and any mutation.
+const peerOffer = protocol.readProtocolOffer(requestBody);
+const negotiation = protocol.negotiateProtocol(ownOffer, peerOffer);
+if (!negotiation.compatible) {
+  throw new TypedResponseError(
+    protocol.describeProtocolRefusal(negotiation.refusal),
+    negotiation.refusal,
+  );
+}
+
+// Client, on the payload of a failed hop: `TypedResponseError.errorData` on a TypedRequest, the
+// parsed body on the Spark heartbeat's refusal status. Everything else is not a refusal.
+const refusal = protocol.readProtocolRefusal(errorData);
+if (refusal) {
+  logger.warn(protocol.describeProtocolRefusal(refusal));
+  // A refusal stands until an operator upgrades one of the two sides, so the client waits.
+  setTimeout(offerAgain, protocol.refusedOfferRetryIntervalMs);
+}
+```
+
+| Export | Purpose |
+| --- | --- |
+| `protocolVersion` | The installed release, taken from the package's own commit info. |
+| `IProtocolOffer` | `{ interfacesVersion; minimumPeerVersion }` — what a side speaks and the oldest peer it accepts. |
+| `createProtocolOffer(minimumPeerVersion)` | This build's offer. A minimum above the installed release, or in another major, throws here — at start-up, not at the first registration. |
+| `validateProtocolOffer(value, path?)` | Every reason an offer is refused, as an array of messages; empty for a valid offer. |
+| `validateProtocolOfferOn(body, path?)` | The same reasons for the `protocol` key of a body, read as a data property. The naming twin of `readProtocolOffer`, for validators that list reasons instead of throwing. |
+| `readProtocolOffer(body)` | The offer on a body, read from the `protocol` key alone and returned detached. |
+| `negotiateProtocol(local, remote)` | `{ compatible: true }` or `{ compatible: false; refusal }`. Pure; throws when either side's offer names something that is not a release version. |
+| `IProtocolRefusal` | `{ code: 'protocol-incompatible'; reason; refusing; refused }`, carried as `TypedResponseError.errorData` or as a plain HTTP JSON body. |
+| `TProtocolIncompatibility` | `'major-mismatch'`, `'peer-below-minimum'`, `'self-below-peer-minimum'`. |
+| `readProtocolRefusal(value)` | The refusal inside an error payload (`TypedResponseError.errorData`) or a response body, or `null` when the value is not one. |
+| `describeProtocolRefusal(refusal)` | One log line naming both sides, opening with the frozen `protocol-incompatible` code. |
+| `refusedOfferRetryIntervalMs` | `300_000` — the shared cadence at which a refused client offers again. |
+
+`negotiateProtocol` checks in a fixed order: different majors are `major-mismatch` even when a
+minimum would also fail, then a remote below the local minimum is `peer-below-minimum`, then a
+local below the remote minimum is `self-below-peer-minimum`. The last two are mirror images of one
+another — one holding on this side means the other holds on the peer — and they can never hold at
+once, which would require each version to be below the other. An offer that does not name two
+release versions is a local defect, not an incompatibility between two peers: `negotiateProtocol`
+throws on it, and a peer-sent body is read with `readProtocolOffer` first, which refuses it by
+name. Both offers and refusals come back frozen and detached from the values they were read from.
+
+**Every carrier reads the offer once, as data.** A `protocol` key, or a member of the offer under
+it, that is an accessor rather than a plain value is refused as "must use its exact schema" and is
+never invoked — by `readProtocolOffer`, by `validateProtocolOfferOn`, by `validateProtocolOffer`
+and by `readProtocolRefusal` alike. No snapshot, validator or client on any carrier runs code a
+peer attached to a body, and none of them can observe one value while a session is served by
+another. This is stated here and nowhere else: the families that carry an offer go through these
+functions rather than restating the rule.
+
+A carrier that negotiates puts the offer in a top-level `protocol` key on both its request and its
+response, and a server reads it before it validates the rest of the body, authenticates or changes
+any state. Validators in this package are exact-key, so a body from a later major is unreadable by
+an older build; reading the offer first is what turns that into a named refusal instead of a
+generic contract rejection, and it keeps a refused peer's credentials, sessions and packet access
+untouched.
+
+Versions are `MAJOR.MINOR.PATCH` and nothing else — no prerelease, no build metadata, no `v`
+prefix, no leading zeros — and are compared per numeric component, so `32.10.0` is above `32.9.0`.
+`minimumPeerVersion` is in the same major as `interfacesVersion` and never above it. Each
+deployable owns its minimums, one per session kind it serves, and raises one only in the commit
+that starts depending on a later interfaces minor, for that session kind alone.
+
 ## Secrets v24 Pre-Cutover Contract
 
 Version 24 retains the value-free v23 architecture while replacing the remaining
 pre-cutover lifecycle and runtime authority gaps. Secret values enter Cloudly
 only as strict SmartCrypto X25519 envelopes or an explicit bounded
-server-generation request. Coreflow receives a full digest-verified schema-v2
-manifest plus one sealed envelope per pinned SecretVersion through the Node-only
+server-generation request. Coreflow receives a full digest-verified manifest
+plus one sealed envelope per pinned SecretVersion through the Node-only
 runtime export.
 
 This is a contract release before consumer cutover. It does **not** claim that
@@ -796,7 +1059,7 @@ The current secret contract includes:
   `requests.secret.IReq_GetSecretIngressRecipient` contract with method
   `getSecretIngressRecipient`, and fixed-order create/rotate/App Store context
   builders.
-- `ISecretEnvelopeAdmissionBindingV1` under the Node-only runtime export binds
+- `ISecretEnvelopeAdmissionBinding` under the Node-only runtime export binds
   an exact envelope and request context to one recipient generation. The
   binding is reproducible and does not itself prove admission. Retiring-key
   retries require a trusted Cloudly mutation receipt created atomically while
@@ -808,12 +1071,12 @@ The current secret contract includes:
   non-issuable `purge-pending` lifecycle and revisioned
   `pending`/`erasing`/`failed`/`succeeded` operation keep external erasure
   durable across retries without treating preflight as authorization.
-- Schema-v2 `IResolvedSecretManifest` contracts, stable Docker resource naming,
+- `IResolvedSecretManifest` contracts, stable Docker resource naming,
   WorkloadInit map/wrapper helpers, and `ISealedResolvedSecretMaterial` under
   `@serve.zone/interfaces/runtime`.
 - Two-step Coreflow X25519 recipient enrollment and exact recipient lifecycle
   validators.
-- Mandatory `IImmutableContainerInvocationV1` evidence on immutable image
+- Mandatory `IImmutableContainerInvocation` evidence on immutable image
   deployment plans.
 
 ### Secrets v24 Runtime Registration And Reporting
@@ -826,7 +1089,7 @@ Coreflow connection:
   empty state or the complete valid recipient set for the cluster derived from
   the verified JWT.
 - `getCoreflowSecretRuntimeRegistrationExpectation` returns either an
-  `available` v2 expectation or an explicit unavailable reason. The available
+  `available` expectation or an explicit unavailable reason. The available
   expectation binds the live reporter session, active recipient, fresh
   generation-fenced target authority, and active WorkloadInit approval through
   `expectationDigest`.
@@ -835,17 +1098,19 @@ Coreflow connection:
   credential, reconciles manager consensus privately, and publishes one fresh
   single-Swarm target authority or a targetless unavailable state. Structural
   contract validation does not itself establish manager consensus.
-- `TSparkSwarmObservationV2` lets workers report only their local Swarm node ID,
+- `TSparkSwarmObservation` lets workers report only their local Swarm node ID,
   because Docker does not expose the Swarm cluster ID to workers. Cloudly may
   associate that node with a cluster only through authenticated node scope and
-  accepted manager consensus. The v2 transport contract designates
-  `/spark/v2/nodes/swarm-observation`. A conforming Spark sender must retain one
-  exact request until it receives a request-bound acceptance receipt. A
-  conforming Cloudly consumer must authenticate the node before inspecting
-  replay state, derive cluster scope from that persisted identity, and never
-  register, translate, or accept v1 observations as an authority fallback.
-- `computeSparkSwarmObservationV2Digest` uses strict canonical JSON and the
-  `serve.zone/spark-swarm-observation-v2` domain. A reporter session starts at
+  accepted manager consensus. The transport contract designates
+  `sparkSwarmNodeContracts.swarmObservation`, whose endpoint is
+  `/spark/swarm-nodes/swarm-observation` and whose `maxRequestBytes` covers the
+  largest snapshot this validator accepts; every body on it carries the sender's
+  `protocol` offer. A conforming Spark sender must retain one exact
+  request until it receives a request-bound acceptance receipt. A conforming
+  Cloudly consumer must authenticate the node before inspecting replay state and
+  derive cluster scope from that persisted identity.
+- `computeSparkSwarmObservationDigest` uses strict canonical JSON and the
+  `serve.zone/spark-swarm-observation` domain. A reporter session starts at
   sequence one. The contract requires a Cloudly consumer to accept only the
   exact next sequence with a strictly advancing `observedAt`, while an exact
   same-sequence/same-digest retry returns the byte-equivalent persisted receipt
@@ -855,25 +1120,42 @@ Coreflow connection:
   sequence-one observation must still advance the permanent timestamp
   high-water mark. The consumer must persist acceptance state and its receipt
   in one atomic boundary.
-- `validateSparkSwarmObservationV2` validates exact structure and attached
-  snapshots, while `validateSparkSwarmObservationV2Request` and
-  `validateSparkSwarmObservationV2Response` validate transport and request
+- `validateSparkSwarmObservation` validates exact structure and attached
+  snapshots, while `validateSparkSwarmObservationRequest` and
+  `validateSparkSwarmObservationResponse` validate transport and request
   binding. None of these functions authenticates a node, persists replay state,
   establishes manager consensus, or creates runtime authority.
 - WorkloadInit approval binds a clean stable release identity, version-tagged
   OCI index, exact amd64 and arm64 platform/executable digests, policy
   generation, and a Cloudly summary of detached Cosign DSSE/SLSA verification.
   Public shape and digest validators do not verify the signature, public-key
-  trust root, or private Cloudly policy.
+  trust root, or private Cloudly policy. The provenance identifiers a verifier
+  matches are `workloadInitReleaseContract.buildType`
+  (`https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker`) and
+  `builderId` (`https://serve.zone/builders/workloadinit-manual-release`); the
+  in-toto statement type, the SLSA predicate type, the Cosign bundle format and
+  the OCI index media type keep the exact bytes their own specifications define.
+  An approval carries no shape version, and
+  `IWorkloadInitApprovalAuthorityReference` states only the counter
+  `authorityGeneration` beside the approval digest it points at.
 - `coreflowSecretRuntimeRegistrationTagId` is the sole dedicated TypedSocket
   tag identifier. Its payload is exactly
-  `ICoreflowSecretRuntimeRegistrationV2`; cluster scope comes from the verified
+  `ICoreflowSecretRuntimeRegistration`; cluster scope comes from the verified
   connection identity rather than the tag.
-- `ICoreflowSecretRuntimeRegistrationV2` references the exact expectation,
+- `ICoreflowSecretRuntimeRegistration` references the exact expectation,
   target generation/digest, and WorkloadInit authority. It must cover every
   Cloudly-node/Swarm-cluster/Swarm-node identity and approved per-platform
   manifest and installed-executable digest without self-asserting placement or
   approval.
+- `capabilities` is a sorted, duplicate-free list of `data.TCoreflowRuntimeCapability`
+  names drawn from `data.coreflowRuntimeCapabilities`, judged by
+  `data.isCoreflowRuntimeCapabilityList`. A build states what it can do by name;
+  which shape it speaks is the interfaces version both peers exchanged. Every
+  name in `data.requiredCoreflowRuntimeCapabilities` must be present. That list
+  is the vocabulary minus `data.optionalCoreflowRuntimeCapabilities`, which
+  holds `corestore-inventory` alone: it is the one capability a build may lack,
+  because it depends on the node's Corestore deployment rather than on the
+  contracts the build was compiled against.
 - `validateCoreflowSecretRuntimeRegistration` compares the registration with a
   trusted expectation built by Cloudly, including the live reporter session.
   Missing, extra, duplicate, reordered, or mismatched node evidence fails
@@ -955,7 +1237,7 @@ const storageConfig: appstore.IAppStoreVersionConfig = {
       delivery: {
         type: 'file',
         targetPath: '/run/secrets/backup-archive.json',
-        format: 'servezone-object-storage-v1',
+        format: 'servezone-object-storage',
         uid: 1000,
         gid: 1000,
         mode: 0o400,
@@ -964,10 +1246,10 @@ const storageConfig: appstore.IAppStoreVersionConfig = {
     },
   ],
   requiresFeatures: [
-    appstore.appStoreStorageFeatureIds.bindingsV2,
-    appstore.appStoreStorageFeatureIds.filesystemV1,
-    appstore.appStoreStorageFeatureIds.objectStorageV2,
-    appstore.appStoreStorageFeatureIds.objectStorageFileV2,
+    appstore.appStoreStorageFeatureIds.bindings,
+    appstore.appStoreStorageFeatureIds.filesystem,
+    appstore.appStoreStorageFeatureIds.objectStorage,
+    appstore.appStoreStorageFeatureIds.objectStorageFile,
   ],
 };
 ```
@@ -1191,7 +1473,7 @@ Common data contracts include:
 - `IDomain`, `IDnsEntry`, and traffic contracts for routing and DNS management.
 - Traffic and gateway route contracts including `ICoretrafficPortRouteConfig`, routing `portRoutes`, and `IGatewayClientRoute` client-owned route views. Gateway route intent supports optional match `domains`, `transport`, and `remoteIngress`, plus explicit route `priority` and `managedRouteKind`. Ownership can combine `hostname` with `routeRef` so a normal route and a path-specific managed route for the same hostname reconcile independently.
 - Value-free `ISecretMetadata`, `ISecretVersionMetadata`, and `ISecretSetMetadata`
-  contracts for operator views, plus schema-v2 exact-version
+  contracts for operator views, plus exact-version
   `IResolvedSecretManifest` contracts for cluster delivery. Manifest helpers
   bind immutable image rollout and invocation evidence, enforce canonical
   digests and globally unique launcher/file targets, and track per-cluster
@@ -1213,7 +1495,7 @@ Common data contracts include:
 
 ### Cluster Relay Block
 
-`ICluster.data.relay` is the optional `IClusterRelayV1 { schemaVersion: 1; origin: string }`
+`ICluster.data.relay` is the optional `IClusterRelay { origin: string }`
 that states how cluster-side components reach this cluster's relay. It is absent on a cluster
 whose nodes still target Cloudly directly, so its presence is what marks a cluster as relayed.
 
@@ -1222,7 +1504,7 @@ session registers over, as described in [Authenticated Runtime Sessions](#authen
 It must be an `https:` origin with no path, query, fragment, userinfo or trailing slash, so that
 `new URL(origin).origin === origin`; an explicit port is allowed, and because `URL` drops a
 default port and lowercases the host, `https://relay.example:443` and `https://Relay.example`
-are not canonical origins. `validateClusterRelayV1(value, path?)` returns one named reason per
+are not canonical origins. `validateClusterRelay(value, path?)` returns one named reason per
 violation and an empty array for a valid block.
 
 The relay's certificate subject is not a second field: every consumer derives it from the origin
@@ -1230,31 +1512,41 @@ with `clusterRelayCertificateDomainName(relay)`, which returns the origin's host
 Cloudly issues the certificate for and owns the A record for. An origin naming an address literal
 therefore has no issuable certificate.
 
+`data.clusterRelayUndispatchedRefusals` names the three registration refusals that end a relay's
+custody — `relay-cluster-not-enabled`, `relay-node-foreign` and `relay-sequence-not-advancing` —
+with `data.TClusterRelayUndispatchedRefusal` as their union. Each is Cloudly reading its own
+records and stating that it does not dispatch to this relay, so a relay that hears one drops what
+it holds for its nodes instead of waiting. A refusal that only says Cloudly could not verify the
+relay states nothing about dispatch and is deliberately not in the list.
+
 ```typescript
-const relay: data.IClusterRelayV1 = {
-  schemaVersion: 1,
+const relay: data.IClusterRelay = {
   origin: 'https://relay.cluster-a.serve.zone:8443',
 };
 
-const reasons = data.validateClusterRelayV1(relay); // []
+const reasons = data.validateClusterRelay(relay); // []
 const certificateDomainName = data.clusterRelayCertificateDomainName(relay);
 // 'relay.cluster-a.serve.zone'
 ```
 
-Enabling a relay is one operator flip per cluster. `enableClusterRelayV1 { identity, clusterId }`
-answers with the block Cloudly published, and `disableClusterRelayV1` removes it and answers with
+Enabling a relay is one operator flip per cluster. `enableClusterRelay { identity, clusterId }`
+answers with the block Cloudly published, and `disableClusterRelay` removes it and answers with
 an explicit `relay: null`. The caller names only the cluster: Cloudly derives the origin itself
 from that cluster and its own public hostname, and refuses the request when no DNS zone it
 manages matches the derived name, so a relay name that nothing can publish is never written.
 Both requests push the cluster configuration to the connected relay afterwards, so a relay learns
 the change without reconnecting.
 
-Once its socket is authenticated with `registerCloudlyClientSessionV1`, the relay sends
-`registerClusterRelayV1` carrying `IClusterRelayRegistrationV1`: the relay build, the cluster node
-it runs on, the exact endpoint it bound for its cluster's Pallet nodes, and a
+Once its socket is authenticated with `registerCloudlyClientSession`, the relay sends
+`registerClusterRelay` carrying `IRegisterClusterRelayRequest`: the relay build, the cluster node
+it runs on, the exact endpoint it bound for its cluster's Pallet nodes, its `protocol` offer, and a
 `registrationSequence` that counts up once per registration within one relay process and restarts
-at `0` when that process restarts. `validateClusterRelayRegistrationV1(value, path?)` returns one
-named reason per violation, like every validator here, and checks shape only. `listenAddress` is
+at `0` when that process restarts. `validateRegisterClusterRelayRequest(value, path?)` returns one
+named reason per violation, like every validator here, and checks shape only; it validates the
+offer through the one grammar `protocol` owns. Cloudly reads and negotiates that offer before it
+takes the verified cluster connection or decides the sequence, so a refused registration consumes
+no sequence, and the accepted answer carries Cloudly's own offer beside the origin. `relay.version`
+stays the relay build — a different fact from `protocol.interfacesVersion`, the contract it speaks. `listenAddress` is
 an IPv4 literal because Cloudly publishes it verbatim as the A record of the relay's certificate
 domain name — a hostname would need a `CNAME` and an IPv6 address an `AAAA` record, so admitting
 either is an additive change once Cloudly publishes it. A loopback or link-local address is
@@ -1285,8 +1577,8 @@ present with an empty one. `validateClusterRelayRegistration(value, path?)` retu
 reason per violation, as every validator here does.
 
 ```typescript
-const registration: data.IClusterRelayRegistrationV1 = {
-  schemaVersion: 1,
+const registration: data.IRegisterClusterRelayRequest = {
+  protocol: protocol.createProtocolOffer('32.0.0'),
   relay: {
     version: '4.0.0',
     nodeId: 'node-a',
@@ -1296,7 +1588,7 @@ const registration: data.IClusterRelayRegistrationV1 = {
   registrationSequence: 0,
 };
 
-const registrationReasons = data.validateClusterRelayRegistrationV1(registration); // []
+const registrationReasons = data.validateRegisterClusterRelayRequest(registration); // []
 ```
 
 How the relay reaches each node's Corestore is part of the same document: see
@@ -1330,7 +1622,7 @@ credential is excluded.
 | --- | --- | --- |
 | `pushClusterRouteTable` | Cloudly → relay | `{ table }` → `{ appliedRevision }` |
 | `getClusterRouteTable` | relay → Cloudly | `{}` → `{ table \| null }` |
-| `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities? }` → `{ accepted: true, revision \| null }` |
+| `registerClusterIngress` | ingress → relay → Cloudly | `{ bearer, version, nodeId, capabilities?, protocol }` → `{ accepted: true, revision \| null, protocol }` |
 | `getClusterIngressRouteTable` | ingress → relay | `{ knownRevision \| null }` → `{ table \| null }` |
 | `getClusterTrafficStatistics` | Cloudly → relay → ingress | `{ fromDayUtc, toDayUtc, cursor?, limit }` → `{ statistics, nextCursor? }` |
 
@@ -1352,7 +1644,11 @@ Isolation on that shared listener is therefore by **authorization, not by routin
 connection whose registration Cloudly accepted is the ingress, `getClusterIngressRouteTable` and
 `getClusterTrafficStatistics` are answered for that connection alone, and any other connection —
 including a Pallet node's — is refused by name. `validateClusterIngressRegistration(value, path?)`
-checks shape only: whether the bearer is the one Cloudly minted is Cloudly's to verify.
+checks shape only: whether the bearer is the one Cloudly minted is Cloudly's to verify. It reads
+the registration's `protocol` offer through the one grammar `protocol` owns, and both hops judge
+the body in the one server order `protocol.readProtocolOffer` states — the offer is negotiated
+before this shape check and before the bearer — so a relay refuses a peer it cannot serve without
+asking Cloudly, and an accepted registration carries the accepting side's own offer back.
 
 `IClusterTrafficStatistics` is one UTC day of one hostname's traffic on one node —
 `requests`, `bytesIn`, `bytesOut`, `connections` and the backend failures the proxy can observe
@@ -1373,6 +1669,7 @@ const ingressReasons = data.validateClusterIngressRegistration({
   bearer: ingressBearerFromAssignmentEnvironment,
   version: '3.0.0',
   nodeId: 'node-a',
+  protocol: protocol.createProtocolOffer('32.0.0'),
 }); // []
 ```
 
@@ -1380,7 +1677,7 @@ const ingressReasons = data.validateClusterIngressRegistration({
 
 A route to a node's published host ports needs the address that node answers on, and only the
 node can prove it: it holds the uplink observation the address belongs to. It therefore states it
-on the network report it already sends — `IReportRuntimeNetworkProtectionRequestV1` gains the
+on the network report it already sends — `IReportRuntimeNetworkProtectionRequest` gains the
 optional `uplinkAddress`, a unicast IPv4 literal that is neither loopback nor link-local
 (`runtimeNodeUplinkAddress`). Absence stays absent: a node that states no address is told apart
 from one that states a value, and nothing downstream defaults or infers one. Cloudly stores what
@@ -1609,7 +1906,7 @@ metadata, `data.normalizeCoreMailControlBootstrap` for startup authority, and
 normalizers reject unknown fields, noncanonical mailboxes,
 ambiguous active recipient ownership, malformed SHA-256 values, and
 credential-lifecycle inconsistencies. CoreMail credential verifiers use the
-versioned `argon2id-v1` format and the exact policy exported as
+`argon2id` format and the exact policy exported as
 `data.coreMailCredentialVerifierPolicy`.
 
 `data.ICoreMailDesiredState.smtp` is the optional CoreMail SMTP submission
@@ -1637,7 +1934,7 @@ canonical environment keys for the verifier-only bootstrap payload and the
 separate control and gateway secret values; no consumer may derive or embed
 plaintext material in desired state.
 
-CoreMail schema v2 keeps durable authority at the stable tenant, service, and
+The CoreMail contracts keep durable authority at the stable tenant, service, and
 binding identity while revisions, config epochs, and composite
 `credentialId`/`version` values fence sessions and new actions. Credential
 versions are authority-wide monotonic and unique even when rotation changes the
@@ -1672,8 +1969,8 @@ consumed only by the first durable insertion of an idempotency identity, while
 replays consume none. Pending inbound includes every state except
 `acknowledged`. These semantics are exported as `data.coreMailQuotaPolicy`.
 Every binding carries finite `messagesPerMinute`, `messagesPerDay`, and
-`maxPendingInbound` values; omitted or unlimited quotas are not valid schema-v2
-desired state.
+`maxPendingInbound` values; omitted or unlimited quotas are not valid desired
+state.
 `data.coreMailRetentionPolicy` retains terminal outbound,
 acknowledged inbound, and idempotency receipts for 30 days and expired
 capabilities for 24 hours. Pending inbound is never age-purged.
@@ -1695,7 +1992,7 @@ kind-specific byte budget reports `PAYLOAD_LIMIT_EXCEEDED`.
 
 Control and gateway credential rotation is ordered: provision the candidate
 plaintext through resolved runtime secrets, publish and activate the matching
-`argon2id-v1` verifier, roll or reconnect every affected replica, observe
+`argon2id` verifier, roll or reconnect every affected replica, observe
 per-task authentication and readiness, then mark the previous verifier
 `retiring` with `acceptUntil`. Remove the previous verifier and secret only
 after its acceptance window has elapsed and no session uses that composite
@@ -1726,7 +2023,7 @@ and a `coremail:<identifier>` management scope, validated by the existing
 `data.validateSecretManagementScope` and secret-metadata validators.
 
 `IServiceMailConfig.coreMail` publishes the service's CoreMail binding as public
-metadata only: binding and composite credential identity, the `argon2id-v1`
+metadata only: binding and composite credential identity, the `argon2id`
 verification hash, the binding state, and any `retiring` predecessor with its
 `acceptUntil`. Plaintext never appears there, and the field is excluded from
 `data.TServiceWritableData`, so only the control plane writes it while the rest
@@ -1809,9 +2106,9 @@ async function acceptMaterial(
 }
 ```
 
-Runtime material is shaped as `{ schemaVersion: 1, manifest, entries }`, where
+Runtime material is shaped as `{ manifest, entries }`, where
 each entry contains only `secretVersionId` and a strict X25519 envelope. The
-helper verifies the canonical schema-v2 manifest digest, envelope context
+helper verifies the canonical manifest digest, envelope context
 digests, active recipient key, sorted exact one-to-one version coverage, every
 request fence, and the trusted local organization/cluster expectation. It never
 decrypts. Organization and cluster are derived from the verified cluster JWT
@@ -1828,16 +2125,13 @@ canonical token boundary, while
 plaintext directly from validated UTF-8 bytes without first constructing a
 JavaScript token string. Publication grants carry the service, binding,
 reconciliation generation, binding-request digest, target Secrets revision, and
-bounded validity window. `computeCorestoreCredentialBindingRequestSha256()`
-produces that digest from the exact value-free provider, scope, environment, and
-optional retention request for persisted schema-v1 records. New issuers use
-`TCorestoreCredentialBindingRequestV2` and
-`validateCorestoreCredentialBindingRequestV2()`,
-`createCorestoreCredentialBindingRequestDigestInputV2()`, and
-`computeCorestoreCredentialBindingRequestSha256V2()`. The corresponding
-unsuffixed APIs remain the schema-v1 boundary. Schema v2 binds every object-storage
-request to the exact durable `bucketName`; schema-v1 records stay readable but
-do not provide that authority. Object-storage plaintext keeps the logical
+bounded validity window. `TCorestoreCredentialBindingRequest` with
+`validateCorestoreCredentialBindingRequest()`,
+`createCorestoreCredentialBindingRequestDigestInput()`, and
+`computeCorestoreCredentialBindingRequestSha256()` produces that digest from
+the exact value-free provider, scope, environment, bucket, and optional
+retention request. Every object-storage request binds the exact durable
+`bucketName`. Object-storage plaintext keeps the logical
 `accessKeyId` and `secretAccessKey` fields while
 `createCorestoreCredentialSecretValues()` expands them to the six canonical
 Corestore `S3_*` and `AWS_*` Secret aliases. Receipts bind that exact key
@@ -1899,7 +2193,11 @@ answer is refused with one: the two states can never be read as each other.
 | `getClusterPlatformDesiredState` | relay → Cloudly | `{}` → `{ capabilities, providerConfigs, bindings }` |
 | `backupServiceDatabaseClosure` | relay → Cloudly | `{ backupId, serviceId, nodeId, descriptor, closure }` → `{ accepted }` |
 | `restoreServiceDatabaseClosure` | relay → Cloudly | `{ backupId, serviceId, nodeId }` → `{ descriptor, closure }` |
-| `stageIsolatedRestoreArchive` | Cloudly → relay | `{ restoreGrant, clusterId, targetNodeName, restoreId, expectedRevision, object, archive }` → `{ state }` |
+| `prepareIsolatedRestoreOnNode` | Cloudly → relay | `{ nodeId, control }` → `{ progress }` |
+| `stageIsolatedRestoreArchive` | Cloudly → relay | `{ nodeId, control }` → `{ progress }` |
+| `getIsolatedRestoreProgressOnNode` | Cloudly → relay | `{ nodeId, control }` → `{ progress }` |
+| `executeIsolatedRestoreOnNode` | Cloudly → relay | `{ nodeId, control }` → `{ progress }` |
+| `cleanupIsolatedRestoreOnNode` | Cloudly → relay | `{ nodeId, control }` → `{ progress }` |
 
 **Placement is a field too.** `getClusterPlatformDesiredState` answers with
 `IClusterPlatformBindingPlacement { nodeId, binding }` rather than a bare binding list: a database
@@ -1931,14 +2229,53 @@ closure its own receipt contradicts.
 
 **Isolated restore carries its grant.** Corestore accepts exactly one authority on
 `/isolated-restore/*`: a compact RS256 grant that names one operation, expires within minutes and
-binds the cluster, the node, the canonical resource mappings and the archive manifest. So
-`coreflowPrepareIsolatedRestore`, `coreflowExecuteIsolatedRestore`,
-`coreflowGetIsolatedRestoreStatus`, `coreflowCleanupIsolatedRestore` and
-`stageIsolatedRestoreArchive` each carry `restoreGrant`, which the relay forwards untouched and can
-neither widen nor mint. Each is sensitive ephemeral input: exclude the complete request from hooks,
-logs and journals on every hop. Staging is one archive object per call — the manifest entry is the
-descriptor — because Corestore writes staged objects one bounded chunk at a time under a
-`write-object` grant, and turning a stream into those chunks is the relay's work.
+binds the cluster, the node name, the canonical resource mappings and the archive manifest. The
+five methods above are therefore one shape — `{ nodeId, control }` → `{ progress }` — where
+`control` is the body Corestore itself reads (`data.IIsolatedRestoreControlPrepareRequest`,
+`…WriteRequest`, `…StatusRequest`, `…ExecuteRequest`, `…CleanupRequest`) with the grant inside it.
+The relay forwards the control untouched and can neither widen it nor mint one; it adds no
+identity and no protocol offer either, because the cluster is the one the verified machine identity
+on the session `registerCloudlyClientSession` opened names, and the protocol offer was exchanged by
+that handshake and again by `registerClusterRelay`'s own `protocol` member. Every one of them is
+sensitive ephemeral input: the grant is a bearer credential, declared once on
+`data.IIsolatedRestoreControlAuthority`, so exclude the complete request from hooks, logs,
+diagnostics and durable journals on every hop.
+
+**The order an operator's restore runs in.** Cloudly calls `createIsolatedRestore` with the node
+it dispatches to, then, on that node: `prepareIsolatedRestoreOnNode` with `expectedRevision: 0`,
+`stageIsolatedRestoreArchive` once per bounded chunk of every manifest object,
+`executeIsolatedRestoreOnNode`, and `cleanupIsolatedRestoreOnNode` when the rehearsal is over;
+`getIsolatedRestoreProgressOnNode` reads the same state without changing it. Staging is bounded by
+`data.isolatedRestoreContractLimits`: at most 512 KiB decoded per chunk, 4,096 chunks per object
+and 64 MiB per object, each chunk authenticated by its own `chunkSha256` against the immutable
+object descriptor. Every mutation carries the `revision` the node last stated as its
+`expectedRevision`, so a replay settles instead of racing.
+
+**The node id routes, the node name is authorized.** `createIsolatedRestore` takes `targetNodeId`
+— the cluster document's node id, which is what a relay routes on — while the signed grant keeps
+`targetNodeName`, which is what the operator authorized and what Corestore verifies. Cloudly is
+the only party holding both, so `IIsolatedRestoreRecord` states both and every control call is
+dispatched by the id. `data.bindIsolatedRestoreProgressToNode(progress, { nodeId, restoreId })`
+is where an answer is tied back: the control body names neither the node nor the restore, so
+without it a relay could answer with another node's — or another restore's — perfectly canonical
+progress.
+
+**What a node can state, in Corestore's own words.** `data.IIsolatedRestoreProgress` is Corestore's
+staging summary plus the node the control was carried to: `{ nodeId, restoreId, stagingArchiveId,
+status, revision, lastFence, expectedObjects, receivedObjects, completedMappings, totalMappings,
+preparedAt, updatedAt, executedAt?, stagedObject? }`, with `status` one of
+`data.isolatedRestoreProgressStatuses` — `prepared`, `executing`, `failed`, `executed`, `cleaned`.
+`stagedObject` is present only on a staged chunk and says where the next chunk continues; it is
+named apart from the `object` receipt Corestore's own write answer carries, which is a different
+shape and is not projected. `data.normalizeIsolatedRestoreProgress(value)` reads it exactly,
+refusing an unknown status, a count larger than the plan it belongs to, a `revision` or `lastFence`
+below 1 — a committed state carries both — an `executing` or `executed` answer that does not hold
+the whole archive, and an `executed` answer that left a mapping behind or does not say when it
+finished. A node states nothing of the control plane's record — no source backup, no requester, no
+verification — so Cloudly composes its record from this and its own knowledge, exactly as it does
+with the Corestore inventory. A relay that cannot reach the node answers one of
+`data.isolatedRestoreNodeControlRefusals` instead: `restore-node-not-carried`,
+`restore-node-unreachable`, or `restore-node-refused` followed by Corestore's own reason.
 
 `IIsolatedRestoreDatabaseMapping.target.databaseAllocation` carries Corestore's safe allocation
 reference, present exactly when the target database is allocation-managed. It lives inside the
@@ -1975,88 +2312,22 @@ recipient the relay enrolled with `beginSecretRecipientEnrollment` and
 `completeSecretRecipientEnrollment` — see [Corestore Runtime Credentials](#corestore-runtime-credentials).
 No credential travels in the cluster document, and none is read from the relay's environment.
 
-### Legacy Deployment Settlement
-
-The Node-only `/runtime` export also provides strict, exact-schema codecs for
-Cloudly legacy deployment settlement plans, production requests, check/apply
-summaries, stable outcomes, and scratch/production receipts. Authenticated
-artifacts use domain-separated HMAC inputs and references derived from the full
-authority-metadata SHA-256; authority-aware normalizers enforce metadata fences
-and artifact-time validity windows. General authority-aware APIs require a
-consumer-owned, constant-time HMAC verifier; private stdio authority-aware APIs
-derive verification from their exact plaintext authority handoffs. They never
-read the current wall clock.
-Structural normalizers explicitly do not authenticate MACs. Literal portable
-golden vectors contain only safe
-metadata, summaries, digests, and MACs. The separately named
-`ICloudlyLegacyDeploymentSettlementAuthorityHandoffPlaintextV1` parser/encoder
-exists only for private maintenance-container interoperability and is never part
-of a safe result, receipt, or golden summary.
-
-Fenced settlement contracts add deterministic execution-attempt identities and
-prepared, committed, or aborted observations. Resolution bundles distinguish
-`committed-schema1`, `committed-schema2`, `aborted-prepared`,
-`observed-aborted`, `absent-tombstone`, and `legacy-no-op`; only the scratch-only
-legacy no-op has no durable attempt observation. Source and execution authority
-status are bound to the resolution's `observedAt`. Scratch attempts use the same
-authority for both roles and require matching statuses. Historical verification
-remains possible after expiry because status is derived only from the
-authenticated observation time. Production recovery always uses receipt v2 and
-a distinct execution authority B whose metadata names source authority A and
-binds the authenticated plan, request bundle, and scratch receipt digests.
-B is issued strictly after scratch completion; B's `requestedAt` and
-`approvedAt` are independent of A's request timestamp and must remain within
-B's own validity interval.
-
-Consumers make trust decisions through
-`normalizeAuthenticatedCloudlyLegacyDeploymentSettlementResolutionForAuthorities()`,
-`normalizeCloudlyLegacyDeploymentSettlementScratchExecutionBundleForAuthority()`,
-`normalizeCloudlyLegacyDeploymentSettlementProductionExecutionBundleV2ForAuthorities()`,
-`normalizeCloudlyLegacyDeploymentSettlementStdioRequestForAuthorities()`, and
-`normalizeCloudlyLegacyDeploymentSettlementStdioResponseForRequestAuthorities()`.
-Every resolution outcome, including an unapplied outcome, is carried in an
-`IAuthenticatedCloudlyLegacyDeploymentSettlementResolutionV1` recovery
-attestation under the dedicated resolution HMAC domain and signed by the
-execution authority. The raw
-`normalizeCloudlyLegacyDeploymentSettlementResolutionBundleForAuthorities()`
-helper verifies referenced artifacts and status only; its result is not an
-authenticated recovery claim. The non-stdio authority-aware APIs use the
-caller-supplied HMAC verifier and never receive plaintext keys. The private
-stdio variants accept no external verifier: they bind each HMAC to the
-authority reference and key in the corresponding request handoff. Interfaces
-never executes a settlement.
-
-The stdio contract exposes nine commands from `settlement-plan` through
-`settlement-production-resolve`. Requests and responses are exact canonical
-JSON followed by one LF, bounded by
-`cloudlyLegacyDeploymentSettlementStdioLimits`, and responses use a
-command-discriminated success payload or a finite secret-safe error. Private
-authority handoffs and MongoDB descriptors belong only on protected request
-transport. Production stdio requests reject equal decoded A and B HMAC keys and
-wipe temporary comparison buffers. The handoff-derived verifier uses HMAC-SHA256
-with constant-time MAC comparison, rejects wrong or swapped handoff keys, and
-wipes temporary decoded key and MAC buffers. Handoffs and derived verifiers are
-private in-process capabilities that must never be persisted or logged and must
-be discarded when the stdio exchange ends. Verifier-only integrations do not
-expose key material to Interfaces, so their callers must enforce the same key
-separation.
-Authority-aware response validation also binds settlement-request
-`requestedAt`, production-authorization `requestedAt` and `approvedAt`, and
-resolution `observedAt` to the corresponding request. Production check and
-apply results must be issued by B no earlier than both A's request and B's
-`approvedAt`. Callers remain responsible for process isolation, key
-destruction, logging discipline, database access, and the actual settlement
-transaction.
+### Launcher Environment Delivery
 
 Launcher environment delivery uses stable `szsv-<base32-sha256>` Docker
 resource names and `/run/serve.zone/secrets/<resource>` source paths. The
-nonsecret map is written to `/run/serve.zone/workloadinit-map-v1.json` with mode
-0444. Runtime assets under `/opt/serve.zone/runtime-assets` are read-only, and
-the wrapper executes
-`workloadinit run --map /run/serve.zone/workloadinit-map-v1.json -- <argv...>`
-without a shell, symlink, or aggregate value file. Resources and maps remain
-retained while any desired, applied, or previous-accepted manifest references
-them and are deleted only after Docker confirms rollout or service removal.
+nonsecret map is written to `/run/serve.zone/workloadinit-map.json` with mode
+0444. Runtime assets under `/opt/serve.zone/runtime-assets` are read-only, the
+wrapper itself lives at
+`/opt/serve.zone/runtime-assets/workloadinit/workloadinit`, and it executes
+`workloadinit run --map /run/serve.zone/workloadinit-map.json -- <argv...>`
+without a shell, symlink, or aggregate value file. A resource name is the
+lowercase base32 of a SHA-256 over `serve.zone/docker-secret-resource`, a NUL
+and the SecretVersion id, so every launcher secret of a service is republished
+under a new Docker resource name when a cluster moves to 32.0.0. Resources and
+maps remain retained while any desired, applied, or previous-accepted manifest
+references them and are deleted only after Docker confirms rollout or service
+removal.
 
 ## Platform Contracts