Phase 7: Session Entity Model Migration¶

Version: 1.4.0 Date: 2026-02-20 Status: ✅ Complete (7A–7K implemented, 7I deferred per AD-P7-06, 7L documentation done) Author: LCM Architecture Team Master Plan: mvp-implementation-plan.md §10 ADRs: ADR-020 · ADR-021 · ADR-022

1. Executive Summary¶

Phase 7 implements the largest structural change in the LCM codebase: migrating from the LabletInstance/LabletRecordRun/LabletLabBinding entity model to a consolidated LabletSession aggregate with three child entities (UserSession, GradingSession, ScoreReport).

Scope¶

Migration Strategy¶

Big-bang rename — no backward compatibility, no aliases, no deprecation. All services updated simultaneously. Frontend will break during implementation and be fixed in the frontend sub-phase.

Key Decisions (AD-P7-01 through AD-P7-05)¶

2. Codebase Audit¶

2.1 Architecture Overview¶

┌─────────────────────┐
│   control-plane-api  │  ← Single source of truth (9 MongoDB collections, 70 commands, 25 queries)
│   (port 8020)        │
└──────┬──────┬───┬────┘
       │      │   │
  HTTP │ HTTP │   │ HTTP
       │      │   │
┌──────▼────┐ ┌─▼───▼─────┐ ┌──────────────┐
│ resource  │ │ lablet    │ │ worker       │
│-scheduler │ │-controller│ │-controller   │
│(port 8081)│ │(port 8082)│ │(port 8083)   │
└───────────┘ └───────────┘ └──────────────┘
  Stateless    Stateless     Stateless
  reconciler   reconciler    reconciler
     │              │              │
     └──── etcd ────┘──────────────┘
           (coordination)

Key architectural constraint: Only control-plane-api owns domain aggregates and MongoDB. All controllers are stateless reconcilers using ControlPlaneApiClient from lcm-core.

2.2 Entities to Refactor¶

LabletInstance (control-plane-api) — 727 lines¶

LabletRecordRun (control-plane-api) — 344 lines¶

LabletLabBinding (control-plane-api) — 96 lines¶

2.3 Existing CQRS to Rewrite/Delete¶

Commands (17 files to transform)¶

commands/lablet_instance/ → commands/lablet_session/ (9 commands):

commands/run/ → DELETE (8 commands):

New commands to create:

Queries (6 files to transform)¶

New queries to create:

2.4 MongoDB Collections — Current vs Target¶

Current (9 registered in CPA main.py)¶

Target (10 collections)¶

2.5 etcd Key Structure — Current vs Target¶

2.6 API Routes — Current vs Target¶

CPA Internal Endpoints (consumed by controllers)¶

CPA Public Endpoints¶

2.7 ControlPlaneApiClient (lcm-core) — Methods to Rename¶

File: lcm_core/integration/clients/control_plane_client.py — 1,343 lines

2.8 lcm-core Shared Models to Rename¶

2.9 Cross-Service Impact Summary¶

2.10 Dead Code Inventory¶

Total dead code: ~2,000+ lines to remove.

3. Execution Plan¶

3.0 Sub-Phase Dependency Graph¶

graph TD
    7A["7A: lcm-core renames<br/>enums + read models"]
    7B["7B: Dead code cleanup"]
    7C["7C: CPA domain layer<br/>entities + events + repos"]
    7D["7D: CPA application layer<br/>commands + queries + DTOs"]
    7E["7E: CPA integration layer<br/>MongoDB repos + etcd"]
    7F["7F: CPA API layer<br/>controllers + internal endpoints"]
    7G["7G: lcm-core client update<br/>ControlPlaneApiClient"]
    7H["7H: Controller updates<br/>LC reconciler + RS scheduler"]
    7I["7I: CloudEvent webhook<br/>LC webhook endpoint"]
    7J["7J: Frontend updates<br/>API paths + SSE events"]
    7K["7K: Tests & verification"]
    7L["7L: Documentation"]

    7A --> 7C
    7B --> 7C
    7C --> 7D
    7D --> 7E
    7E --> 7F
    7F --> 7G
    7G --> 7H
    7G --> 7I
    7H --> 7K
    7I --> 7K
    7F --> 7J
    7J --> 7K
    7K --> 7L

    classDef core fill:#4a9eff,color:#fff
    classDef cpa fill:#ff6b6b,color:#fff
    classDef ctrl fill:#51cf66,color:#fff
    classDef ui fill:#ffd43b,color:#333
    classDef test fill:#cc5de8,color:#fff

    class 7A,7G core
    class 7B,7C,7D,7E,7F cpa
    class 7H,7I ctrl
    class 7J ui
    class 7K,7L test

