feat(specs): introduce batch-sandbox API with pagination and refined …

[hittyt]

…overrides

Summary

Refines the OpenSandbox Batch Sandbox API specification (specs/batch-sandbox.yml) to improve scalability for high-volume provisioning and ensure architectural consistency across the platform.

Testing

• Not run (only openAPI spec design)
• Unit tests
• Integration tests
• e2e / manual verification

Breaking Changes

• None
• Yes (describe impact and migration path)

Checklist

• Linked Issue or clearly described motivation
• Added/updated docs (if needed)
• Added/updated tests (if needed)
• Security impact considered
• Backward compatibility considered

[Spground]

Who is responsible for generating sandbox-id? The k8s operator or api service?

[hittyt]

for the k8s cluster mode, sandbox-id should be generated by the operator.
api server is responsible for wrapping it into the BatchSandboxMember object.

[Spground]

1. timeout. shall we add timeout field for BatchSandbox like single Sandbox timeout filed used for TTL.
2. how about we also support resource_limits field to specify container resource. Use case example: user didn't need pooling, just declare list of image, env, commandand argsinsandbox_override ` field, in this case, the system should create batch of Pods directly using user's declaration.

[hittyt]

1. timeout field is added with description.
2. I recommend omitting the resource_limits field to maintain API simplicity. Since batch provisioning relies on
   pre-warmed buffers within a Pool for instant startup, allowing ad-hoc resource overrides alongside a mandatory poolRef creates ambiguity and undermines the performance benefits of the pool.

[hittyt]

After further discussion, we've realized that the batch-sandbox API isn't strictly
necessary at this stage since there are no clear, high-priority use cases for it yet. I'd rather keep the project
scope focused and avoid adding complexity prematurely. We can revisit this design if and when a concrete requirement
for batch operations emerges. Thanks to everyone for the feedback!