@serve.zone/interfaces 9.0.0 → 10.1.0

package/changelog.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2026-07-13 - 10.1.0
+
+### Features
+
+- define isolated restore orchestration contracts (backup)
+  - Add non-runnable scratch namespaces with backup-derived cluster and source authority.
+  - Add idempotency keys, revision compare-and-swap, exact cluster/node routing, verification, cursor pagination, durable backup holds, and retryable per-resource cleanup progress.
+
+### Maintenance
+
+- Remove the legacy implicit-any build suppression and refresh the age-eligible TypeScript toolchain.
+
+## 2026-07-10 - 10.0.0
+
+### Breaking Changes
+
+- accept JWT-only credentials for cluster config requests (config)
+  - Add IIdentityCredential as a JWT-only authentication contract.
+  - Make IIdentity extend IIdentityCredential so full identities remain compatible where credentials are accepted.
+  - Update getClusterConfig request identity to require only the JWT needed for server-side resolution.
+
 ## 2026-07-10 - 9.0.0
 
 ### Breaking Changes

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '9.0.0',
+    version: '10.1.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFFBQVE7SUFDakIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/backup.d.ts

@@ -53,6 +53,19 @@ export interface IBackupRestoreEvent {
     status: 'restored' | 'failed';
     errorText?: string;
 }
