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.
- 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`.

`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/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,5 +1,18 @@
 import enum
-from typing import Self
+from decimal import Decimal
+from typing import Annotated, Self
+
+from pydantic import Field
+
+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):
@@ -43,3 +56,94 @@ def from_value(cls, value: str | None) -> Self | None:
         except ValueError:
             pass
         return None
+
+
+type AllocationAmount = Annotated[
+    Decimal,
+    # An unbounded allocation is expressed as `Decimal("Infinity")`, which the default
+    # `Decimal` constraint rejects. It survives the wire as the string "Infinity".
+    Field(allow_inf_nan=True),
+]
+
+
+class SlotOccupancy(BackendAISchema):
+    """How much of one slot each individual device supplies."""
+
+    amounts: dict[DeviceId, AllocationAmount] = Field(default_factory=dict)
+
+
+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: dict[ResourceSlotName, SlotOccupancy] = Field(default_factory=dict)
+
+
+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: dict[DeviceName, DeviceOccupancy] = Field(default_factory=dict)
+
+    @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):
+    mem: int | None = None
+    proc: int | None = None
+
+
+class AttachedDevice(BackendAISchema):
+    device_id: DeviceId
+    model_name: str
+    data: DeviceCapacity = Field(default_factory=DeviceCapacity)
+
+
+class ServicePortInfo(BackendAISchema):
+    name: str
+    protocol: ServicePortProtocols
+    container_ports: list[int] = Field(default_factory=list)
+    host_ports: list[int | None] = Field(default_factory=list)
+    is_inference: bool = False
+
+
+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] = Field(default_factory=list)
+    attached_devices: dict[DeviceName, list[AttachedDevice]] = Field(default_factory=dict)
+    occupancy: KernelOccupancy = Field(default_factory=KernelOccupancy)