design: expected final ateapi.proto for decoupled substrate resources (#368)

[Eitan Yarmush (EItanya)]

What

Draft of the expected final ateapi.proto once ActorTemplate, WorkerPool, SandboxConfig and WorkerPoolGrant move out of Kubernetes CRDs into the substrate API — the alignment artifact requested in #368. For review of the API shape only: codegen and server implementation intentionally lag the proto.

• pkg/proto/ateapipb/ateapi.proto — the target surface, edited in place so the diff shows exactly what changes
• docs/design/ateapi-resource-api.md — resource model and design decisions (D1–D15)
• docs/design/ateapi-crd-migration.md — transition from the CRDs/POC: what changes and why, migration path

Shape highlights

• Package renames to ateapi.v1alpha1 (gRPC paths embed the package → API versioning); every message is a fresh type, migration is a client cutover
• Follows the draft API style guide: ResourceMetadata meta = 1, shared ObjectRef, standard method shapes, required update_mask, int64 version optimistic concurrency
• Two services: Control (tenant: atespaces, templates, actors) / Admin (platform: pools, sandbox configs, grants, debug)
• ActorTemplate spec is immutable — no Update; template changes = new template + migrate actors
• One Kubernetes pocket: WorkerPoolSpec.kubernetes (KubernetesPlacement); everything outside it is plane-neutral. The POC's deployment_atespace is honestly renamed kubernetes.namespace
• WorkerPoolGrant is a conventional resource; Create enforces at most one grant per (atespace, worker_pool)
• Enum statuses instead of phase strings/conditions; oneof env source with plane-neutral SecretRef; equality-only Selector
• Watch streams: initial snapshot → SYNCED marker → at-least-once incremental events

Four deliberate style-guide divergences are listed in the design doc; filing those as feedback on #351 separately.

Review focus

The resource-model table and decisions D1–D15 in docs/design/ateapi-resource-api.md are the consensus surface — the proto is those decisions spelled out.

Refs #368

Julian Gutierrez Oschmann (@juli4n) the scope of this got a bit bigger than expected. I started gaming out the API decisions as per the new API guidelines and some of those bled into the overall proto design. We can always scope down if we think there's too much in here

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.