+/**
+ * Durable retention hold owned by one isolated restore. An entry is active
+ * while `releasedAt` is absent. Active holds never expire implicitly:
+ * retention may neither claim nor delete the backup until every active hold
+ * has been released after successful scratch-resource and staging cleanup.
+ */
+export interface IBackupRestoreHold {
+    restoreId: string;
+    idempotencyKey: string;
+    acquiredAt: number;
+    releasedAt?: number;
+    releaseReason?: string;
+}
 export interface IBackupRecord {
     id: string;
     serviceId: string;
@@ -76,6 +89,12 @@ export interface IBackupRecord {
     requestedBy?: string;
     errorText?: string;
     restoreHistory?: IBackupRestoreEvent[];
+    /**
+     * Authoritative isolated-restore holds. Cloudly atomically appends the
+     * active entry with restore creation. Failed archive cleanup must retain
+     * this backup record so hold recovery remains possible.
+     */
+    restoreHolds?: IBackupRestoreHold[];
     tags?: Record<string, string>;
 }
 /** Retention policy understood by containerarchive prune. */
@@ -92,3 +111,213 @@ export interface IArchivePruneResult {
     freedBytes: number;
     dryRun: boolean;
 }
+/**
+ * JWT-free actor projection persisted with isolated-restore audit data.
+ * Authentication credentials must never be copied into restore records.
+ */
+export interface IIsolatedRestoreActor {
+    userId: string;
+    type: 'human' | 'machine' | 'system';
+    role?: 'admin' | 'user' | 'api' | 'cluster';
+}
+export type TIsolatedRestoreStatus = 'pending' | 'preparing' | 'staging' | 'restoring' | 'verifying' | 'ready' | 'failed' | 'cleanup-pending' | 'cleaning' | 'cleaned' | 'cleanup-failed';
+export type TIsolatedRestoreErrorPhase = 'validation' | 'source-backup-hold' | 'preparation' | 'staging' | 'restoring' | 'verifying' | 'cleanup';
+/** Append-only structured failure entry for one isolated restore. */
+export interface IIsolatedRestoreError {
+    sequence: number;
+    phase: TIsolatedRestoreErrorPhase;
+    code: string;
+    message: string;
+    retryable: boolean;
+    occurredAt: number;
+}
+export type TIsolatedRestoreAuditAction = 'created' | 'status-transitioned' | 'source-backup-hold-acquired' | 'cleanup-requested' | 'expired' | 'source-backup-hold-release-requested' | 'source-backup-hold-released';
+/** Append-only lifecycle event. `sequence` is strictly increasing per restore. */
+export interface IIsolatedRestoreAuditEvent {
+    sequence: number;
+    action: TIsolatedRestoreAuditAction;
+    actor: IIsolatedRestoreActor;
+    occurredAt: number;
+    fromStatus?: TIsolatedRestoreStatus;
+    toStatus?: TIsolatedRestoreStatus;
+    reason?: string;
+}
+export interface IIsolatedRestoreVolumeMapping {
+    /** Stable server-generated id used by verification and cleanup progress. */
+    id: string;
+    type: 'volume';
+    source: {
+        snapshotId: string;
+        volumeName: string;
+        mountPath: string;
+    };
+    target: {
+        volumeName: string;
+        mountPath: string;
+    };
+}
+export interface IIsolatedRestoreDatabaseMapping {
+    /** Stable server-generated id used by verification and cleanup progress. */
+    id: string;
+    type: 'database';
+    source: {
+        snapshotId: string;
+        resourceName: string;
+        databaseName: string;
+    };
+    target: {
+        resourceName: string;
+        databaseName: string;
+    };
+}
+export interface IIsolatedRestoreObjectStorageMapping {
+    /** Stable server-generated id used by verification and cleanup progress. */
+    id: string;
+    type: 'objectstorage';
+    source: {
+        snapshotId: string;
+        resourceName: string;
+        bucketName: string;
+    };
+    target: {
+        resourceName: string;
+        bucketName: string;
+    };
+}
+export type TIsolatedRestoreResourceMapping = IIsolatedRestoreVolumeMapping | IIsolatedRestoreDatabaseMapping | IIsolatedRestoreObjectStorageMapping;
+export type TIsolatedRestoreVerificationStatus = 'pending' | 'running' | 'passed' | 'failed';
+export interface IIsolatedRestoreVerificationCheck {
+    /** Stable machine-readable check code. */
+    code: string;
+    status: 'passed' | 'failed';
+    message?: string;
+}
+export interface IIsolatedRestoreResourceVerification {
+    resourceMappingId: string;
+    resourceType: TBackupResourceType;
+    status: TIsolatedRestoreVerificationStatus;
+    checks: IIsolatedRestoreVerificationCheck[];
+    checkedAt?: number;
+}
+/** Complete verification state returned by the target data plane. */
+export interface IIsolatedRestoreVerification {
+    status: TIsolatedRestoreVerificationStatus;
+    results: IIsolatedRestoreResourceVerification[];
+    startedAt?: number;
+    completedAt?: number;
+}
+export type TIsolatedRestoreCleanupTrigger = 'manual' | 'expired' | 'restore-failed' | 'policy';
+export type TIsolatedRestoreCleanupProgressStatus = 'pending' | 'running' | 'succeeded' | 'failed';
+export interface IIsolatedRestoreResourceCleanupProgress {
+    resourceMappingId: string;
+    resourceType: TBackupResourceType;
+    status: TIsolatedRestoreCleanupProgressStatus;
+    attempts: number;
+    updatedAt?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export interface IIsolatedRestoreStagingCleanupProgress {
+    stagingArchiveId: string;
+    status: TIsolatedRestoreCleanupProgressStatus;
+    attempts: number;
+    updatedAt?: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+/** Data-plane cleanup progress shared by public and internal status views. */
+export interface IIsolatedRestoreCleanupProgress {
+    resources: IIsolatedRestoreResourceCleanupProgress[];
+    stagingArchive: IIsolatedRestoreStagingCleanupProgress;
+}
+/**
+ * Cleanup metadata. The source-backup hold remains active until every
+ * resource entry and the staging entry report `succeeded`. `cleanup-failed`
+ * is retryable and must not release the hold.
+ */
+export interface IIsolatedRestoreCleanup extends IIsolatedRestoreCleanupProgress {
+    trigger: TIsolatedRestoreCleanupTrigger;
+    reason: string;
+    requestedBy: IIsolatedRestoreActor;
+    requestedAt: number;
+    startedAt?: number;
+    completedAt?: number;
+}
+export type TIsolatedRestoreSourceBackupHoldStatus = 'acquired' | 'release-pending' | 'released';
+/**
+ * Restore-side projection of the authoritative IBackupRecord hold. The hold
+ * is non-expiring and may enter `released` only after exact cleanup success.
+ */
+export interface IIsolatedRestoreSourceBackupHold {
+    status: TIsolatedRestoreSourceBackupHoldStatus;
+    acquiredAt: number;
+    releaseRequestedAt?: number;
+    releasedAt?: number;
+    releaseReason?: string;
+}
+export type TIsolatedRestoreNodeStatus = 'preparing' | 'prepared' | 'staging' | 'restoring' | 'verifying' | 'ready' | 'failed' | 'cleaning' | 'cleaned' | 'cleanup-failed';
+/**
+ * Data-plane state for one exact cluster/node/restore routing key. `revision`
+ * advances after every mutation and is the compare-and-swap value used by
+ * prepare, execute, and cleanup requests.
+ */
+export interface IIsolatedRestoreNodeState {
+    restoreId: string;
+    clusterId: string;
+    targetNodeName: string;
+    sourceBackupId: string;
+    sourceServiceId: string;
+    scratchNamespaceId: string;
+    stagingArchiveId: string;
+    revision: number;
+    status: TIsolatedRestoreNodeStatus;
+    completedResourceMappingIds: string[];
+    verification: IIsolatedRestoreVerification;
+    cleanup?: IIsolatedRestoreCleanupProgress;
+    preparedAt?: number;
+    readyAt?: number;
+    updatedAt: number;
+    lastErrorCode?: string;
+    lastErrorMessage?: string;
+}
+/**
+ * Durable control-plane record for a restore into a generated data-plane
+ * scratch namespace. The namespace is not an IService and carries no image,
+ * runtime, route, port, environment, or secret authority.
+ *
+ * `clusterId` and `sourceServiceId` are copied from the authoritative source
+ * backup, never accepted from the caller. `revision` advances monotonically
+ * for optimistic lifecycle updates. A restore execution failure (`failed`)
+ * must proceed through cleanup before its source-backup hold can be released.
+ */
+export interface IIsolatedRestoreRecord {
+    /** Server-generated restore id. */
+    id: string;
+    /** Caller key used to return the same restore after retried creation. */
+    idempotencyKey: string;
+    revision: number;
+    sourceBackupId: string;
+    sourceServiceId: string;
+    sourceServiceName?: string;
+    clusterId: string;
+    /** Server-generated, non-runnable data-plane namespace. */
+    scratchNamespaceId: string;
+    /** Server-generated archive namespace, distinct from sourceBackupId. */
+    stagingArchiveId: string;
+    targetNodeName: string;
+    purpose: string;
+    requestedBy: IIsolatedRestoreActor;
+    status: TIsolatedRestoreStatus;
+    resourceMappings: TIsolatedRestoreResourceMapping[];
+    verification: IIsolatedRestoreVerification;
+    sourceBackupHold: IIsolatedRestoreSourceBackupHold;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+    readyAt?: number;
+    cleanup?: IIsolatedRestoreCleanup;
+    /** Append-only; entries are never replaced when a later phase fails. */
+    errors: IIsolatedRestoreError[];
+    /** Append-only lifecycle audit trail. */
+    auditEvents: IIsolatedRestoreAuditEvent[];
+}

package/dist_ts/data/user.d.ts

@@ -3,18 +3,19 @@ export interface IToken {
     expiresAt: number;
     assignedRoles: string[];
 }
+export interface IIdentityCredential {
+    jwt: string;
+}
 /**
  * an identity is assumed by authentication as a user
  * an identity is ephemeral and has to be renewed regularly
  */
-export interface IIdentity {
+export interface IIdentity extends IIdentityCredential {
     name: string;
     userId: string;
     type: 'machine' | 'human';
     role: 'admin' | 'user' | 'api' | 'cluster';
     expiresAt: number;
-    /** the jwt token should contain above data for verification */
-    jwt: string;
 }
 export interface IUser {
     id: string;

package/dist_ts/requests/backup.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IArchivePruneResult, IArchiveRetentionPolicy, IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, TBackupSnapshot } from '../data/backup.js';
+import type { IArchivePruneResult, IArchiveRetentionPolicy, IBackupArchiveManifest, IBackupArchiveObject, IBackupRecord, IBackupReplicationResult, IIsolatedRestoreNodeState, IIsolatedRestoreRecord, TBackupSnapshot, TIsolatedRestoreResourceMapping } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
 export interface IReq_Any_Cloudly_CreateServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateServiceBackup> {
@@ -146,3 +146,150 @@ export interface IReq_Cloudly_Coreflow_PruneNodeArchive extends plugins.typedreq
         result?: IArchivePruneResult;
     };
 }
+/**
+ * Creates a restore in a new non-runnable data-plane scratch namespace.
+ * Cloudly derives clusterId and sourceServiceId from the authoritative backup,
+ * atomically acquires its retention hold, and owns every generated target id.
+ */
+export interface IReq_Any_Cloudly_CreateIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateIsolatedRestore> {
+    method: 'createIsolatedRestore';
+    request: {
+        identity: IIdentity;
+        sourceBackupId: string;
+        targetNodeName: string;
+        purpose: string;
+        /** Caller-generated key; retries return the original restore. */
+        idempotencyKey: string;
+        /** Requested lifetime; Cloudly applies its configured maximum. */
+        ttlMs?: number;
+        /** Derived from the authoritative backup. */
+        clusterId?: never;
+        /** Derived from the authoritative backup. */
+        sourceServiceId?: never;
+        /** Generated by Cloudly. Explicitly forbidden as caller input. */
+        id?: never;
+        /** Alias-like caller input is forbidden as well. */
+        restoreId?: never;
+        /** Legacy runnable-service targeting is forbidden. */
+        targetServiceId?: never;
+        /** Generated by Cloudly. Explicitly forbidden as caller input. */
+        scratchNamespaceId?: never;
+        /** Generated by Cloudly. Explicitly forbidden as caller input. */
+        stagingArchiveId?: never;
+        /** Generated after validating every snapshot in the source backup. */
+        resourceMappings?: never;
+    };
+    response: {
+        restore: IIsolatedRestoreRecord;
+    };
+}
+export interface IReq_Any_Cloudly_GetIsolatedRestores extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetIsolatedRestores> {
+    method: 'getIsolatedRestores';
+    request: {
+        identity: IIdentity;
+        sourceBackupId?: string;
+        sourceServiceId?: string;
+        clusterId?: string;
+        targetNodeName?: string;
+        scratchNamespaceId?: string;
+        status?: IIsolatedRestoreRecord['status'];
+        includeCleaned?: boolean;
+        /** Opaque cursor returned by the previous page. */
+        cursor?: string;
+        /** Server-capped page size. */
+        limit?: number;
+    };
+    response: {
+        restores: IIsolatedRestoreRecord[];
+        /** Omitted when this is the final page. */
+        nextCursor?: string;
+    };
+}
+export interface IReq_Any_Cloudly_GetIsolatedRestoreById extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetIsolatedRestoreById> {
+    method: 'getIsolatedRestoreById';
+    request: {
+        identity: IIdentity;
+        restoreId: string;
+    };
+    response: {
+        restore: IIsolatedRestoreRecord;
+    };
+}
+/**
+ * Prepares and stages one isolated restore on an exact cluster node. A missing
+ * node state has revision 0; successful mutation returns the next revision.
+ */
+export interface IReq_Cloudly_Coreflow_PrepareIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_PrepareIsolatedRestore> {
+    method: 'coreflowPrepareIsolatedRestore';
+    request: {
+        clusterId: string;
+        targetNodeName: string;
+        restoreId: string;
+        expectedRevision: number;
+        sourceBackupId: string;
+        sourceServiceId: string;
+        scratchNamespaceId: string;
+        stagingArchiveId: string;
+        resourceMappings: TIsolatedRestoreResourceMapping[];
+        archiveManifest: IBackupArchiveManifest;
+    };
+    response: {
+        state: IIsolatedRestoreNodeState;
+    };
+}
+/** Read-only status for one exact cluster/node/restore routing key. */
+export interface IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus> {
+    method: 'coreflowGetIsolatedRestoreStatus';
+    request: {
+        clusterId: string;
+        targetNodeName: string;
+        restoreId: string;
+    };
+    response: {
+        found: boolean;
+        state?: IIsolatedRestoreNodeState;
+    };
+}
+export interface IReq_Cloudly_Coreflow_ExecuteIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_ExecuteIsolatedRestore> {
+    method: 'coreflowExecuteIsolatedRestore';
+    request: {
+        clusterId: string;
+        targetNodeName: string;
+        restoreId: string;
+        expectedRevision: number;
+    };
+    response: {
+        state: IIsolatedRestoreNodeState;
+    };
+}
+/**
+ * Idempotent cleanup mutation. A cleanup-failed state remains retryable and
+ * does not authorize release of the source-backup hold.
+ */
+export interface IReq_Cloudly_Coreflow_CleanupIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_Coreflow_CleanupIsolatedRestore> {
+    method: 'coreflowCleanupIsolatedRestore';
+    request: {
+        clusterId: string;
+        targetNodeName: string;
+        restoreId: string;
+        expectedRevision: number;
+    };
+    response: {
+        state: IIsolatedRestoreNodeState;
+    };
+}
+/**
+ * Requests idempotent asynchronous cleanup. The restore record is retained as
+ * audit evidence and transitions through the canonical cleanup statuses.
+ */
+export interface IReq_Any_Cloudly_CleanupIsolatedRestore extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CleanupIsolatedRestore> {
+    method: 'cleanupIsolatedRestore';
+    request: {
+        identity: IIdentity;
+        restoreId: string;
+        reason: string;
+    };
+    response: {
+        restore: IIsolatedRestoreRecord;
+    };
+}

package/dist_ts/requests/config.d.ts

@@ -17,7 +17,7 @@ export interface IRequest_Any_Cloudly_GetServerConfig extends plugins.typedreque
 export interface IRequest_Any_Cloudly_GetClusterConfig extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetClusterConfig> {
     method: 'getClusterConfig';
     request: {
-        identity: userInterfaces.IIdentity;
+        identity: userInterfaces.IIdentityCredential;
     };
     response: {
         configData: clusterInterfaces.ICluster;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "9.0.0",
+  "version": "10.1.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -19,7 +19,7 @@
     "@git.zone/tsdoc": "^2.1.1",
     "@git.zone/tsrun": "^2.0.5",
     "@git.zone/tstest": "^3.6.6",
-    "@types/node": "^26.0.1"
+    "@types/node": "^26.1.0"
   },
   "files": [
     "ts/**/*",
@@ -52,7 +52,7 @@
   ],
   "scripts": {
     "test": "tstest test/ --verbose --logfile --timeout 60",
-    "build": "tsbuild tsfolders --allowimplicitany",
+    "build": "tsbuild tsfolders",
     "buildDocs": "tsdoc"
   }
 }

package/readme.md

@@ -99,7 +99,7 @@ Common data contracts include:
 - `ISecretBundle` and `ISecretGroup` for secret ownership and shared secret groups.
 - Mail gateway contracts for domain authorities, address bindings, WorkApp bindings, managed SMTP/API credentials, spool items, delivery journals, and inbound/outbound message payloads.
 - Service-level mail configuration through `IService.data.mail`, including per-address inbound `smtpForward` settings and outbound credential metadata. Cloudly settings include dcrouter gateway, SMTP submission, and inbound forward-target keys for reconciling those bindings.
-- `IUser`, `IIdentity`, and token-related contracts for authentication context.
+- `IUser`, JWT-only `IIdentityCredential`, full `IIdentity`, and token-related contracts for authentication context. `IIdentity` extends `IIdentityCredential` with server-issued user metadata.
 - `ICloudlyConfig`, `ICloudlySettings`, status, server, bare-metal, BaseOS, backup, and task execution interfaces for control-plane state.
 
 Shared service port helpers are exported from `data` so Cloudly, App Store resolution, Coreflow, Coretraffic, Onebox, and dcrouter agree on the same normalization rules:
@@ -138,6 +138,8 @@ interface IExampleRequest {
 }
 ```
 
+`requests.config.IRequest_Any_Cloudly_GetClusterConfig` accepts `data.IIdentityCredential`, which contains only the JWT needed for server-side identity resolution. Username/password login and machine-token exchange responses continue to return the full `data.IIdentity`.
+
 Gateway request contracts include `getGatewayClientRoutes` (`requests.gateway.IReq_GetGatewayClientRoutes`) for listing owned `IGatewayClientRoute[]` route views, and `syncGatewayClientRoute` for idempotently syncing or deleting hostname-owned and routeRef-owned routes. Mail request contracts include `syncMailAddressBinding`, `deleteMailAddressBinding`, `rotateMailCredential`, and `getMailDeliveryStatus`. `IReq_GetMailDeliveryStatus` looks up a delivery spool item by `spoolItemId`, returns `data.IMailDeliveryStatus`, and accepts `IMailSubmissionRequestAuth` so service-mail credentials can query their own accepted, queued, deferred, delivered, or failed status. `TMailAddressBindingSync.outboundEnabled` explicitly controls whether a gateway should maintain a managed outbound SMTP credential for an address binding. Binding credential metadata is public; `rotateMailCredential` returns the new secret only in its one-time `IMailCredentialOneTimeSecret` response.
 
 Request groups are exported by product area:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '9.0.0',
+  version: '10.1.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/backup.ts

@@ -77,6 +77,20 @@ export interface IBackupRestoreEvent {
   errorText?: string;
 }
 
+/**
+ * Durable retention hold owned by one isolated restore. An entry is active
+ * while `releasedAt` is absent. Active holds never expire implicitly:
+ * retention may neither claim nor delete the backup until every active hold
+ * has been released after successful scratch-resource and staging cleanup.
+ */
+export interface IBackupRestoreHold {
+  restoreId: string;
+  idempotencyKey: string;
+  acquiredAt: number;
+  releasedAt?: number;
+  releaseReason?: string;
+}
+
 export interface IBackupRecord {
   id: string;
   serviceId: string;
@@ -100,6 +114,12 @@ export interface IBackupRecord {
   requestedBy?: string;
   errorText?: string;
   restoreHistory?: IBackupRestoreEvent[];
+  /**
+   * Authoritative isolated-restore holds. Cloudly atomically appends the
+   * active entry with restore creation. Failed archive cleanup must retain
+   * this backup record so hold recovery remains possible.
+   */
+  restoreHolds?: IBackupRestoreHold[];
   tags?: Record<string, string>;
 }
 
@@ -118,3 +138,291 @@ export interface IArchivePruneResult {
   freedBytes: number;
   dryRun: boolean;
 }
+
+/**
+ * JWT-free actor projection persisted with isolated-restore audit data.
+ * Authentication credentials must never be copied into restore records.
+ */
+export interface IIsolatedRestoreActor {
+  userId: string;
+  type: 'human' | 'machine' | 'system';
+  role?: 'admin' | 'user' | 'api' | 'cluster';
+}
+
+export type TIsolatedRestoreStatus =
+  | 'pending'
+  | 'preparing'
+  | 'staging'
+  | 'restoring'
+  | 'verifying'
+  | 'ready'
+  | 'failed'
+  | 'cleanup-pending'
+  | 'cleaning'
+  | 'cleaned'
+  | 'cleanup-failed';
+
+export type TIsolatedRestoreErrorPhase =
+  | 'validation'
+  | 'source-backup-hold'
+  | 'preparation'
+  | 'staging'
+  | 'restoring'
+  | 'verifying'
+  | 'cleanup';
+
+/** Append-only structured failure entry for one isolated restore. */
+export interface IIsolatedRestoreError {
+  sequence: number;
+  phase: TIsolatedRestoreErrorPhase;
+  code: string;
+  message: string;
+  retryable: boolean;
+  occurredAt: number;
+}
+
+export type TIsolatedRestoreAuditAction =
+  | 'created'
+  | 'status-transitioned'
+  | 'source-backup-hold-acquired'
+  | 'cleanup-requested'
+  | 'expired'
+  | 'source-backup-hold-release-requested'
+  | 'source-backup-hold-released';
+
+/** Append-only lifecycle event. `sequence` is strictly increasing per restore. */
+export interface IIsolatedRestoreAuditEvent {
+  sequence: number;
+  action: TIsolatedRestoreAuditAction;
+  actor: IIsolatedRestoreActor;
+  occurredAt: number;
+  fromStatus?: TIsolatedRestoreStatus;
+  toStatus?: TIsolatedRestoreStatus;
+  reason?: string;
+}
+
+export interface IIsolatedRestoreVolumeMapping {
+  /** Stable server-generated id used by verification and cleanup progress. */
+  id: string;
+  type: 'volume';
+  source: {
+    snapshotId: string;
+    volumeName: string;
+    mountPath: string;
+  };
+  target: {
+    volumeName: string;
+    mountPath: string;
+  };
+}
+
+export interface IIsolatedRestoreDatabaseMapping {
+  /** Stable server-generated id used by verification and cleanup progress. */
+  id: string;
+  type: 'database';
+  source: {
+    snapshotId: string;
+    resourceName: string;
+    databaseName: string;
+  };
+  target: {
+    resourceName: string;
+    databaseName: string;
+  };
+}
+
+export interface IIsolatedRestoreObjectStorageMapping {
+  /** Stable server-generated id used by verification and cleanup progress. */
+  id: string;
+  type: 'objectstorage';
+  source: {
+    snapshotId: string;
+    resourceName: string;
+    bucketName: string;
+  };
+  target: {
+    resourceName: string;
+    bucketName: string;
+  };
+}
+
+export type TIsolatedRestoreResourceMapping =
+  | IIsolatedRestoreVolumeMapping
+  | IIsolatedRestoreDatabaseMapping
+  | IIsolatedRestoreObjectStorageMapping;
+
+export type TIsolatedRestoreVerificationStatus =
+  | 'pending'
+  | 'running'
+  | 'passed'
+  | 'failed';
+
+export interface IIsolatedRestoreVerificationCheck {
+  /** Stable machine-readable check code. */
+  code: string;
+  status: 'passed' | 'failed';
+  message?: string;
+}
+
+export interface IIsolatedRestoreResourceVerification {
+  resourceMappingId: string;
+  resourceType: TBackupResourceType;
+  status: TIsolatedRestoreVerificationStatus;
+  checks: IIsolatedRestoreVerificationCheck[];
+  checkedAt?: number;
+}
+
+/** Complete verification state returned by the target data plane. */
+export interface IIsolatedRestoreVerification {
+  status: TIsolatedRestoreVerificationStatus;
+  results: IIsolatedRestoreResourceVerification[];
+  startedAt?: number;
+  completedAt?: number;
+}
+
+export type TIsolatedRestoreCleanupTrigger =
+  | 'manual'
+  | 'expired'
+  | 'restore-failed'
+  | 'policy';
+
+export type TIsolatedRestoreCleanupProgressStatus =
+  | 'pending'
+  | 'running'
+  | 'succeeded'
+  | 'failed';
+
+export interface IIsolatedRestoreResourceCleanupProgress {
+  resourceMappingId: string;
+  resourceType: TBackupResourceType;
+  status: TIsolatedRestoreCleanupProgressStatus;
+  attempts: number;
+  updatedAt?: number;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+export interface IIsolatedRestoreStagingCleanupProgress {
+  stagingArchiveId: string;
+  status: TIsolatedRestoreCleanupProgressStatus;
+  attempts: number;
+  updatedAt?: number;
+  errorCode?: string;
+  errorMessage?: string;
+}
+
+/** Data-plane cleanup progress shared by public and internal status views. */
+export interface IIsolatedRestoreCleanupProgress {
+  resources: IIsolatedRestoreResourceCleanupProgress[];
+  stagingArchive: IIsolatedRestoreStagingCleanupProgress;
+}
+
+/**
+ * Cleanup metadata. The source-backup hold remains active until every
+ * resource entry and the staging entry report `succeeded`. `cleanup-failed`
+ * is retryable and must not release the hold.
+ */
+export interface IIsolatedRestoreCleanup extends IIsolatedRestoreCleanupProgress {
+  trigger: TIsolatedRestoreCleanupTrigger;
+  reason: string;
+  requestedBy: IIsolatedRestoreActor;
+  requestedAt: number;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+export type TIsolatedRestoreSourceBackupHoldStatus =
+  | 'acquired'
+  | 'release-pending'
+  | 'released';
+
+/**
+ * Restore-side projection of the authoritative IBackupRecord hold. The hold
+ * is non-expiring and may enter `released` only after exact cleanup success.
+ */
+export interface IIsolatedRestoreSourceBackupHold {
+  status: TIsolatedRestoreSourceBackupHoldStatus;
+  acquiredAt: number;
+  releaseRequestedAt?: number;
+  releasedAt?: number;
+  releaseReason?: string;
+}
+
+export type TIsolatedRestoreNodeStatus =
+  | 'preparing'
+  | 'prepared'
+  | 'staging'
+  | 'restoring'
+  | 'verifying'
+  | 'ready'
+  | 'failed'
+  | 'cleaning'
+  | 'cleaned'
+  | 'cleanup-failed';
+
+/**
+ * Data-plane state for one exact cluster/node/restore routing key. `revision`
+ * advances after every mutation and is the compare-and-swap value used by
+ * prepare, execute, and cleanup requests.
+ */
+export interface IIsolatedRestoreNodeState {
+  restoreId: string;
+  clusterId: string;
+  targetNodeName: string;
+  sourceBackupId: string;
+  sourceServiceId: string;
+  scratchNamespaceId: string;
+  stagingArchiveId: string;
+  revision: number;
+  status: TIsolatedRestoreNodeStatus;
+  completedResourceMappingIds: string[];
+  verification: IIsolatedRestoreVerification;
+  cleanup?: IIsolatedRestoreCleanupProgress;
+  preparedAt?: number;
+  readyAt?: number;
+  updatedAt: number;
+  lastErrorCode?: string;
+  lastErrorMessage?: string;
+}
+
+/**
+ * Durable control-plane record for a restore into a generated data-plane
+ * scratch namespace. The namespace is not an IService and carries no image,
+ * runtime, route, port, environment, or secret authority.
+ *
+ * `clusterId` and `sourceServiceId` are copied from the authoritative source
+ * backup, never accepted from the caller. `revision` advances monotonically
+ * for optimistic lifecycle updates. A restore execution failure (`failed`)
+ * must proceed through cleanup before its source-backup hold can be released.
+ */
+export interface IIsolatedRestoreRecord {
+  /** Server-generated restore id. */
+  id: string;
+  /** Caller key used to return the same restore after retried creation. */
+  idempotencyKey: string;
+  revision: number;
+  sourceBackupId: string;
+  sourceServiceId: string;
+  sourceServiceName?: string;
+  clusterId: string;
+  /** Server-generated, non-runnable data-plane namespace. */
+  scratchNamespaceId: string;
+  /** Server-generated archive namespace, distinct from sourceBackupId. */
+  stagingArchiveId: string;
+  targetNodeName: string;
+  purpose: string;
+  requestedBy: IIsolatedRestoreActor;
+  status: TIsolatedRestoreStatus;
+  resourceMappings: TIsolatedRestoreResourceMapping[];
+  verification: IIsolatedRestoreVerification;
+  sourceBackupHold: IIsolatedRestoreSourceBackupHold;
+  createdAt: number;
+  updatedAt: number;
+  expiresAt: number;
+  readyAt?: number;
+  cleanup?: IIsolatedRestoreCleanup;
+  /** Append-only; entries are never replaced when a later phase fails. */
+  errors: IIsolatedRestoreError[];
+  /** Append-only lifecycle audit trail. */
+  auditEvents: IIsolatedRestoreAuditEvent[];
+}

package/ts/data/user.ts

@@ -4,18 +4,20 @@ export interface IToken {
   assignedRoles: string[];
 }
 
+export interface IIdentityCredential {
+  jwt: string;
+}
+
 /**
  * an identity is assumed by authentication as a user
  * an identity is ephemeral and has to be renewed regularly
  */
-export interface IIdentity {
+export interface IIdentity extends IIdentityCredential {
   name: string;
   userId: string;
   type: 'machine' | 'human';
   role: 'admin' | 'user' | 'api' | 'cluster';
   expiresAt: number;
-  /** the jwt token should contain above data for verification */
-  jwt: string;
 }
 
 export interface IUser {
@@ -27,4 +29,4 @@ export interface IUser {
     password?: string;
     tokens?: IToken[];
   }
-}
+}

package/ts/requests/backup.ts

@@ -6,7 +6,10 @@ import type {
   IBackupArchiveObject,
   IBackupRecord,
   IBackupReplicationResult,
+  IIsolatedRestoreNodeState,
+  IIsolatedRestoreRecord,
   TBackupSnapshot,
+  TIsolatedRestoreResourceMapping,
 } from '../data/backup.js';
 import type { IService } from '../data/service.js';
 import type { IIdentity } from '../data/user.js';
@@ -214,3 +217,190 @@ extends plugins.typedrequestInterfaces.implementsTR<
     result?: IArchivePruneResult;
   };
 }
+
+/**
+ * Creates a restore in a new non-runnable data-plane scratch namespace.
+ * Cloudly derives clusterId and sourceServiceId from the authoritative backup,
+ * atomically acquires its retention hold, and owns every generated target id.
+ */
+export interface IReq_Any_Cloudly_CreateIsolatedRestore
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_CreateIsolatedRestore
+> {
+  method: 'createIsolatedRestore';
+  request: {
+    identity: IIdentity;
+    sourceBackupId: string;
+    targetNodeName: string;
+    purpose: string;
+    /** Caller-generated key; retries return the original restore. */
+    idempotencyKey: string;
+    /** Requested lifetime; Cloudly applies its configured maximum. */
+    ttlMs?: number;
+    /** Derived from the authoritative backup. */
+    clusterId?: never;
+    /** Derived from the authoritative backup. */
+    sourceServiceId?: never;
+    /** Generated by Cloudly. Explicitly forbidden as caller input. */
+    id?: never;
+    /** Alias-like caller input is forbidden as well. */
+    restoreId?: never;
+    /** Legacy runnable-service targeting is forbidden. */
+    targetServiceId?: never;
+    /** Generated by Cloudly. Explicitly forbidden as caller input. */
+    scratchNamespaceId?: never;
+    /** Generated by Cloudly. Explicitly forbidden as caller input. */
+    stagingArchiveId?: never;
+    /** Generated after validating every snapshot in the source backup. */
+    resourceMappings?: never;
+  };
+  response: {
+    restore: IIsolatedRestoreRecord;
+  };
+}
+
+export interface IReq_Any_Cloudly_GetIsolatedRestores
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetIsolatedRestores
+> {
+  method: 'getIsolatedRestores';
+  request: {
+    identity: IIdentity;
+    sourceBackupId?: string;
+    sourceServiceId?: string;
+    clusterId?: string;
+    targetNodeName?: string;
+    scratchNamespaceId?: string;
+    status?: IIsolatedRestoreRecord['status'];
+    includeCleaned?: boolean;
+    /** Opaque cursor returned by the previous page. */
+    cursor?: string;
+    /** Server-capped page size. */
+    limit?: number;
+  };
+  response: {
+    restores: IIsolatedRestoreRecord[];
+    /** Omitted when this is the final page. */
+    nextCursor?: string;
+  };
+}
+
+export interface IReq_Any_Cloudly_GetIsolatedRestoreById
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetIsolatedRestoreById
+> {
+  method: 'getIsolatedRestoreById';
+  request: {
+    identity: IIdentity;
+    restoreId: string;
+  };
+  response: {
+    restore: IIsolatedRestoreRecord;
+  };
+}
+
+/**
+ * Prepares and stages one isolated restore on an exact cluster node. A missing
+ * node state has revision 0; successful mutation returns the next revision.
+ */
+export interface IReq_Cloudly_Coreflow_PrepareIsolatedRestore
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_PrepareIsolatedRestore
+> {
+  method: 'coreflowPrepareIsolatedRestore';
+  request: {
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    expectedRevision: number;
+    sourceBackupId: string;
+    sourceServiceId: string;
+    scratchNamespaceId: string;
+    stagingArchiveId: string;
+    resourceMappings: TIsolatedRestoreResourceMapping[];
+    archiveManifest: IBackupArchiveManifest;
+  };
+  response: {
+    state: IIsolatedRestoreNodeState;
+  };
+}
+
+/** Read-only status for one exact cluster/node/restore routing key. */
+export interface IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_GetIsolatedRestoreStatus
+> {
+  method: 'coreflowGetIsolatedRestoreStatus';
+  request: {
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+  };
+  response: {
+    found: boolean;
+    state?: IIsolatedRestoreNodeState;
+  };
+}
+
+export interface IReq_Cloudly_Coreflow_ExecuteIsolatedRestore
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_ExecuteIsolatedRestore
+> {
+  method: 'coreflowExecuteIsolatedRestore';
+  request: {
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    expectedRevision: number;
+  };
+  response: {
+    state: IIsolatedRestoreNodeState;
+  };
+}
+
+/**
+ * Idempotent cleanup mutation. A cleanup-failed state remains retryable and
+ * does not authorize release of the source-backup hold.
+ */
+export interface IReq_Cloudly_Coreflow_CleanupIsolatedRestore
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Cloudly_Coreflow_CleanupIsolatedRestore
+> {
+  method: 'coreflowCleanupIsolatedRestore';
+  request: {
+    clusterId: string;
+    targetNodeName: string;
+    restoreId: string;
+    expectedRevision: number;
+  };
+  response: {
+    state: IIsolatedRestoreNodeState;
+  };
+}
+
+/**
+ * Requests idempotent asynchronous cleanup. The restore record is retained as
+ * audit evidence and transitions through the canonical cleanup statuses.
+ */
+export interface IReq_Any_Cloudly_CleanupIsolatedRestore
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_CleanupIsolatedRestore
+> {
+  method: 'cleanupIsolatedRestore';
+  request: {
+    identity: IIdentity;
+    restoreId: string;
+    reason: string;
+  };
+  response: {
+    restore: IIsolatedRestoreRecord;
+  };
+}

package/ts/requests/config.ts

@@ -27,7 +27,7 @@ extends plugins.typedrequestInterfaces.implementsTR<
 > {
   method: 'getClusterConfig';
   request: {
-    identity: userInterfaces.IIdentity;
+    identity: userInterfaces.IIdentityCredential;
   };
   response: {
     configData: clusterInterfaces.ICluster;