feat(lifecycle): expose pool allocation summary

docs/api/index.md

@@ -40,6 +40,11 @@ Defines the complete lifecycle interfaces for creating, managing, and destroying
 - `PATCH /sandboxes/{sandboxId}/metadata` - Patch sandbox metadata (JSON Merge Patch, RFC 7396)
 - `GET /sandboxes/{sandboxId}/endpoints/{port}` - Get an access endpoint for a service port
 
+**Optional `Sandbox.allocation` response field:**
+- Returned only when the runtime confirms the sandbox's current concrete Pool allocation.
+- Omitted for unconfirmed allocations, non-Pool sandboxes, and allocations being released.
+- This field is not a request echo, allocation history, or readiness signal, and does not expose Pod names or other Kubernetes-internal fields.
+
 **Authentication:**
 - HTTP Header: `OPEN-SANDBOX-API-KEY: your-api-key`
 - Environment Variable: `OPEN_SANDBOX_API_KEY` (for SDK clients)

kubernetes/AGENTS.md

@@ -46,7 +46,7 @@ For E2E test failure diagnosis, see [docs/E2E-TROUBLESHOOTING.md](./docs/E2E-TRO
 
 The controller communicates allocation state through annotations on BatchSandbox objects. These are treated as internal but stability-sensitive:
 
-- `sandbox.opensandbox.io/alloc-status`: JSON `{"pods":["pod-1","pod-2"]}` — current pod allocation
+- `sandbox.opensandbox.io/alloc-status`: current pool allocation. Legacy pods-only JSON such as `{"pods":["pod-1","pod-2"]}` remains accepted and readable. Current controller writes add `poolRef` and `generation`: `{"pods":["pod-1","pod-2"],"poolRef":"pool-a","generation":42}`. `generation` traces the BatchSandbox generation for the write; it is not an evidence-freshness predicate.
 - `sandbox.opensandbox.io/alloc-release`: JSON `{"pods":["pod-3"]}` — pods released back to pool
 - `sandbox.opensandbox.io/endpoints`: JSON endpoint list consumed by server-side endpoint resolution
 

kubernetes/DEVELOPMENT.md

@@ -143,7 +143,7 @@ PoolReconciler.Reconcile
 ```
 
 Allocation state is stored in memory (`InMemoryAllocationStore`) and persisted to BatchSandbox annotations:
-- `sandbox.opensandbox.io/alloc-status`: `{"pods":["pod-1","pod-2"]}`
+- `sandbox.opensandbox.io/alloc-status`: current pool allocation. Legacy `{"pods":["pod-1","pod-2"]}` remains accepted and readable. Current controller writes include additive `poolRef` and `generation` fields, for example `{"pods":["pod-1","pod-2"],"poolRef":"pool-a","generation":42}`. `generation` records the BatchSandbox generation associated with the write; it is not an evidence-freshness predicate.
 - `sandbox.opensandbox.io/alloc-release`: `{"pods":["pod-3"]}`
 
 On startup, `InMemoryAllocationStore.Recover` rebuilds the in-memory state from all BatchSandbox annotations.
@@ -408,10 +408,10 @@ The controller communicates allocation state through annotations on BatchSandbox
 
 | Annotation Key | JSON Shape | Writer | Reader |
 |---|---|---|---|
-| `sandbox.opensandbox.io/alloc-status` | `{"pods":["pod-1"]}` | `allocator.go` via `apis.go` | `batchsandbox_controller.go` |
+| `sandbox.opensandbox.io/alloc-status` | Legacy: `{"pods":["pod-1"]}`; current writer: `{"pods":["pod-1"],"poolRef":"pool-a","generation":42}` | `allocator.go` via `apis.go` | `batchsandbox_controller.go` |
 | `sandbox.opensandbox.io/alloc-release` | `{"pods":["pod-3"]}` | `batchsandbox_controller.go` | `allocator.go` |
 
-When changing annotation shapes, update all readers and writers, and add migration logic if the change is not backward-compatible.
+The `poolRef` and `generation` fields in `alloc-status` are additive. Continue to accept and read the legacy pods-only shape. `generation` traces the BatchSandbox generation for the annotation write; do not use it as an evidence-freshness predicate. When changing annotation shapes, update all readers and writers, and add migration logic if the change is not backward-compatible.
 
 ## Build and Deploy
 

kubernetes/internal/controller/allocator.go

@@ -269,6 +269,8 @@ func NewAnnoAllocationSyncer(client client.Client) AllocationSyncer {
 }
 
 func (syncer *annoAllocationSyncer) SetAllocation(ctx context.Context, sandbox *sandboxv1alpha1.BatchSandbox, allocation *SandboxAllocation) error {
+	allocation.PoolRef = sandbox.Spec.PoolRef
+	allocation.Generation = sandbox.Generation
 	js, err := json.Marshal(allocation)
 	if err != nil {
 		return err

kubernetes/internal/controller/allocator_test.go

@@ -350,14 +350,20 @@ func newTestSyncer(sandbox *sandboxv1alpha1.BatchSandbox) (*annoAllocationSyncer
 
 func TestSetAllocation_AddsFinalizer(t *testing.T) {
 	sandbox := &sandboxv1alpha1.BatchSandbox{
-		ObjectMeta: metav1.ObjectMeta{Name: "sbx1", Namespace: "default"},
+		ObjectMeta: metav1.ObjectMeta{Name: "sbx1", Namespace: "default", Generation: 7},
 		Spec:       sandboxv1alpha1.BatchSandboxSpec{PoolRef: "pool1"},
 	}
 	syncer, sbx := newTestSyncer(sandbox)
 
 	err := syncer.SetAllocation(context.Background(), sbx, &SandboxAllocation{Pods: []string{"pod1"}})
 	assert.NoError(t, err)
 	assert.Contains(t, sbx.Finalizers, FinalizerPoolAllocation)
+
+	allocation, err := syncer.GetAllocation(context.Background(), sbx)
+	assert.NoError(t, err)
+	assert.Equal(t, []string{"pod1"}, allocation.Pods)
+	assert.Equal(t, "pool1", allocation.PoolRef)
+	assert.Equal(t, int64(7), allocation.Generation)
 }
 
 func TestSetReleased_FinalizerBehavior(t *testing.T) {

kubernetes/internal/controller/apis.go

@@ -39,7 +39,9 @@ const (
 var AnnotationSandboxEndpoints = pkgutils.AnnotationEndpoints
 
 type SandboxAllocation struct {
-	Pods []string `json:"pods"`
+	Pods       []string `json:"pods"`
+	PoolRef    string   `json:"poolRef"`
+	Generation int64    `json:"generation"`
 }
 
 type AllocationRelease struct {