3.1 Sub-Phase 7A: lcm-core Shared Layer Renames¶

Goal: Rename shared enums, read models, and re-export names so downstream services can compile. Scope: lcm-core only Estimate: 1 day

Acceptance criteria:

• [ ] LabletSessionStatus enum exists with 11 states matching ADR-020
• [ ] LabletSessionReadModel has all fields from LabletInstance + absorbed fields + child entity FKs
• [ ] BindingRole, BindingStatus, LabletRecordRunStatus deleted
• [ ] LdsSessionStatus and GradingStatus in own files
• [ ] 3 new read models for child entities
• [ ] lcm-core make lint passes

3.2 Sub-Phase 7B: Dead Code Cleanup¶

Goal: Remove all identified dead code before the big rename to reduce noise and confusion. Scope: control-plane-api, lablet-controller Estimate: 1 day

Estimated total removal: ~2,100+ lines

Acceptance criteria:

• [ ] All dead code files deleted
• [ ] No import errors (make lint passes for CPA and LC)
• [ ] Existing tests pass (make test passes for CPA and LC)
• [ ] main.py DI registrations updated for both services

3.3 Sub-Phase 7C: CPA Domain Layer — New Entities¶

Goal: Create LabletSession aggregate, child entities, domain events, and repository interfaces. Scope: control-plane-api domain/ Estimate: 3 days

LabletSessionState specification (ADR-020 §3 + §4):

@dataclass
class LabletSessionState:
    """Consolidated session state — replaces LabletInstance + LabletLabBinding + LabletRecordRun."""

    # Core identity
    definition_id: str = ""
    definition_version: str = ""
    owner: str = ""

    # Lifecycle
    status: LabletSessionStatus = LabletSessionStatus.PENDING
    status_history: list[dict] = field(default_factory=list)

    # Scheduling (set at SCHEDULED)
    worker_id: str | None = None
    timeslot_start: datetime | None = None
    timeslot_end: datetime | None = None
    reservation_id: str | None = None

    # Lab binding (absorbed from LabletLabBinding — ADR-020 §2)
    lab_record_id: str | None = None           # Direct 1:1 FK (was via LabletLabBinding)
    cml_lab_id: str | None = None              # CML lab identifier on worker

    # Port allocation (absorbed from LabletRecordRun — ADR-020 §2)
    allocated_ports: dict[str, int] = field(default_factory=dict)

    # Runtime tracking (absorbed from LabletRecordRun — ADR-020 §2)
    started_at: datetime | None = None         # When RUNNING state entered
    ended_at: datetime | None = None           # When session completed
    duration_seconds: float | None = None      # Computed on completion

    # Child entity FKs (ADR-021 §4)
    user_session_id: str | None = None         # → UserSession
    grading_session_id: str | None = None      # → GradingSession
    score_report_id: str | None = None         # → ScoreReport

    # Assessment result (kept for quick access — denormalized from ScoreReport)
    grade_result: str | None = None            # "pass" / "fail" / None

    # Timestamps
    created_at: datetime = field(default_factory=datetime.utcnow)
    updated_at: datetime = field(default_factory=datetime.utcnow)

LabletSession lifecycle (11 states — ADR-020 §4):

PENDING → SCHEDULED → INSTANTIATING → READY → RUNNING → COLLECTING → GRADING → STOPPING → STOPPED → ARCHIVED
                                                                                                      ↗
