feat(snapshots): expose snapshot imageUri (spec, server, Kotlin SDK)

Surface the portable OCI restore image reference on the snapshot contract so
callers can restore a sandbox from it (e.g. across clusters) through the Kotlin
SDK instead of dropping down to the raw REST API.

- spec: add optional imageUri to the Snapshot schema in sandbox-lifecycle.yml
- server: add image_uri/imageUri to the Snapshot response, populated from the
  record's restore image only once the snapshot is Ready
- kotlin: add imageUri to SnapshotInfo (with a binary-compatibility constructor)
  and map it in SandboxModelConverter; the lifecycle client regenerates from the
  spec at build time

imageUri is optional and only populated once the snapshot is Ready (null/omitted
otherwise), so the change is additive and backward compatible.

Author: Ferran Pons Serra

sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/domain/models/sandboxes/SandboxModels.kt

@@ -794,7 +794,24 @@ class SnapshotInfo(
     val name: String? = null,
     val status: SnapshotStatus,
     val createdAt: OffsetDateTime,
-)
+    /**
+     * Portable OCI image reference for a Ready snapshot, usable to restore a sandbox (e.g. across
+     * clusters). Populated once the snapshot reaches [SnapshotState.READY]; null otherwise.
+     */
+    val imageUri: String? = null,
+) {
+    /**
+     * Binary-compatibility constructor preserving the pre-`imageUri` JVM signature for
+     * already-compiled (e.g. Java) callers; delegates [imageUri] to null.
+     */
+    constructor(
+        id: String,
+        sandboxId: String,
+        name: String?,
+        status: SnapshotStatus,
+        createdAt: OffsetDateTime,
+    ) : this(id, sandboxId, name, status, createdAt, null)
+}
 
 class SnapshotFilter private constructor(
     val sandboxId: String?,

sdks/sandbox/kotlin/sandbox/src/main/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/converter/SandboxModelConverter.kt

@@ -410,6 +410,7 @@ internal object SandboxModelConverter {
                     lastTransitionAt = this.status.lastTransitionAt,
                 ),
             createdAt = this.createdAt,
+            imageUri = this.imageUri,
         )
     }
 

sdks/sandbox/kotlin/sandbox/src/test/kotlin/com/alibaba/opensandbox/sandbox/infrastructure/adapters/service/SandboxesAdapterTest.kt

@@ -369,7 +369,8 @@ class SandboxesAdapterTest {
                     "message": null,
                     "lastTransitionAt": "2023-01-01T10:00:00Z"
                 },
-                "createdAt": "2023-01-01T10:00:00Z"
+                "createdAt": "2023-01-01T10:00:00Z",
+                "imageUri": "registry.example.com/snapshots/snap-123:latest"
             }
             """.trimIndent()
         mockWebServer.enqueue(MockResponse().setBody(responseBody).setResponseCode(200))
@@ -378,6 +379,7 @@ class SandboxesAdapterTest {
 
         assertEquals(snapshotId, result.id)
         assertEquals("sandbox-123", result.sandboxId)
+        assertEquals("registry.example.com/snapshots/snap-123:latest", result.imageUri)
 
         val request = mockWebServer.takeRequest()
         assertEquals("GET", request.method)

server/opensandbox_server/api/schema.py

@@ -672,6 +672,14 @@ class Snapshot(BaseModel):
         alias="createdAt",
         description="Snapshot creation timestamp",
     )
+    image_uri: Optional[str] = Field(
+        None,
+        alias="imageUri",
+        description=(
+            "Portable OCI image reference produced for a Ready snapshot, usable to restore a "
+            "sandbox (e.g. across clusters). Present once the snapshot is Ready; omitted otherwise."
+        ),
+    )
 
     class Config:
         populate_by_name = True

server/opensandbox_server/services/snapshot_service.py

@@ -549,6 +549,13 @@ def _to_snapshot_response(record: SnapshotRecord) -> Snapshot:
                 lastTransitionAt=record.status.last_transition_at,
             ),
             createdAt=record.created_at,
+            # The restore image is part of the contract only once the snapshot is Ready; never
+            # surface it for Creating/Deleting/Failed states (e.g. after deletion is requested).
+            imageUri=(
+                record.restore_config.image
+                if record.status.state == SnapshotState.READY
+                else None
+            ),
         )
 
 

server/tests/test_snapshot_service.py

@@ -124,6 +124,16 @@ def _snapshot_record(
     )
 
 
+def test_snapshot_response_exposes_image_uri_only_when_ready() -> None:
+    image = "opensandbox-snapshots:snap-1"
+    ready = _snapshot_record("snap-ready", SnapshotState.READY, image=image)
+    deleting = _snapshot_record("snap-deleting", SnapshotState.DELETING, image=image)
+
+    assert PersistedSnapshotService._to_snapshot_response(ready).image_uri == image
+    # Once deletion is requested (or any non-Ready state), the restore image must not leak.
+    assert PersistedSnapshotService._to_snapshot_response(deleting).image_uri is None
+
+
 def test_snapshot_service_persists_create_and_get(tmp_path) -> None:
     repo = SQLiteSnapshotRepository(tmp_path / "snapshots.db")
     runtime = StubSnapshotRuntime()
@@ -221,6 +231,10 @@ def create_snapshot(snapshot_id: str, sandbox_id: str, **kwargs):
     assert stored.status.state == SnapshotState.READY
     assert stored.restore_config.image == "opensandbox-snapshots:snap-ready"
 
+    # The Ready snapshot response exposes the portable restore image via imageUri.
+    response = service.get_snapshot(created.id)
+    assert response.image_uri == "opensandbox-snapshots:snap-ready"
+
 
 def test_snapshot_service_marks_snapshot_failed_from_worker(tmp_path) -> None:
     repo = SQLiteSnapshotRepository(tmp_path / "snapshots.db")

specs/sandbox-lifecycle.yml

@@ -915,6 +915,12 @@ components:
           format: date-time
           description: Snapshot creation timestamp
 
+        imageUri:
+          type: string
+          description: >-
+            Portable OCI image reference produced for a Ready snapshot, usable to restore a sandbox
+            (e.g. across clusters). Present once the snapshot reaches the Ready state; omitted otherwise.
+
       required:
         - id
         - sandboxId