refactor(BA-7353): define the kernel payload beside the events that carry it

Review follow-up. A payload that only ever travels on a kernel event does not need a
package of its own — it belongs with the other kernel event types.

- Drop `common/interchange/` and define the payload in
  `events/event_types/kernel/types.py`, next to `KernelLifecycleEventReason`. Revert
  `common/AGENTS.md` and `common/KNOWLEDGE.md`, which only described that package, and
  leave `agent/resources.py` untouched.
- Give each level of the occupancy its own model with a mapping field rather than
  nesting three dicts inline: `KernelOccupancy.devices` (by `DeviceName`) →
  `DeviceOccupancy.slots` (by `ResourceSlotName`) → `SlotOccupancy.amounts` (by
  `DeviceId`). A device supplies more than one slot when it is metered along more than
  one axis, as `cuda` does with `cuda.device` and `cuda.shares`.
- Name it after what the manager does with it. It records the value as the kernel's
  occupancy, so the field is `occupancy` and the per-slot sum is `slot_totals`.
- Key slots by `ResourceSlotName` throughout, not the legacy `SlotName`.
- Declare the mappings as `Mapping`, so a consumer that tries to edit the payload it
  received is caught by the type checker.
- Drop the field defaults: a producer states the whole payload. The exception is
  `DeviceCapacity`, whose two fields the compute plugin's own `ComputedDeviceCapacity`
  declares `NotRequired` — a device that measures neither reports neither.
- Let the default `Decimal` constraint reject a non-finite amount. `Infinity` belongs to
  a resource policy with `DefaultForUnspecified.UNLIMITED`, not to an allocation: a
  device supplies a finite share of what it has, and `alloc_map` never produces one.

`slot_totals` stays a property rather than a `computed_field`: a computed field is
written into the payload beside the occupancy it is derived from, where nothing reads it
— a receiver recomputes it — and it can disagree with the value next to it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: fregataa

src/ai/backend/agent/resources.py

@@ -123,7 +123,7 @@ class KernelResourceSpec:
     slots: ResourceSlot
     """Stores the original user-requested resource slots."""
 
-    allocations: MutableMapping[DeviceName, DeviceAllocation]
+    allocations: MutableMapping[DeviceName, Mapping[SlotName, Mapping[DeviceId, Decimal]]]
     """
     Represents the resource allocations for each slot (device) type and devices.
     """

src/ai/backend/common/AGENTS.md

@@ -26,8 +26,6 @@
 | `common/events/` | Event type definitions and dispatcher — see existing `AbstractEvent` subclasses |
 | `common/bgtask/` | Background task framework — extend `BaseBackgroundTaskHandler` |
 | `common/dto/` | Inter-component DTOs — see `common/dto/AGENTS.md` |
-| `common/interchange/` | Payloads one component sends another (event/RPC bodies) — see `common/interchange/AGENTS.md` |
-| `common/schema/` | Pydantic types the manager persists as a JSON DB column — see `common/schema/AGENTS.md` |
 | `common/exception.py` | Root `BackendAIError` and `ErrorCode` — all component exceptions inherit from here |
 | `common/types.py` | Common base types used across layers |
 

src/ai/backend/common/KNOWLEDGE.md

@@ -27,20 +27,3 @@ types belong here is the core of this document.
 - The second criterion: types that, if placed in a higher layer, **would force an upward import** (`common/schema/` states this explicitly and is used only by the manager).
 - Single-consumer subpackages (`stage/` — agent-only, `resilience/` — manager-only) are not defects.
 - "It is convenient to put it somewhere neutral" is not a membership reason.
-
-## Shared types are split by what crosses, not by who owns them
-
-A type shared by two components still has to land in one of four places, and the
-question that separates them is what boundary it crosses:
-
-| Package | Crosses |
-|---------|---------|
-| `interchange/` | A component boundary as a serialized body (event/RPC payload) |
-| `dto/` | An API boundary, per target component |
-| `schema/` | The persistence boundary — the manager stores it as a JSON column |
-| `data/` | Nothing; it is passed within a component |
-
-`interchange/` exists because the first row had no home: `dto/` is organized by target
-component, and a payload has two sides, so neither side owns it. Its membership test is
-the consumer, not the producer — a field the receiving component never reads belongs in
-the producing component, not on the wire.