Any state ──────────────────────────────────────────────────────────────────────────────→ TERMINATED

Child entity schemas (ADR-021):

@dataclass
class UserSession:
    """LDS session tracking — Entity[str] with own MongoDB collection."""
    id: str                              # UUID
    lablet_session_id: str               # FK → LabletSession
    lds_session_id: str                  # External LDS session ref
    lds_part_id: str | None = None       # LDS content part
    login_url: str | None = None         # JWT-signed launch URL
    devices: list[dict] = field(default_factory=list)  # Device access info
    status: LdsSessionStatus = LdsSessionStatus.PROVISIONING
    created_at: datetime = field(default_factory=datetime.utcnow)
    updated_at: datetime = field(default_factory=datetime.utcnow)

@dataclass
class GradingSession:
    """Grading Engine session tracking — Entity[str] with own MongoDB collection."""
    id: str                              # UUID
    lablet_session_id: str               # FK → LabletSession
    grading_session_id: str              # External GradingEngine ref
    grading_part_id: str | None = None   # Form/content part
    pod_id: str | None = None            # GradingEngine pod
    status: GradingStatus = GradingStatus.PENDING
    created_at: datetime = field(default_factory=datetime.utcnow)
    updated_at: datetime = field(default_factory=datetime.utcnow)

@dataclass
class ScoreReport:
    """Assessment score report — Entity[str] with own MongoDB collection."""
    id: str                              # UUID
    lablet_session_id: str               # FK → LabletSession
    grading_session_id: str              # FK → GradingSession
    score: float = 0.0
    max_score: float = 0.0
    cut_score: float | None = None       # Passing threshold
    passed: bool | None = None
    sections: list[ScoreSection] = field(default_factory=list)
    submitted_at: datetime | None = None
    created_at: datetime = field(default_factory=datetime.utcnow)

@dataclass
class ScoreSection:
    """Value object — individual scoring section within a ScoreReport."""
    name: str
    score: float
    max_score: float
    weight: float = 1.0

Acceptance criteria:

• [ ] LabletSession aggregate has 11-state lifecycle with @dispatch handlers
• [ ] All 14 domain events defined and handled
• [ ] UserSession, GradingSession, ScoreReport entities created
• [ ] Old entity files (lablet_instance.py, lablet_lab_binding.py, lablet_record_run.py) deleted
• [ ] Domain unit tests pass (≥30 tests)

3.4 Sub-Phase 7D: CPA Application Layer — CQRS¶

Goal: Create/rename/delete commands and queries for the new entity model. Scope: control-plane-api application/ Estimate: 3 days

Acceptance criteria:

• [ ] All old lablet_instance/ and run/ command directories deleted
• [ ] All old lablet-instance/run query files deleted
• [ ] 8 lablet_session commands + 5 child entity commands created
• [ ] 2 lablet_session queries + 4 child entity queries created
• [ ] Handler tests pass (≥20 tests)

3.5 Sub-Phase 7E: CPA Integration Layer — Repositories + etcd¶

Goal: Implement MongoDB repositories for 4 entities, update etcd key structure. Scope: control-plane-api integration/ Estimate: 2 days

Acceptance criteria:

• [ ] 4 new MongoDB repositories operational (CRUD verified)
• [ ] Old repository files deleted
• [ ] etcd keys use /lcm/sessions/ prefix
• [ ] main.py DI registrations updated (net: remove 3 old + Task, add 4 new)
• [ ] Repository integration tests pass (≥10 tests)

3.6 Sub-Phase 7F: CPA API Layer — Controllers¶

Goal: Create new API endpoints, delete old ones. Scope: control-plane-api api/controllers/ Estimate: 2 days

Acceptance criteria:

