lablup / lablup/backend.ai

Unify resource slot naming from `occupying_slots` to `occupied_slots`

Open
#8,122 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
670
Forks
183
Avg merge
17h 7m
Merged PRs (30d)
358

Description

## Background

The codebase has inconsistent naming for resource slot fields across different database tables:

|Table|Column Name|Usage Count|
|---|---|---|
| session| `occupying_slots| 61 occurrence|
| kernel| `occupied_slots| 362 occurrence|
| agent| `occupied_slots| (part of 362|

Both fields represent the same concept: "resource slots currently occupied by the entity."

## Problem

1. **Naming Inconsistency**: Session uses `occupying_slots` (present participle) while Kernel and Agent
use `occupied_slots` (past participle)
1. **Legacy Compatibility Code**: GraphQL API exposes both field names for Session (`occupying_slots` and
`occupied_slots` marked as "# legacy")
1. **Developer Confusion**: Same semantic concept with different naming conventions

## Current State

**Database Models:**

- `src/ai/backend/manager/models/session/row.py:764` → `occupying_slots`
- `src/ai/backend/manager/models/kernel/row.py:461` → `occupied_slots`
- `src/ai/backend/manager/models/agent/row.py:89` → `occupied_slots`

**GraphQL API (gql_legacy/session.py:986-987):**

```python
occupying_slots = graphene.JSONString()
occupied_slots = graphene.JSONString() # legacy
```

## Data Types:

- data/session/types.py → occupying_slots: ResourceSlot
- data/kernel/types.py → occupied_slots: ResourceSlot
- data/agent/types.py → occupied_slots: ResourceSlot

## Requirements

1. Rename sessions.occupying_slots column to occupied_slots via Alembic migration
1. Update SessionRow model to use occupied_slots
1. Update all data types and DTOs to use occupied_slots
1. Update GraphQL API:

- Keep occupied_slots as primary field
- Mark occupying_slots as deprecated/legacy alias

1. Update all internal references in services, repositories, and schedulers
1. Update client SDK field mappings

## Impact

- Database: Single column rename in sessions table
- API: GraphQL field rename (with backward compatibility alias)
- Internal: ~22 files need updates for occupying_slots references

## Testing Scenarios

- Session creation correctly populates occupied_slots
- Session status transitions maintain occupied_slots values
- GraphQL queries return correct values for both field names
- Scheduler correctly reads/writes occupied_slots
- Existing tests pass after migration
- Client SDK compatibility verified

JIRA Issue: BA-3940

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.