@serve.zone/interfaces 10.0.0 → 11.0.0

package/changelog.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2026-07-13 - 11.0.0
+
+### Breaking Changes
+
+- require JWT-only credentials for public isolated restore requests (backup)
+  - Replace caller-visible identity claims with `IIdentityCredential` on create, list, get, and cleanup requests.
+  - Require Cloudly handlers to verify the JWT and derive actor, role, and tenant authority server-side.
+
+## 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

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '10.0.0',
+    version: '11.0.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# 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/requests/backup.d.ts

@@ -1,7 +1,7 @@
 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';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
 export interface IReq_Any_Cloudly_CreateServiceBackup extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_CreateServiceBackup> {
     method: 'createServiceBackup';
     request: {
@@ -146,3 +146,154 @@ 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: {
+        /** Cloudly verifies this credential and derives all actor claims server-side. */
+        identity: IIdentityCredential;
+        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: {
+        /** Cloudly verifies this credential and derives all actor claims server-side. */
+        identity: IIdentityCredential;
+        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: {
+        /** Cloudly verifies this credential and derives all actor claims server-side. */
+        identity: IIdentityCredential;
+        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: {
+        /** Cloudly verifies this credential and derives all actor claims server-side. */
+        identity: IIdentityCredential;
+        restoreId: string;
+        reason: string;
+    };
+    response: {
+        restore: IIsolatedRestoreRecord;
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "10.0.0",
+  "version": "11.0.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/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '10.0.0',
+  version: '11.0.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/requests/backup.ts

@@ -6,10 +6,13 @@ 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';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
 
 export interface IReq_Any_Cloudly_CreateServiceBackup
 extends plugins.typedrequestInterfaces.implementsTR<
@@ -214,3 +217,194 @@ 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: {
+    /** Cloudly verifies this credential and derives all actor claims server-side. */
+    identity: IIdentityCredential;
+    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: {
+    /** Cloudly verifies this credential and derives all actor claims server-side. */
+    identity: IIdentityCredential;
+    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: {
+    /** Cloudly verifies this credential and derives all actor claims server-side. */
+    identity: IIdentityCredential;
+    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: {
+    /** Cloudly verifies this credential and derives all actor claims server-side. */
+    identity: IIdentityCredential;
+    restoreId: string;
+    reason: string;
+  };
+  response: {
+    restore: IIsolatedRestoreRecord;
+  };
+}