• [ ] Old controllers deleted (lablet_instances_controller.py, lablet_record_runs_controller.py)
• [ ] SessionsController serves /api/v1/sessions/*
• [ ] Internal endpoints updated for session terminology
• [ ] Internal endpoints for child entity CRUD operational
• [ ] SSE events use lablet_session.* type prefix
• [ ] API tests pass (≥10 tests)

3.7 Sub-Phase 7G: lcm-core Client Update¶

Goal: Update ControlPlaneApiClient for new API paths and session terminology. Scope: lcm-core integration/ Estimate: 1 day

Acceptance criteria:

• [ ] All lablet_instance method names → lablet_session
• [ ] Removed methods: allocate_ports, bind_lab_to_lablet, unbind_lab_from_lablet
• [ ] 3 new child entity methods added
• [ ] All URL paths use /sessions/ not /lablet-instances/
• [ ] lcm-core make lint passes

3.8 Sub-Phase 7H: Controller Service Updates¶

Goal: Update lablet-controller and resource-scheduler to use new naming and API paths. Scope: lablet-controller, resource-scheduler Estimate: 3 days

Lablet-Controller¶

Resource-Scheduler¶

Acceptance criteria:

• [ ] LabletReconciler uses LabletSessionReadModel and session CPA client methods
• [ ] LabDiscoveryService updated for session terminology
• [ ] etcd watch prefix changed to /lcm/sessions/ in both LC and RS
• [ ] All LC and RS tests pass (make test for both)

3.9 Sub-Phase 7I: CloudEvent Webhook (lablet-controller) — ⏸️ DEFERRED¶

Goal: Implement simple CloudEvent webhook endpoint that proxies state mutations to CPA. Scope: lablet-controller Estimate: 2 days Decision: AD-P7-01 — Simple webhook → CPA proxy, no CQRS in LC Status: ⏸️ DEFERRED per AD-P7-06 (2026-02-20). Not a prerequisite for Phase 7J.

Rationale for deferral:

• CloudEvents provide automation of state transitions, not capability. The CPA already exposes all mutation endpoints via InternalSessionsController (POST /{session_id}/transition).
• The LabletSession state machine is fully functional — TransitionLabletSessionCommand validates against LABLET_SESSION_VALID_TRANSITIONS.
• The frontend (Phase 7J) will include manual action buttons for all transitions that CloudEvents would otherwise automate (READY→RUNNING, RUNNING→COLLECTING, etc.).
• Phase 7I is conceptually the deferred Phase 5 (Grading/LDS Integration) and belongs in a dedicated integration phase post-7.
• The dependency graph confirms 7I and 7J are independent parallel paths — both feed into 7K but neither depends on the other.

CloudEvent endpoint design:

The endpoint is provided by neuroglia cloudevent ingestor, no need to add explicit controller.

Acceptance criteria:

• [ ] POST /api/events endpoint registered and operational
• [ ] Handles 4 CloudEvent types: lds.session.started, lds.session.ended, grading.session.completed, grading.session.failed
• [ ] Each handler proxies state mutations to CPA via ControlPlaneApiClient
• [ ] No Mediator/CQRS/domain model added to lablet-controller
• [ ] Unit tests: ≥8 tests (2 per event type: success + error)
• [ ] Integration test: end-to-end HTTP POST → CPA mock

3.10 Sub-Phase 7J: Frontend Updates¶

Goal: Update frontend API paths and SSE event types. Scope: control-plane-api UI (src/ui/) Decision: AD-P7-04 — Accept broken frontend during implementation, fix here. Estimate: 1.5 days

Acceptance criteria:

• [ ] All API calls use /api/sessions/ paths
• [ ] SSE events correctly typed as lablet_session.*
• [ ] make build-ui passes
• [ ] Frontend loads and displays session data

3.11 Sub-Phase 7K: Tests & Verification¶

Goal: Ensure all services compile, lint, and pass tests. Run cross-service verification. Scope: All services Estimate: 2 days

Acceptance criteria:

• [ ] make lint passes for all services
• [ ] make test passes for all services
• [ ] docker compose up all services start cleanly
• [ ] Zero LabletInstance / lablet_instance references in Python source (docs excluded)
• [ ] Zero lablet_instances collection references
• [ ] Zero /lcm/instances/ etcd key references

3.12 Sub-Phase 7L: Documentation¶

Goal: Update all documentation to reflect the new entity model. Estimate: 1 day

4. Timeline Summary¶

5. Risk Register¶

6. Verification Checklist (Final Gate)¶

Before marking Phase 7 complete:

• [x] grep -r "LabletInstance" src/ --include="*.py" | grep -v __pycache__ returns 0 functional results (25 docstring/comment-only references remain — acceptable per AD-P7-05)
• [x] grep -r "lablet_instance" src/ --include="*.py" | grep -v __pycache__ returns 0 functional results (9 docstring/comment-only references remain)
• [x] grep -r "lablet_instances" src/ --include="*.py" | grep -v __pycache__ returns 0 functional results (1 docstring reference)
• [x] grep -r "lablet_lab_binding" src/ --include="*.py" | grep -v __pycache__ returns 0 results ✅
• [x] grep -r "lablet_record_run" src/ --include="*.py" | grep -v __pycache__ returns 0 results ✅
• [x] grep -r "/lcm/instances/" src/ --include="*.py" | grep -v __pycache__ returns 0 functional results (1 docstring example in tracing.py)
• [x] make lint passes for: lcm-core, control-plane-api, lablet-controller, resource-scheduler, worker-controller ✅
• [x] make test passes for: control-plane-api (589✅/1⚠️), lablet-controller (152✅), resource-scheduler (92✅/3⚠️), worker-controller (100✅) — failures are pre-existing
• [x] make build-ui passes ✅
• [x] MongoDB has collections: lablet_sessions, user_sessions, grading_sessions, score_reports ✅
• [x] MongoDB does NOT have: lablet_instances, lablet_lab_bindings, lablet_record_runs, tasks ✅

7. Phase 7J Bootstrap — Quick-Start Context¶

Purpose: Provide all context needed to start Phase 7J (Frontend Updates) efficiently. Created: 2026-02-20 (from Phase 7I/7J dependency analysis session)

7.1 Pre-7J Cleanup (from 7F residues)¶

Before starting 7J, delete this dead code:

• src/control-plane-api/api/controllers/lablet_record_runs_controller.py (455 lines) — references old LabletRecordRun commands. Should have been deleted in 7F.

7.2 Backend APIs Available for Frontend¶

Public endpoints (BFF, cookie auth):

Internal endpoints (API key auth — frontend uses BFF proxy pattern):

7.3 Frontend Files to Update¶

7.4 Manual Session Action Buttons (AD-P7-06)¶

Since CloudEvent automation is deferred, the frontend must expose these manual actions:

Note: The BFF controller needs a new POST /api/lablet-sessions/{id}/transition endpoint that proxies to the internal transition endpoint with the user's session cookie auth. This is a 7J task.

7.5 Sub-Phase Completion Snapshot (2026-02-20)¶

8. Phase 7K Bootstrap — Verification & Residue Cleanup¶

Purpose: Detailed 7K task list based on automated codebase audit (2026-02-20). Scope: All services — final cleanup, lint, test, smoke test. Estimate: 2 days

8.1 Residue Audit Findings¶

Automated grep audit of all Python source (excluding __pycache__, docs):

Functional Residue (Code, Not Comments)¶

These are actual code references that need renaming, not just docstring mentions:

Docstring/Comment Residue (Low Priority)¶

These are historical context references in docstrings — cosmetic cleanup, not blocking:

8.2 Phase 7K Task Breakdown¶

8.3 Recommended Execution Order¶

1. P7-K1 + P7-K2 (CMLWorker domain renames)           ← foundation
2. P7-K3 + P7-K4 + P7-K5 (command/event consumers)    ← depends on 1
3. P7-K6 + P7-K7 (lcm-core cleanup)                   ← independent
4. P7-K9 (test files)                                  ← depends on 1-2
5. P7-K8 (docstring cleanup)                           ← low priority
6. P7-K10 (rebuild UI)                                 ← independent
7. P7-K11 (lint all)                                   ← gate
8. P7-K12 (test all)                                   ← gate
9. P7-K13 (docker smoke test)                          ← final gate
10. P7-K14 (grep verification)                         ← sign-off

8.4 Decision Log Update¶

9. Revision History¶