src/ai/backend/common/events/event_types/kernel/types.py

@@ -1,6 +1,18 @@
 import enum
+from collections.abc import Mapping
+from decimal import Decimal
 from typing import Self
 
+from ai.backend.common.identifier.resource_slot import ResourceSlotName
+from ai.backend.common.types import (
+    BackendAISchema,
+    ContainerId,
+    DeviceId,
+    DeviceName,
+    ResourceSlotEntry,
+    ServicePortProtocols,
+)
+
 
 class KernelLifecycleEventReason(enum.StrEnum):
     AGENT_TERMINATION = "agent-termination"
@@ -43,3 +55,94 @@ def from_value(cls, value: str | None) -> Self | None:
         except ValueError:
             pass
         return None
+
+
+class SlotOccupancy(BackendAISchema):
+    """How much of one slot each individual device supplies."""
+
+    amounts: Mapping[DeviceId, Decimal]
+
+
+class DeviceOccupancy(BackendAISchema):
+    """The slots one device supplies.
+
+    A device supplies more than one slot when it is metered along more than one axis —
+    `cuda` supplies both `cuda.device` and `cuda.shares`.
+    """
+
+    slots: Mapping[ResourceSlotName, SlotOccupancy]
+
+
+class KernelOccupancy(BackendAISchema):
+    """
+    The resources the kernel occupies, attributed to the devices supplying them.
+
+    `DeviceName` names a device (`cuda`) and `DeviceId` one of its units (`0`), so the
+    two levels keyed by a device are not the same thing.
+    """
+
+    devices: Mapping[DeviceName, DeviceOccupancy]
+
+    @property
+    def slot_totals(self) -> list[ResourceSlotEntry]:
+        """
+        The per-device amounts summed per slot — what a caller records as occupancy.
+
+        A slot supplied by no device is left out rather than reported as zero, which is
+        the distinction a caller storing the result depends on.
+
+        Not a `computed_field`: it would be written into the payload beside the
+        occupancy it is derived from, and a receiver recomputes it anyway.
+        """
+        totals: list[ResourceSlotEntry] = []
+        for device in self.devices.values():
+            for slot_name, slot in device.slots.items():
+                if not slot.amounts:
+                    continue
+                total = sum(slot.amounts.values(), Decimal(0))
+                totals.append(ResourceSlotEntry(resource_type=slot_name, quantity=str(total)))
+        return totals
+
+
+class DeviceCapacity(BackendAISchema):
+    """
+    What a device reports about itself.
+
+    Both are defaulted, unlike every other field here: the compute plugin's own
+    `ComputedDeviceCapacity` declares them `NotRequired`, so a device that measures
+    neither reports neither.
+    """
+
+    mem: int | None = None
+    proc: int | None = None
+
+
+class AttachedDevice(BackendAISchema):
+    device_id: DeviceId
+    model_name: str
+    data: DeviceCapacity
+
+
+class ServicePortInfo(BackendAISchema):
+    name: str
+    protocol: ServicePortProtocols
+    container_ports: list[int]
+    host_ports: list[int | None]
+    is_inference: bool
+
+
+class KernelCreationInfo(BackendAISchema):
+    """
+    What the agent reports about a kernel once its container is up.
+
+    This is the contract with the manager, not a rendering of the agent's own resource
+    spec: it carries the facts the manager records against the kernel and nothing else.
+    """
+
+    container_id: ContainerId
+    kernel_host: str
+    repl_in_port: int
+    repl_out_port: int
+    service_ports: list[ServicePortInfo]
+    attached_devices: Mapping[DeviceName, list[AttachedDevice]]
+    occupancy: KernelOccupancy