Merge branch 'Refactor/Code-Quality'

Backend/cmd/worker/main.go

@@ -1,10 +1,16 @@
 package main
 
 import (
+	"context"
+	"encoding/json"
 	"log"
+	"os/signal"
+	"syscall"
+	"time"
 
 	"moku-backend/internal/bootstrap"
-	"moku-backend/internal/process"
+	"moku-backend/internal/jobs"
+	"moku-backend/internal/worker"
 )
 
 func main() {
@@ -18,9 +24,25 @@ func main() {
 		}
 	}()
 
-	app.Logger.Info("worker ready", "service", app.ServiceName, "environment", app.Config.Environment)
+	jobStore := jobs.NewStore(app.Database)
+	runner := worker.NewRunner(jobStore, app.Logger, time.Second)
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		var payload jobs.BootstrapStructureMaterializePayload
+		if len(job.Payload) > 0 {
+			if err := json.Unmarshal(job.Payload, &payload); err != nil {
+				return err
+			}
+		}
 
-	if err := process.WaitForShutdown(app.ServiceName, app.Logger); err != nil {
+		return bootstrap.NewService(app.Database, app.Config.POSIXRoot).ProcessBootstrapStructureMaterialization(ctx, payload.InstallationID)
+	})
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	app.Logger.Info("worker ready", "service", app.ServiceName, "environment", app.Config.Environment, "pollInterval", time.Second)
+
+	if err := runner.Run(ctx); err != nil {
 		app.Logger.Error("worker stopped", "error", err)
 		log.Fatal(err)
 	}

Backend/db/migrations/000005_background_jobs.sql

@@ -0,0 +1,64 @@
+-- +goose Up
+
+CREATE TYPE bootstrap_materialization_status AS ENUM ('not_started', 'pending', 'running', 'succeeded', 'failed');
+CREATE TYPE background_job_status AS ENUM ('pending', 'running', 'succeeded', 'failed');
+
+ALTER TABLE installations
+  ADD COLUMN IF NOT EXISTS materialization_status bootstrap_materialization_status NOT NULL DEFAULT 'not_started',
+  ADD COLUMN IF NOT EXISTS materialization_error TEXT,
+  ADD COLUMN IF NOT EXISTS materialization_requested_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS materialization_started_at TIMESTAMPTZ,
+  ADD COLUMN IF NOT EXISTS materialization_finished_at TIMESTAMPTZ;
+
+UPDATE installations
+SET
+  materialization_status = CASE
+    WHEN is_bootstrapped THEN 'succeeded'::bootstrap_materialization_status
+    ELSE 'not_started'::bootstrap_materialization_status
+  END,
+  materialization_error = NULL,
+  materialization_requested_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END,
+  materialization_started_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END,
+  materialization_finished_at = CASE
+    WHEN is_bootstrapped THEN COALESCE(bootstrapped_at, created_at, NOW())
+    ELSE NULL
+  END
+WHERE materialization_status = 'not_started'::bootstrap_materialization_status;
+
+CREATE TABLE IF NOT EXISTS background_jobs (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  kind TEXT NOT NULL,
+  status background_job_status NOT NULL DEFAULT 'pending',
+  payload JSONB NOT NULL DEFAULT '{}'::jsonb,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  max_attempts INTEGER NOT NULL DEFAULT 1,
+  available_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  started_at TIMESTAMPTZ,
+  finished_at TIMESTAMPTZ,
+  last_error TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_background_jobs_claim ON background_jobs (status, available_at, created_at);
+
+-- +goose Down
+
+DROP INDEX IF EXISTS idx_background_jobs_claim;
+DROP TABLE IF EXISTS background_jobs;
+
+ALTER TABLE installations
+  DROP COLUMN IF EXISTS materialization_finished_at,
+  DROP COLUMN IF EXISTS materialization_started_at,
+  DROP COLUMN IF EXISTS materialization_requested_at,
+  DROP COLUMN IF EXISTS materialization_error,
+  DROP COLUMN IF EXISTS materialization_status;
+
+DROP TYPE IF EXISTS background_job_status;
+DROP TYPE IF EXISTS bootstrap_materialization_status;

Backend/internal/bootstrap/bootstrap_installation.go

@@ -0,0 +1,159 @@
+package bootstrap
+
+import (
+	"context"
+	"errors"
+	"strings"
+
+	"github.com/jackc/pgx/v5"
+)
+
+const (
+	materializationNotStarted = "not_started"
+	materializationPending    = "pending"
+	materializationRunning    = "running"
+	materializationSucceeded  = "succeeded"
+	materializationFailed     = "failed"
+)
+
+type bootstrapStructurePrerequisites struct {
+	installation InstallationRecord
+	admin        AdminSummary
+}
+
+func (service *Service) GetInstallation(ctx context.Context) (*InstallationRecord, error) {
+	record, err := scanInstallationRecord(service.db.Pool.QueryRow(ctx, `
+		SELECT
+			id::text,
+			name,
+			mode::text,
+			access::text,
+			protocol::text,
+			host,
+			is_bootstrapped,
+			materialization_status::text,
+			materialization_error
+		FROM installations
+		WHERE singleton = TRUE
+		LIMIT 1;
+	`))
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &record, nil
+}
+
+func loadInstallation(ctx context.Context, tx pgx.Tx) (InstallationRecord, error) {
+	return scanInstallationRecord(tx.QueryRow(ctx, `
+		SELECT
+			id::text,
+			name,
+			mode::text,
+			access::text,
+			protocol::text,
+			host,
+			is_bootstrapped,
+			materialization_status::text,
+			materialization_error
+		FROM installations
+		WHERE singleton = TRUE
+		LIMIT 1;
+	`))
+}
+
+func updateBootstrappedInstallation(ctx context.Context, tx pgx.Tx) (InstallationRecord, error) {
+	return scanInstallationRecord(tx.QueryRow(ctx, `
+		UPDATE installations
+		SET
+			is_bootstrapped = TRUE,
+			bootstrapped_at = COALESCE(bootstrapped_at, NOW()),
+			materialization_status = 'pending'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_requested_at = NOW(),
+			materialization_started_at = NULL,
+			materialization_finished_at = NULL,
+			updated_at = NOW()
+		WHERE singleton = TRUE
+		RETURNING
+			id::text,
+			name,
+			mode::text,
+			access::text,
+			protocol::text,
+			host,
+			is_bootstrapped,
+			materialization_status::text,
+			materialization_error;
+	`))
+}
+
+func scanInstallationRecord(row pgx.Row) (InstallationRecord, error) {
+	var record InstallationRecord
+	if err := row.Scan(
+		&record.ID,
+		&record.Name,
+		&record.Mode,
+		&record.Access,
+		&record.Protocol,
+		&record.Host,
+		&record.IsBootstrapped,
+		&record.MaterializationStatus,
+		&record.MaterializationError,
+	); err != nil {
+		return InstallationRecord{}, err
+	}
+
+	if strings.TrimSpace(record.MaterializationStatus) == "" {
+		record.MaterializationStatus = materializationNotStarted
+	}
+
+	return record, nil
+}
+
+func loadPrimaryAdmin(ctx context.Context, tx pgx.Tx) (AdminSummary, error) {
+	var admin AdminSummary
+	if err := tx.QueryRow(ctx, `
+		SELECT id::text, email, display_name
+		FROM users
+		WHERE is_instance_admin = TRUE
+		ORDER BY created_at ASC
+		LIMIT 1;
+	`).Scan(&admin.ID, &admin.Email, &admin.DisplayName); err != nil {
+		return AdminSummary{}, err
+	}
+
+	return admin, nil
+}
+
+func (service *Service) loadBootstrapStructurePrerequisites(
+	ctx context.Context,
+	tx pgx.Tx,
+) (bootstrapStructurePrerequisites, error) {
+	installation, err := loadInstallation(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return bootstrapStructurePrerequisites{}, ErrInstallationNotConfigured
+		}
+
+		return bootstrapStructurePrerequisites{}, err
+	}
+
+	admin, err := loadPrimaryAdmin(ctx, tx)
+	if err != nil {
+		if errors.Is(err, pgx.ErrNoRows) {
+			return bootstrapStructurePrerequisites{}, ErrAdminNotConfigured
+		}
+
+		return bootstrapStructurePrerequisites{}, err
+	}
+
+	return bootstrapStructurePrerequisites{
+		installation: installation,
+		admin:        admin,
+	}, nil
+}

Backend/internal/bootstrap/bootstrap_materialization.go

@@ -0,0 +1,180 @@
+package bootstrap
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	"moku-backend/internal/jobs"
+	"moku-backend/internal/posixproj"
+)
+
+func (service *Service) enqueueBootstrapStructureMaterialization(
+	ctx context.Context,
+	installation *InstallationRecord,
+) error {
+	if installation == nil {
+		return nil
+	}
+
+	jobStore := jobs.NewStore(service.db)
+	if _, err := jobStore.Enqueue(ctx, jobs.EnqueueInput{
+		Kind: jobs.KindBootstrapStructureMaterialize,
+		Payload: jobs.BootstrapStructureMaterializePayload{
+			InstallationID: installation.ID,
+		},
+	}); err != nil {
+		failure := fmt.Sprintf("enqueue bootstrap materialization job: %v", err)
+		if markErr := service.markBootstrapMaterializationFailed(ctx, installation.ID, failure); markErr != nil {
+			return errors.Join(err, markErr)
+		}
+
+		// The relational bootstrap write already committed successfully, so keep the
+		// response successful and surface the enqueue problem via materialization state.
+		installation.MaterializationStatus = materializationFailed
+		installation.MaterializationError = &failure
+	}
+
+	return nil
+}
+
+func (service *Service) ProcessBootstrapStructureMaterialization(ctx context.Context, installationID string) error {
+	trimmedInstallationID := strings.TrimSpace(installationID)
+	if trimmedInstallationID == "" {
+		return ErrInstallationNotConfigured
+	}
+
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return err
+	}
+	if installation == nil || installation.ID != trimmedInstallationID {
+		return ErrInstallationNotConfigured
+	}
+
+	if err := service.markBootstrapMaterializationRunning(ctx, trimmedInstallationID); err != nil {
+		return err
+	}
+
+	if err := service.materializeBootstrapStructure(ctx, *installation); err != nil {
+		failure := strings.TrimSpace(err.Error())
+		if failure == "" {
+			failure = "bootstrap materialization failed"
+		}
+
+		if markErr := service.markBootstrapMaterializationFailed(ctx, trimmedInstallationID, failure); markErr != nil {
+			return errors.Join(err, markErr)
+		}
+
+		return err
+	}
+
+	return service.markBootstrapMaterializationSucceeded(ctx, trimmedInstallationID)
+}
+
+func (service *Service) materializeBootstrapStructure(ctx context.Context, installation InstallationRecord) error {
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return err
+	}
+	if admin == nil {
+		return ErrAdminNotConfigured
+	}
+
+	organization, err := service.loadPrimaryOrganization(ctx)
+	if err != nil {
+		return err
+	}
+	if organization == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	department, err := service.loadPrimaryDepartment(ctx)
+	if err != nil {
+		return err
+	}
+	if department == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	team, err := service.loadPrimaryTeam(ctx)
+	if err != nil {
+		return err
+	}
+	if team == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	project, err := service.loadPrimaryProject(ctx)
+	if err != nil {
+		return err
+	}
+	if project == nil {
+		return ErrBootstrapStructureMissing
+	}
+
+	if err := service.ensureBootstrapPOSIXSkeleton(
+		installation,
+		AdminSummary{ID: admin.ID, Email: admin.Email, DisplayName: admin.DisplayName},
+		namedRecord{ID: organization.ID, Name: organization.Name, Slug: organization.Slug},
+		namedRecord{ID: department.ID, Name: department.Name, Slug: department.Slug},
+		namedRecord{ID: team.ID, Name: team.Name, Slug: team.Slug},
+		namedRecord{ID: project.ID, Name: project.Name, Slug: project.Slug},
+	); err != nil {
+		return err
+	}
+
+	return service.rebuildProjection(ctx)
+}
+
+func (service *Service) rebuildProjection(ctx context.Context) error {
+	if err := posixproj.NewProjector(service.db, service.posixRoot).Rebuild(ctx); err != nil {
+		return fmt.Errorf("rebuild POSIX projection: %w", err)
+	}
+
+	return nil
+}
+
+func (service *Service) markBootstrapMaterializationRunning(ctx context.Context, installationID string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'running'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_started_at = NOW(),
+			materialization_finished_at = NULL,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID))
+
+	return err
+}
+
+func (service *Service) markBootstrapMaterializationSucceeded(ctx context.Context, installationID string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'succeeded'::bootstrap_materialization_status,
+			materialization_error = NULL,
+			materialization_finished_at = NOW(),
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID))
+
+	return err
+}
+
+func (service *Service) markBootstrapMaterializationFailed(ctx context.Context, installationID, failure string) error {
+	_, err := service.db.Pool.Exec(ctx, `
+		UPDATE installations
+		SET
+			materialization_status = 'failed'::bootstrap_materialization_status,
+			materialization_error = $2,
+			materialization_finished_at = NOW(),
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(installationID), strings.TrimSpace(failure))
+
+	return err
+}

Backend/internal/bootstrap/bootstrap_state.go

@@ -0,0 +1,73 @@
+package bootstrap
+
+import "context"
+
+func (service *Service) GetState(ctx context.Context) (BootstrapState, error) {
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	structure, err := service.GetStructure(ctx)
+	if err != nil {
+		return BootstrapState{}, err
+	}
+
+	return BootstrapState{
+		Installation: installation,
+		Admin:        admin,
+		Structure:    structure,
+	}, nil
+}
+
+func (service *Service) GetAppShellState(ctx context.Context) (AppShellState, error) {
+	installation, err := service.GetInstallation(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	admin, err := service.GetAdmin(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	organizations, err := service.listOrganizations(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	departments, err := service.listDepartments(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	teams, err := service.listTeams(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	projects, err := service.listProjects(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	workspaces, err := service.listWorkspaces(ctx)
+	if err != nil {
+		return AppShellState{}, err
+	}
+
+	return AppShellState{
+		Installation:  installation,
+		Admin:         admin,
+		Organizations: organizations,
+		Departments:   departments,
+		Teams:         teams,
+		Projects:      projects,
+		Workspaces:    workspaces,
+	}, nil
+}

Backend/internal/bootstrap/service_test.go

@@ -5,9 +5,70 @@ import (
 	"errors"
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 )
 
+type fakeRow struct {
+	scan func(dest ...any) error
+}
+
+func (row fakeRow) Scan(dest ...any) error {
+	return row.scan(dest...)
+}
+
+func TestScanInstallationRecordDefaultsMaterializationStatus(t *testing.T) {
+	record, err := scanInstallationRecord(fakeRow{scan: func(dest ...any) error {
+		*(dest[0].(*string)) = "installation-1"
+		*(dest[1].(*string)) = "MangoPig"
+		*(dest[2].(*string)) = "personal"
+		*(dest[3].(*string)) = "local"
+		*(dest[4].(*string)) = "http"
+		*(dest[5].(*string)) = "localhost"
+		*(dest[6].(*bool)) = true
+		*(dest[7].(*string)) = ""
+		*(dest[8].(**string)) = nil
+		return nil
+	}})
+	if err != nil {
+		t.Fatalf("scanInstallationRecord: %v", err)
+	}
+
+	if record.MaterializationStatus != materializationNotStarted {
+		t.Fatalf("expected default materialization status %q, got %q", materializationNotStarted, record.MaterializationStatus)
+	}
+	if record.MaterializationError != nil {
+		t.Fatalf("expected nil materialization error, got %#v", record.MaterializationError)
+	}
+}
+
+func TestScanInstallationRecordPreservesMaterializationFields(t *testing.T) {
+	failure := "projection rebuild failed"
+
+	record, err := scanInstallationRecord(fakeRow{scan: func(dest ...any) error {
+		*(dest[0].(*string)) = "installation-2"
+		*(dest[1].(*string)) = "MangoPig"
+		*(dest[2].(*string)) = "personal"
+		*(dest[3].(*string)) = "local"
+		*(dest[4].(*string)) = "http"
+		*(dest[5].(*string)) = "localhost"
+		*(dest[6].(*bool)) = true
+		*(dest[7].(*string)) = materializationFailed
+		*(dest[8].(**string)) = &failure
+		return nil
+	}})
+	if err != nil {
+		t.Fatalf("scanInstallationRecord: %v", err)
+	}
+
+	if record.MaterializationStatus != materializationFailed {
+		t.Fatalf("expected materialization status %q, got %q", materializationFailed, record.MaterializationStatus)
+	}
+	if record.MaterializationError == nil || *record.MaterializationError != failure {
+		t.Fatalf("expected materialization error %q, got %#v", failure, record.MaterializationError)
+	}
+}
+
 func TestEnsureBootstrapPOSIXSkeletonInitializesEmptyRoot(t *testing.T) {
 	rootPath := filepath.Join(t.TempDir(), "POSIX")
 	t.Setenv("POSIX_ROOT", rootPath)
@@ -166,6 +227,9 @@ func TestCreateProjectHierarchyFolderOnDiskCreatesExpectedFolderShape(t *testing
 	}
 
 	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(createdFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected created folder to have stable id, got %#v", folderPayload["id"])
+	}
 	if folderPayload["name"] != "Design System" {
 		t.Fatalf("expected folder name Design System, got %#v", folderPayload["name"])
 	}
@@ -282,6 +346,9 @@ func TestRenameProjectHierarchyFolderOnDiskRenamesFolderShape(t *testing.T) {
 	}
 
 	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(renamedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected renamed folder to preserve stable id, got %#v", folderPayload["id"])
+	}
 	if folderPayload["name"] != "Platform Design" {
 		t.Fatalf("expected renamed folder name Platform Design, got %#v", folderPayload["name"])
 	}
@@ -388,6 +455,9 @@ func TestMoveProjectHierarchyFolderOnDiskMovesFolderToNewParent(t *testing.T) {
 	}
 
 	folderPayload := readJSONFileForTest[map[string]any](t, filepath.Join(movedFolderPath, "folder.json"))
+	if strings.TrimSpace(asStringForTest(folderPayload["id"])) == "" {
+		t.Fatalf("expected moved folder to preserve stable id, got %#v", folderPayload["id"])
+	}
 	if folderPayload["name"] != "Research" {
 		t.Fatalf("expected moved folder name Research, got %#v", folderPayload["name"])
 	}
@@ -477,9 +547,9 @@ func TestMoveProjectHierarchyFolderOnDiskRejectsDescendantTarget(t *testing.T) {
 
 func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
 	rows := []projectHierarchyFolderRow{
-		{Path: "projects/project-primary-project/children/folder-design", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Design"},
-		{Path: "projects/project-primary-project/children/folder-design/children/folder-research", ParentPath: "projects/project-primary-project/children/folder-design/children", Label: "Research"},
-		{Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
+		{ID: "folder-design-id", Path: "projects/project-primary-project/children/folder-design", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Design"},
+		{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", ParentPath: "projects/project-primary-project/children/folder-design/children", Label: "Research"},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", ParentPath: projectHierarchyRootPath("primary-project"), Label: "Ops"},
 	}
 
 	folders := buildProjectHierarchyFolderTree(rows, projectHierarchyRootPath("primary-project"))
@@ -492,6 +562,64 @@ func TestBuildProjectHierarchyFolderTreeBuildsNestedStructure(t *testing.T) {
 	if len(folders[0].Children) != 1 || folders[0].Children[0].Label != "Research" {
 		t.Fatalf("unexpected nested folder structure: %#v", folders[0].Children)
 	}
+	if folders[0].ID != "folder-design-id" || folders[0].Path != "projects/project-primary-project/children/folder-design" {
+		t.Fatalf("expected design folder to retain stable id/path, got %#v", folders[0])
+	}
+	if folders[0].Children[0].ID != "folder-research-id" || folders[1].ID != "folder-ops-id" {
+		t.Fatalf("expected nested/top-level folder ids to be preserved, got %#v / %#v", folders[0].Children[0], folders[1])
+	}
+}
+
+func TestApplyProjectHierarchyFolderOrderingOrdersRootAndChildrenByStableID(t *testing.T) {
+	folders := []ProjectHierarchyFolderRecord{
+		{
+			ID:    "folder-design-id",
+			Path:  "projects/project-primary-project/children/folder-design",
+			Label: "Design",
+			Children: []ProjectHierarchyFolderRecord{
+				{ID: "folder-research-id", Path: "projects/project-primary-project/children/folder-design/children/folder-research", Label: "Research"},
+				{ID: "folder-assets-id", Path: "projects/project-primary-project/children/folder-design/children/folder-assets", Label: "Assets"},
+			},
+		},
+		{ID: "folder-ops-id", Path: "projects/project-primary-project/children/folder-ops", Label: "Ops"},
+		{ID: "folder-qa-id", Path: "projects/project-primary-project/children/folder-qa", Label: "QA"},
+	}
+
+	ordered := applyProjectHierarchyFolderOrdering(folders, map[string][]string{
+		projectFolderOrderRootKey: {"folder-qa-id", "folder-design-id"},
+		"folder-design-id":        {"folder-assets-id", "folder-research-id"},
+	})
+
+	if len(ordered) != 3 {
+		t.Fatalf("expected 3 ordered root folders, got %d", len(ordered))
+	}
+	if ordered[0].ID != "folder-qa-id" || ordered[1].ID != "folder-design-id" || ordered[2].ID != "folder-ops-id" {
+		t.Fatalf("unexpected ordered root ids: %#v", ordered)
+	}
+	if len(ordered[1].Children) != 2 {
+		t.Fatalf("expected design folder children to be preserved, got %#v", ordered[1].Children)
+	}
+	if ordered[1].Children[0].ID != "folder-assets-id" || ordered[1].Children[1].ID != "folder-research-id" {
+		t.Fatalf("unexpected ordered child ids: %#v", ordered[1].Children)
+	}
+}
+
+func TestInsertFolderOrderReordersWithinSameParent(t *testing.T) {
+	folderOrder := map[string][]string{
+		projectFolderOrderRootKey: {"folder-a", "folder-b", "folder-c"},
+	}
+
+	insertFolderOrder(folderOrder, "", "folder-c", 0)
+
+	got := folderOrder[projectFolderOrderRootKey]
+	if len(got) != 3 || got[0] != "folder-c" || got[1] != "folder-a" || got[2] != "folder-b" {
+		t.Fatalf("unexpected reordered root children: %#v", got)
+	}
+}
+
+func asStringForTest(value any) string {
+	text, _ := value.(string)
+	return text
 }
 
 func readJSONFileForTest[T any](t *testing.T, path string) T {

Backend/internal/httpx/api_project_routes.go

@@ -13,22 +13,27 @@ import (
 )
 
 type createProjectFolderRequest struct {
-	Name           string `json:"name"`
-	ParentFolderID string `json:"parentFolderId"`
+	Name             string `json:"name"`
+	ParentFolderPath string `json:"parentFolderId"`
 }
 
 type renameProjectFolderRequest struct {
-	FolderID string `json:"folderId"`
-	Name     string `json:"name"`
+	FolderPath string `json:"folderId"`
+	Name       string `json:"name"`
 }
 
 type deleteProjectFolderRequest struct {
-	FolderID string `json:"folderId"`
+	FolderPath string `json:"folderId"`
 }
 
+// Keep the existing JSON contract for the frontend, but use clearer path-vs-stable-ID
+// names internally so the move flow is easier to reason about.
 type moveProjectFolderRequest struct {
-	FolderID       string `json:"folderId"`
-	ParentFolderID string `json:"parentFolderId"`
+	FolderPath       string `json:"folderId"`
+	FolderStableID   string `json:"folderNodeId"`
+	ParentFolderPath string `json:"parentFolderId"`
+	ParentStableID   string `json:"parentNodeId"`
+	TargetIndex      int    `json:"targetIndex"`
 }
 
 func (routes apiRoutes) handleProjectFolders(w http.ResponseWriter, r *http.Request) {
@@ -68,16 +73,16 @@ func (routes apiRoutes) handleCreateProjectFolder(w http.ResponseWriter, r *http
 	}
 
 	payload.Name = strings.TrimSpace(payload.Name)
-	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentFolderPath = strings.TrimSpace(payload.ParentFolderPath)
 	if payload.Name == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().CreateProjectFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
-		ProjectID:      projectID,
-		ParentFolderID: payload.ParentFolderID,
-		Name:           payload.Name,
+		ProjectID:        projectID,
+		ParentFolderPath: payload.ParentFolderPath,
+		Name:             payload.Name,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "persist")
@@ -101,14 +106,14 @@ func (routes apiRoutes) handleDeleteProjectFolder(w http.ResponseWriter, r *http
 	}
 
 	payload := decodeDeleteProjectFolderRequest(r)
-	if strings.TrimSpace(payload.FolderID) == "" {
+	if strings.TrimSpace(payload.FolderPath) == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().DeleteProjectFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
-		ProjectID: projectID,
-		FolderID:  payload.FolderID,
+		ProjectID:  projectID,
+		FolderPath: payload.FolderPath,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "delete")
@@ -136,9 +141,9 @@ func (routes apiRoutes) handleRenameProjectFolder(w http.ResponseWriter, r *http
 		return
 	}
 
-	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderPath = strings.TrimSpace(payload.FolderPath)
 	payload.Name = strings.TrimSpace(payload.Name)
-	if payload.FolderID == "" {
+	if payload.FolderPath == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
@@ -148,9 +153,9 @@ func (routes apiRoutes) handleRenameProjectFolder(w http.ResponseWriter, r *http
 	}
 
 	result, err := routes.bootstrapService().RenameProjectFolder(r.Context(), bootstrapservice.RenameProjectFolderInput{
-		ProjectID: projectID,
-		FolderID:  payload.FolderID,
-		Name:      payload.Name,
+		ProjectID:  projectID,
+		FolderPath: payload.FolderPath,
+		Name:       payload.Name,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "rename")
@@ -178,17 +183,22 @@ func (routes apiRoutes) handleMoveProjectFolder(w http.ResponseWriter, r *http.R
 		return
 	}
 
-	payload.FolderID = strings.TrimSpace(payload.FolderID)
-	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
-	if payload.FolderID == "" {
+	payload.FolderPath = strings.TrimSpace(payload.FolderPath)
+	payload.FolderStableID = strings.TrimSpace(payload.FolderStableID)
+	payload.ParentFolderPath = strings.TrimSpace(payload.ParentFolderPath)
+	payload.ParentStableID = strings.TrimSpace(payload.ParentStableID)
+	if payload.FolderPath == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().MoveProjectFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
-		ProjectID:      projectID,
-		FolderID:       payload.FolderID,
-		ParentFolderID: payload.ParentFolderID,
+		ProjectID:        projectID,
+		FolderPath:       payload.FolderPath,
+		FolderStableID:   payload.FolderStableID,
+		ParentFolderPath: payload.ParentFolderPath,
+		ParentStableID:   payload.ParentStableID,
+		TargetIndex:      payload.TargetIndex,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "move")
@@ -241,16 +251,16 @@ func (routes apiRoutes) handleCreateProjectTreeFolder(w http.ResponseWriter, r *
 	}
 
 	payload.Name = strings.TrimSpace(payload.Name)
-	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
+	payload.ParentFolderPath = strings.TrimSpace(payload.ParentFolderPath)
 	if payload.Name == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder name is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().CreateProjectTreeFolder(r.Context(), bootstrapservice.CreateProjectFolderInput{
-		ProjectID:      projectID,
-		ParentFolderID: payload.ParentFolderID,
-		Name:           payload.Name,
+		ProjectID:        projectID,
+		ParentFolderPath: payload.ParentFolderPath,
+		Name:             payload.Name,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "persist")
@@ -274,14 +284,14 @@ func (routes apiRoutes) handleDeleteProjectTreeFolder(w http.ResponseWriter, r *
 	}
 
 	payload := decodeDeleteProjectFolderRequest(r)
-	if strings.TrimSpace(payload.FolderID) == "" {
+	if strings.TrimSpace(payload.FolderPath) == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().DeleteProjectTreeFolder(r.Context(), bootstrapservice.DeleteProjectFolderInput{
-		ProjectID: projectID,
-		FolderID:  payload.FolderID,
+		ProjectID:  projectID,
+		FolderPath: payload.FolderPath,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "delete")
@@ -309,9 +319,9 @@ func (routes apiRoutes) handleRenameProjectTreeFolder(w http.ResponseWriter, r *
 		return
 	}
 
-	payload.FolderID = strings.TrimSpace(payload.FolderID)
+	payload.FolderPath = strings.TrimSpace(payload.FolderPath)
 	payload.Name = strings.TrimSpace(payload.Name)
-	if payload.FolderID == "" {
+	if payload.FolderPath == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
@@ -321,9 +331,9 @@ func (routes apiRoutes) handleRenameProjectTreeFolder(w http.ResponseWriter, r *
 	}
 
 	result, err := routes.bootstrapService().RenameProjectTreeFolder(r.Context(), bootstrapservice.RenameProjectFolderInput{
-		ProjectID: projectID,
-		FolderID:  payload.FolderID,
-		Name:      payload.Name,
+		ProjectID:  projectID,
+		FolderPath: payload.FolderPath,
+		Name:       payload.Name,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "rename")
@@ -351,17 +361,22 @@ func (routes apiRoutes) handleMoveProjectTreeFolder(w http.ResponseWriter, r *ht
 		return
 	}
 
-	payload.FolderID = strings.TrimSpace(payload.FolderID)
-	payload.ParentFolderID = strings.TrimSpace(payload.ParentFolderID)
-	if payload.FolderID == "" {
+	payload.FolderPath = strings.TrimSpace(payload.FolderPath)
+	payload.FolderStableID = strings.TrimSpace(payload.FolderStableID)
+	payload.ParentFolderPath = strings.TrimSpace(payload.ParentFolderPath)
+	payload.ParentStableID = strings.TrimSpace(payload.ParentStableID)
+	if payload.FolderPath == "" {
 		WriteError(w, http.StatusBadRequest, RequestIDFromContext(r.Context()), "invalid_request", "Folder ID is required.")
 		return
 	}
 
 	result, err := routes.bootstrapService().MoveProjectTreeFolder(r.Context(), bootstrapservice.MoveProjectFolderInput{
-		ProjectID:      projectID,
-		FolderID:       payload.FolderID,
-		ParentFolderID: payload.ParentFolderID,
+		ProjectID:        projectID,
+		FolderPath:       payload.FolderPath,
+		FolderStableID:   payload.FolderStableID,
+		ParentFolderPath: payload.ParentFolderPath,
+		ParentStableID:   payload.ParentStableID,
+		TargetIndex:      payload.TargetIndex,
 	})
 	if err != nil {
 		routes.writeProjectFolderError(w, r, err, "move")
@@ -419,7 +434,7 @@ func decodeMoveProjectFolderRequest(w http.ResponseWriter, r *http.Request) (mov
 
 func decodeDeleteProjectFolderRequest(r *http.Request) deleteProjectFolderRequest {
 	return deleteProjectFolderRequest{
-		FolderID: strings.TrimSpace(r.URL.Query().Get("folderId")),
+		FolderPath: strings.TrimSpace(r.URL.Query().Get("folderId")),
 	}
 }
 

Backend/internal/jobs/store.go

@@ -0,0 +1,196 @@
+package jobs
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+
+	"moku-backend/internal/database"
+)
+
+const (
+	KindBootstrapStructureMaterialize = "bootstrap.structure.materialize"
+)
+
+type Status string
+
+const (
+	StatusPending   Status = "pending"
+	StatusRunning   Status = "running"
+	StatusSucceeded Status = "succeeded"
+	StatusFailed    Status = "failed"
+)
+
+type BootstrapStructureMaterializePayload struct {
+	InstallationID string `json:"installationId"`
+}
+
+type Job struct {
+	ID          string
+	Kind        string
+	Status      Status
+	Payload     json.RawMessage
+	Attempts    int
+	MaxAttempts int
+	AvailableAt time.Time
+	StartedAt   *time.Time
+	FinishedAt  *time.Time
+	LastError   *string
+	CreatedAt   time.Time
+	UpdatedAt   time.Time
+}
+
+type EnqueueInput struct {
+	Kind        string
+	Payload     any
+	AvailableAt time.Time
+	MaxAttempts int
+}
+
+type Store struct {
+	db *database.DB
+}
+
+func NewStore(db *database.DB) *Store {
+	return &Store{db: db}
+}
+
+func (store *Store) Enqueue(ctx context.Context, input EnqueueInput) (Job, error) {
+	payload := json.RawMessage([]byte(`{}`))
+	if input.Payload != nil {
+		encoded, err := json.Marshal(input.Payload)
+		if err != nil {
+			return Job{}, err
+		}
+		payload = encoded
+	}
+
+	availableAt := input.AvailableAt
+	if availableAt.IsZero() {
+		availableAt = time.Now().UTC()
+	}
+
+	maxAttempts := input.MaxAttempts
+	if maxAttempts < 1 {
+		maxAttempts = 1
+	}
+
+	return scanJob(store.db.Pool.QueryRow(ctx, `
+		INSERT INTO background_jobs (kind, status, payload, attempts, max_attempts, available_at)
+		VALUES ($1, 'pending'::background_job_status, $2::jsonb, 0, $3, $4)
+		RETURNING
+			id::text,
+			kind,
+			status::text,
+			payload,
+			attempts,
+			max_attempts,
+			available_at,
+			started_at,
+			finished_at,
+			last_error,
+			created_at,
+			updated_at;
+	`, strings.TrimSpace(input.Kind), payload, maxAttempts, availableAt))
+}
+
+func (store *Store) ClaimNext(ctx context.Context) (*Job, error) {
+	job, err := scanJob(store.db.Pool.QueryRow(ctx, `
+		WITH next_job AS (
+			SELECT id
+			FROM background_jobs
+			WHERE status = 'pending'::background_job_status
+				AND available_at <= NOW()
+			ORDER BY created_at ASC
+			LIMIT 1
+			FOR UPDATE SKIP LOCKED
+		)
+		UPDATE background_jobs AS jobs
+		SET
+			status = 'running'::background_job_status,
+			attempts = jobs.attempts + 1,
+			started_at = NOW(),
+			finished_at = NULL,
+			last_error = NULL,
+			updated_at = NOW()
+		FROM next_job
+		WHERE jobs.id = next_job.id
+		RETURNING
+			jobs.id::text,
+			jobs.kind,
+			jobs.status::text,
+			jobs.payload,
+			jobs.attempts,
+			jobs.max_attempts,
+			jobs.available_at,
+			jobs.started_at,
+			jobs.finished_at,
+			jobs.last_error,
+			jobs.created_at,
+			jobs.updated_at;
+	`))
+	if err != nil {
+		if err == pgx.ErrNoRows {
+			return nil, nil
+		}
+
+		return nil, err
+	}
+
+	return &job, nil
+}
+
+func (store *Store) MarkSucceeded(ctx context.Context, jobID string) error {
+	_, err := store.db.Pool.Exec(ctx, `
+		UPDATE background_jobs
+		SET
+			status = 'succeeded'::background_job_status,
+			finished_at = NOW(),
+			last_error = NULL,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(jobID))
+
+	return err
+}
+
+func (store *Store) MarkFailed(ctx context.Context, jobID, failure string) error {
+	_, err := store.db.Pool.Exec(ctx, `
+		UPDATE background_jobs
+		SET
+			status = 'failed'::background_job_status,
+			finished_at = NOW(),
+			last_error = $2,
+			updated_at = NOW()
+		WHERE id = $1::uuid;
+	`, strings.TrimSpace(jobID), strings.TrimSpace(failure))
+
+	return err
+}
+
+func scanJob(row pgx.Row) (Job, error) {
+	var job Job
+	var status string
+	if err := row.Scan(
+		&job.ID,
+		&job.Kind,
+		&status,
+		&job.Payload,
+		&job.Attempts,
+		&job.MaxAttempts,
+		&job.AvailableAt,
+		&job.StartedAt,
+		&job.FinishedAt,
+		&job.LastError,
+		&job.CreatedAt,
+		&job.UpdatedAt,
+	); err != nil {
+		return Job{}, err
+	}
+
+	job.Status = Status(status)
+	return job, nil
+}

Backend/internal/worker/runner.go

@@ -0,0 +1,118 @@
+package worker
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"strings"
+	"time"
+
+	"moku-backend/internal/jobs"
+)
+
+type JobStore interface {
+	ClaimNext(ctx context.Context) (*jobs.Job, error)
+	MarkSucceeded(ctx context.Context, jobID string) error
+	MarkFailed(ctx context.Context, jobID, failure string) error
+}
+
+type Handler func(ctx context.Context, job jobs.Job) error
+
+type Runner struct {
+	store        JobStore
+	logger       *slog.Logger
+	pollInterval time.Duration
+	handlers     map[string]Handler
+}
+
+func NewRunner(store JobStore, logger *slog.Logger, pollInterval time.Duration) *Runner {
+	interval := pollInterval
+	if interval <= 0 {
+		interval = time.Second
+	}
+
+	return &Runner{
+		store:        store,
+		logger:       logger,
+		pollInterval: interval,
+		handlers:     make(map[string]Handler),
+	}
+}
+
+func (runner *Runner) Register(kind string, handler Handler) {
+	runner.handlers[strings.TrimSpace(kind)] = handler
+}
+
+func (runner *Runner) Run(ctx context.Context) error {
+	for {
+		select {
+		case <-ctx.Done():
+			return nil
+		default:
+		}
+
+		job, err := runner.store.ClaimNext(ctx)
+		if err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+
+			return err
+		}
+
+		if job == nil {
+			if err := waitForNextPoll(ctx, runner.pollInterval); err != nil {
+				return nil
+			}
+
+			continue
+		}
+
+		handler, ok := runner.handlers[job.Kind]
+		if !ok {
+			failure := fmt.Sprintf("no handler registered for job kind %q", job.Kind)
+			if err := runner.store.MarkFailed(ctx, job.ID, failure); err != nil {
+				return err
+			}
+
+			runner.logger.Error("worker job failed", "jobID", job.ID, "kind", job.Kind, "error", failure)
+			continue
+		}
+
+		if err := handler(ctx, *job); err != nil {
+			if ctx.Err() != nil {
+				return nil
+			}
+
+			failure := strings.TrimSpace(err.Error())
+			if failure == "" {
+				failure = "job handler returned an empty error"
+			}
+
+			if markErr := runner.store.MarkFailed(ctx, job.ID, failure); markErr != nil {
+				return markErr
+			}
+
+			runner.logger.Error("worker job failed", "jobID", job.ID, "kind", job.Kind, "error", failure)
+			continue
+		}
+
+		if err := runner.store.MarkSucceeded(ctx, job.ID); err != nil {
+			return err
+		}
+
+		runner.logger.Info("worker job succeeded", "jobID", job.ID, "kind", job.Kind)
+	}
+}
+
+func waitForNextPoll(ctx context.Context, interval time.Duration) error {
+	timer := time.NewTimer(interval)
+	defer timer.Stop()
+
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+	case <-timer.C:
+		return nil
+	}
+}

Backend/internal/worker/runner_test.go

@@ -0,0 +1,161 @@
+package worker
+
+import (
+	"context"
+	"errors"
+	"io"
+	"log/slog"
+	"strings"
+	"sync"
+	"testing"
+
+	"moku-backend/internal/jobs"
+)
+
+func TestRunnerProcessesRegisteredJob(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:      "job-1",
+			Kind:    jobs.KindBootstrapStructureMaterialize,
+			Payload: []byte(`{"installationId":"installation-1"}`),
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+
+	handlerCalled := false
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		handlerCalled = true
+		if job.ID != "job-1" {
+			t.Fatalf("expected job id job-1, got %s", job.ID)
+		}
+		return nil
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if !handlerCalled {
+		t.Fatal("expected handler to be called")
+	}
+	if len(store.succeeded) != 1 || store.succeeded[0] != "job-1" {
+		t.Fatalf("expected job to be marked succeeded once, got %#v", store.succeeded)
+	}
+	if len(store.failed) != 0 {
+		t.Fatalf("expected no failed jobs, got %#v", store.failed)
+	}
+}
+
+func TestRunnerMarksFailedWhenHandlerErrors(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:   "job-2",
+			Kind: jobs.KindBootstrapStructureMaterialize,
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+	runner.Register(jobs.KindBootstrapStructureMaterialize, func(ctx context.Context, job jobs.Job) error {
+		return errors.New("boom")
+	})
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if len(store.succeeded) != 0 {
+		t.Fatalf("expected no succeeded jobs, got %#v", store.succeeded)
+	}
+	if len(store.failed) != 1 {
+		t.Fatalf("expected one failed job, got %#v", store.failed)
+	}
+	if store.failed[0].jobID != "job-2" {
+		t.Fatalf("expected failed job id job-2, got %#v", store.failed[0])
+	}
+	if !strings.Contains(store.failed[0].failure, "boom") {
+		t.Fatalf("expected failure to mention handler error, got %#v", store.failed[0])
+	}
+}
+
+func TestRunnerMarksFailedWhenHandlerMissing(t *testing.T) {
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	store := &fakeJobStore{
+		job: &jobs.Job{
+			ID:   "job-3",
+			Kind: "unknown.kind",
+		},
+		cancel: cancel,
+	}
+	runner := NewRunner(store, slog.New(slog.NewTextHandler(io.Discard, nil)), 0)
+
+	if err := runner.Run(ctx); err != nil {
+		t.Fatalf("runner returned error: %v", err)
+	}
+
+	if len(store.failed) != 1 {
+		t.Fatalf("expected one failed job, got %#v", store.failed)
+	}
+	if !strings.Contains(store.failed[0].failure, "no handler registered") {
+		t.Fatalf("expected missing handler failure, got %#v", store.failed[0])
+	}
+}
+
+type fakeJobStore struct {
+	mu        sync.Mutex
+	job       *jobs.Job
+	claimed   bool
+	succeeded []string
+	failed    []fakeFailure
+	cancel    context.CancelFunc
+}
+
+type fakeFailure struct {
+	jobID   string
+	failure string
+}
+
+func (store *fakeJobStore) ClaimNext(ctx context.Context) (*jobs.Job, error) {
+	store.mu.Lock()
+	defer store.mu.Unlock()
+
+	if store.claimed || store.job == nil {
+		return nil, nil
+	}
+
+	store.claimed = true
+	job := *store.job
+	return &job, nil
+}
+
+func (store *fakeJobStore) MarkSucceeded(ctx context.Context, jobID string) error {
+	store.mu.Lock()
+	store.succeeded = append(store.succeeded, jobID)
+	store.mu.Unlock()
+
+	if store.cancel != nil {
+		store.cancel()
+	}
+
+	return nil
+}
+
+func (store *fakeJobStore) MarkFailed(ctx context.Context, jobID, failure string) error {
+	store.mu.Lock()
+	store.failed = append(store.failed, fakeFailure{jobID: jobID, failure: failure})
+	store.mu.Unlock()
+
+	if store.cancel != nil {
+		store.cancel()
+	}
+
+	return nil
+}

Frontend/src/components/shell/ProjectSelector/ProjectSelector.tsx

@@ -36,6 +36,7 @@ type ProjectSelectorProps = {
 type ProjectFolderNode = {
 	kind: "folder";
 	id: string;
+	path: string;
 	label: string;
 	meta?: string;
 	children: ProjectTreeNode[];
@@ -50,6 +51,7 @@ type ProjectTreeNode = ProjectFolderNode | ProjectLeafNode;
 
 type PersistedProjectFolderRecord = {
 	id: string;
+	path: string;
 	label: string;
 	children: PersistedProjectFolderRecord[];
 };
@@ -60,6 +62,7 @@ type ProjectFoldersResponse = {
 		renamedFolder?: PersistedProjectFolderRecord;
 		movedFolder?: PersistedProjectFolderRecord;
 		previousFolderId?: string;
+		previousFolderPath?: string;
 	};
 	error?: string;
 	message?: string;
@@ -91,6 +94,7 @@ const buildPersistedFolderNodes = (folders: readonly PersistedProjectFolderRecor
 	folders.map((folder) => ({
 		kind: "folder",
 		id: folder.id,
+		path: folder.path,
 		label: folder.label,
 		children: buildPersistedFolderNodes(folder.children ?? []),
 	}));
@@ -99,6 +103,9 @@ const buildProjectTree = (
 	items: readonly ProjectItem[],
 	folders: readonly PersistedProjectFolderRecord[] = [],
 ): ProjectTreeNode[] => [
+	// The selector still presents scaffold project leaves beside persisted folders.
+	// Keep that mixed root shape explicit here so the drag/drop logic can account
+	// for folder-only ordering when we persist sibling positions.
 	...items.map((item) => ({
 		kind: "project" as const,
 		item,
@@ -106,6 +113,11 @@ const buildProjectTree = (
 	...buildPersistedFolderNodes(folders),
 ];
 
+const countProjectFolderSiblingsBeforeIndex = (
+	siblings: readonly ProjectTreeNode[],
+	index: number,
+): number => siblings.slice(0, index).filter((node) => node.kind === "folder").length;
+
 const readPersistedFolders = (body: ProjectFoldersResponse): PersistedProjectFolderRecord[] =>
 	Array.isArray(body.data?.folders) ? body.data.folders : [];
 
@@ -578,18 +590,40 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 
 			const currentNodes = projectTreeNodes();
 			const draggedLocation = findTreeNodeLocation(currentNodes, nextDragState.draggedNodeId, projectTreeAdapter);
-			const persistedParentId = nextDragState.dropTarget.parentId;
 			const canPersistMove = isUuidString(selectedProject().id);
-			const persistedParentLocation = persistedParentId
-				? findTreeNodeLocation(currentNodes, persistedParentId, projectTreeAdapter)
+			const draggedFolderPath = draggedLocation?.node.kind === "folder" ? draggedLocation.node.path : null;
+			const previewNodes = moveTreeNode(currentNodes, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter);
+			const previewLocation = findTreeNodeLocation(previewNodes, nextDragState.draggedNodeId, projectTreeAdapter);
+			const persistedParentLocation = previewLocation?.parentId
+				? findTreeNodeLocation(previewNodes, previewLocation.parentId, projectTreeAdapter)
 				: null;
+			const persistedParentFolderPath =
+				persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.path : null;
+			const previewSiblings = previewLocation?.parentId
+				? persistedParentLocation?.node.kind === "folder"
+					? persistedParentLocation.node.children
+					: []
+				: previewNodes;
+			// The preview tree includes project leaves and folders, but the backend only
+			// stores sibling order for folders. Persist a folder-only index so the server
+			// can reapply the same position against the authoritative ordered tree.
+			const targetIndex = previewLocation
+				? countProjectFolderSiblingsBeforeIndex(previewSiblings, previewLocation.index)
+				: 0;
 
 			if (
 				canPersistMove &&
 				draggedLocation?.node.kind === "folder" &&
-				(persistedParentId === null || persistedParentLocation?.node.kind === "folder")
+				draggedFolderPath &&
+				(!previewLocation?.parentId || persistedParentLocation?.node.kind === "folder")
 			) {
-				void movePersistedFolder(draggedLocation.node.id, persistedParentId);
+				void movePersistedFolder(
+					draggedFolderPath,
+					persistedParentFolderPath,
+					draggedLocation.node.id,
+					persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.id : null,
+					targetIndex,
+				);
 			} else {
 				setProjectTreeNodes((current) =>
 					moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as ProjectDragTarget, projectTreeAdapter),
@@ -674,6 +708,11 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		setPendingFolderRenameName(label);
 	};
 
+	const resolveFolderPath = (folderId: string): string | null => {
+		const location = findTreeNodeLocation(projectTreeNodes(), folderId, projectTreeAdapter);
+		return location && location.node.kind === "folder" ? location.node.path : null;
+	};
+
 	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
@@ -694,6 +733,12 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const parentFolderPath = draft.parentId ? resolveFolderPath(draft.parentId) : null;
+		if (draft.parentId && !parentFolderPath) {
+			cancelPendingFolder();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders`, {
 				method: "POST",
@@ -703,7 +748,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 				},
 				body: JSON.stringify({
 					name,
-					parentFolderId: draft.parentId,
+					parentFolderId: parentFolderPath,
 				}),
 			});
 
@@ -727,9 +772,14 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(folderId);
+		if (!folderPath) {
+			return;
+		}
+
 		try {
 			const response = await fetch(
-				`${resolveAPIBase()}/projects/${projectId}/folders?folderId=${encodeURIComponent(folderId)}`,
+				`${resolveAPIBase()}/projects/${projectId}/folders?folderId=${encodeURIComponent(folderPath)}`,
 				{
 					method: "DELETE",
 					headers: {
@@ -751,9 +801,15 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 		}
 	};
 
-	const movePersistedFolder = async (folderId: string, parentFolderId: string | null): Promise<void> => {
+	const movePersistedFolder = async (
+		folderPath: string,
+		parentFolderPath: string | null,
+		folderStableId: string,
+		parentStableId: string | null,
+		targetIndex: number,
+	): Promise<void> => {
 		const projectId = selectedProject().id;
-		if (!folderId || !isUuidString(projectId)) {
+		if (!folderPath || !folderStableId || !isUuidString(projectId)) {
 			return;
 		}
 
@@ -765,8 +821,11 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId,
-					parentFolderId,
+					folderId: folderPath,
+					folderNodeId: folderStableId,
+					parentFolderId: parentFolderPath,
+					parentNodeId: parentStableId,
+					targetIndex,
 				}),
 			});
 
@@ -777,14 +836,6 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			}
 
 			setPersistedFolders(readPersistedFolders(body));
-
-			const previousFolderId = body.data?.previousFolderId;
-			const movedFolderId = body.data?.movedFolder?.id;
-			if (previousFolderId && movedFolderId && previousFolderId !== movedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? movedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}
@@ -810,6 +861,12 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(draft.folderId);
+		if (!folderPath) {
+			cancelPendingFolderRename();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/folders`, {
 				method: "PATCH",
@@ -818,7 +875,7 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId: draft.folderId,
+					folderId: folderPath,
 					name,
 				}),
 			});
@@ -832,14 +889,6 @@ export const ProjectSelector = (props: ProjectSelectorProps): JSX.Element => {
 			setPersistedFolders(readPersistedFolders(body));
 			setPendingFolderRename(null);
 			setPendingFolderRenameName("");
-
-			const previousFolderId = body.data?.previousFolderId;
-			const renamedFolderId = body.data?.renamedFolder?.id;
-			if (previousFolderId && renamedFolderId && previousFolderId !== renamedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? renamedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}

Frontend/src/components/shell/WorkspaceSidebar/WorkspaceSidebar.tsx

@@ -52,6 +52,7 @@ type WorkspaceDragState = {
 
 type PersistedWorkspaceFolderRecord = {
 	id: string;
+	path: string;
 	label: string;
 	children?: PersistedWorkspaceFolderRecord[];
 };
@@ -62,6 +63,7 @@ type WorkspaceFoldersResponse = {
 		renamedFolder?: PersistedWorkspaceFolderRecord;
 		movedFolder?: PersistedWorkspaceFolderRecord;
 		previousFolderId?: string;
+		previousFolderPath?: string;
 	};
 	error?: string;
 	message?: string;
@@ -81,6 +83,7 @@ const buildPersistedWorkspaceFolderNodes = (
 ): WorkspaceTreeNode[] =>
 	folders.map((folder) => ({
 		id: folder.id,
+		path: folder.path,
 		label: folder.label,
 		kind: "folder",
 		icon: Folder,
@@ -90,6 +93,11 @@ const buildPersistedWorkspaceFolderNodes = (
 const readPersistedWorkspaceFolders = (body: WorkspaceFoldersResponse): PersistedWorkspaceFolderRecord[] =>
 	Array.isArray(body.data?.folders) ? body.data.folders : [];
 
+const countWorkspaceFolderSiblingsBeforeIndex = (
+	siblings: readonly WorkspaceTreeNode[],
+	index: number,
+): number => siblings.slice(0, index).filter((node) => node.kind === "folder").length;
+
 const workspaceTreeAdapter: NavTreeAdapter<WorkspaceTreeNode> = {
 	getNodeId: getWorkspaceTreeNodeId,
 	isBranchNode: (node) => node.kind === "folder",
@@ -532,18 +540,39 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 			const currentNodes = workspaceTreeNodes();
 			const draggedLocation = findTreeNodeLocation(currentNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
-			const persistedParentId = nextDragState.dropTarget.parentId;
 			const canPersistMove = isUuidString(activeProject()?.id ?? "");
-			const persistedParentLocation = persistedParentId
-				? findTreeNodeLocation(currentNodes, persistedParentId, workspaceTreeAdapter)
+			const draggedFolderPath = draggedLocation?.node.kind === "folder" ? draggedLocation.node.path ?? null : null;
+			const previewNodes = moveTreeNode(currentNodes, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter);
+			const previewLocation = findTreeNodeLocation(previewNodes, nextDragState.draggedNodeId, workspaceTreeAdapter);
+			const persistedParentLocation = previewLocation?.parentId
+				? findTreeNodeLocation(previewNodes, previewLocation.parentId, workspaceTreeAdapter)
 				: null;
+			const persistedParentFolderPath = persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.path ?? null : null;
+			const previewSiblings = previewLocation?.parentId
+				? persistedParentLocation?.node.kind === "folder"
+					? persistedParentLocation.node.children ?? []
+					: []
+				: previewNodes;
+			// The tree preview can include static/workspace items, but persisted ordering
+			// only applies to folder siblings. Convert the preview position into a folder-
+			// only index before sending it to the backend move endpoint.
+			const targetIndex = previewLocation
+				? countWorkspaceFolderSiblingsBeforeIndex(previewSiblings, previewLocation.index)
+				: 0;
 
 			if (
 				canPersistMove &&
 				draggedLocation?.node.kind === "folder" &&
-				(persistedParentId === null || persistedParentLocation?.node.kind === "folder")
+				draggedFolderPath &&
+				(!previewLocation?.parentId || persistedParentLocation?.node.kind === "folder")
 			) {
-				void movePersistedFolder(draggedLocation.node.id, persistedParentId);
+				void movePersistedFolder(
+					draggedFolderPath,
+					persistedParentFolderPath,
+					draggedLocation.node.id,
+					persistedParentLocation?.node.kind === "folder" ? persistedParentLocation.node.id : null,
+					targetIndex,
+				);
 			} else {
 				setWorkspaceTreeNodes((current) =>
 					moveTreeNode(current, nextDragState.draggedNodeId, nextDragState.dropTarget as WorkspaceDragTarget, workspaceTreeAdapter),
@@ -598,6 +627,11 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		setPendingFolderRenameName(label);
 	};
 
+	const resolveFolderPath = (folderId: string): string | null => {
+		const location = findTreeNodeLocation(workspaceTreeNodes(), folderId, workspaceTreeAdapter);
+		return location?.node.kind === "folder" ? location.node.path ?? null : null;
+	};
+
 	const submitPendingFolder = async (): Promise<void> => {
 		const name = pendingFolderName().trim();
 		const draft = pendingFolderDraft();
@@ -618,6 +652,12 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
+		const parentFolderPath = draft.parentId ? resolveFolderPath(draft.parentId) : null;
+		if (draft.parentId && !parentFolderPath) {
+			cancelPendingFolder();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
 				method: "POST",
@@ -627,7 +667,7 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 				},
 				body: JSON.stringify({
 					name,
-					parentFolderId: draft.parentId,
+					parentFolderId: parentFolderPath,
 				}),
 			});
 
@@ -647,13 +687,17 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 
 	const deletePersistedFolder = async (folderId: string): Promise<void> => {
 		const projectId = activeProject()?.id ?? "";
+		const folderPath = resolveFolderPath(folderId);
 		if (!folderId || !projectId || !isUuidString(projectId)) {
 			return;
 		}
+		if (!folderPath) {
+			return;
+		}
 
 		try {
 			const response = await fetch(
-				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderId)}`,
+				`${resolveAPIBase()}/projects/${projectId}/tree/folders?folderId=${encodeURIComponent(folderPath)}`,
 				{
 					method: "DELETE",
 					headers: {
@@ -675,9 +719,15 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 		}
 	};
 
-	const movePersistedFolder = async (folderId: string, parentFolderId: string | null): Promise<void> => {
+	const movePersistedFolder = async (
+		folderPath: string,
+		parentFolderPath: string | null,
+		folderStableId: string,
+		parentStableId: string | null,
+		targetIndex: number,
+	): Promise<void> => {
 		const projectId = activeProject()?.id ?? "";
-		if (!folderId || !projectId || !isUuidString(projectId)) {
+		if (!folderPath || !folderStableId || !projectId || !isUuidString(projectId)) {
 			return;
 		}
 
@@ -689,8 +739,11 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId,
-					parentFolderId,
+					folderId: folderPath,
+					folderNodeId: folderStableId,
+					parentFolderId: parentFolderPath,
+					parentNodeId: parentStableId,
+					targetIndex,
 				}),
 			});
 
@@ -701,14 +754,6 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			}
 
 			setPersistedFolders(readPersistedWorkspaceFolders(body));
-
-			const previousFolderId = body.data?.previousFolderId;
-			const movedFolderId = body.data?.movedFolder?.id;
-			if (previousFolderId && movedFolderId && previousFolderId !== movedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? movedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}
@@ -734,6 +779,12 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			return;
 		}
 
+		const folderPath = resolveFolderPath(draft.folderId);
+		if (!folderPath) {
+			cancelPendingFolderRename();
+			return;
+		}
+
 		try {
 			const response = await fetch(`${resolveAPIBase()}/projects/${projectId}/tree/folders`, {
 				method: "PATCH",
@@ -742,7 +793,7 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 					"Content-Type": "application/json",
 				},
 				body: JSON.stringify({
-					folderId: draft.folderId,
+					folderId: folderPath,
 					name,
 				}),
 			});
@@ -756,14 +807,6 @@ export const WorkspaceSidebar = (props: WorkspaceSidebarProps): JSX.Element => {
 			setPersistedFolders(readPersistedWorkspaceFolders(body));
 			setPendingFolderRename(null);
 			setPendingFolderRenameName("");
-
-			const previousFolderId = body.data?.previousFolderId;
-			const renamedFolderId = body.data?.renamedFolder?.id;
-			if (previousFolderId && renamedFolderId && previousFolderId !== renamedFolderId) {
-				setCollapsedFolderIds((current) =>
-					current.map((id) => (id === previousFolderId ? renamedFolderId : id)),
-				);
-			}
 		} catch (error) {
 			console.error(error);
 		}

Frontend/src/components/shell/data/app-shell.context.tsx

@@ -40,6 +40,8 @@ type AppShellInstallation = {
 	protocol: string;
 	host: string;
 	isBootstrapped: boolean;
+	materializationStatus: "not_started" | "pending" | "running" | "succeeded" | "failed" | string;
+	materializationError?: string;
 };
 
 type AppShellAdmin = {
@@ -101,8 +103,29 @@ type AppShellPayload = {
 	workspaces: AppShellWorkspace[];
 };
 
+const normalizeInstallation = (
+	installation: AppShellInstallation | null | undefined,
+): AppShellInstallation | undefined => {
+	if (!installation) {
+		return undefined;
+	}
+
+	const materializationStatus = installation.materializationStatus?.trim()
+		? installation.materializationStatus
+		: installation.isBootstrapped
+			? "succeeded"
+			: "not_started";
+	const materializationError = installation.materializationError?.trim() || undefined;
+
+	return {
+		...installation,
+		materializationStatus,
+		materializationError,
+	};
+};
+
 const normalizeAppShellPayload = (payload: AppShellPayload | null | undefined): AppShellPayload => ({
-	installation: payload?.installation,
+	installation: normalizeInstallation(payload?.installation),
 	admin: payload?.admin,
 	organizations: Array.isArray(payload?.organizations) ? payload.organizations : [],
 	departments: Array.isArray(payload?.departments) ? payload.departments : [],

Frontend/src/components/shell/data/shell.data.ts

@@ -129,6 +129,7 @@ export type WorkspaceStaticItem = SidebarItem & {
 
 export type WorkspaceFolderNode = {
 	id: string;
+	path?: string;
 	label: string;
 	kind: "folder";
 	icon: ShellIcon;

Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.module.scss

@@ -92,6 +92,21 @@
   flex-wrap: wrap;
 }
 
+.heroStatus {
+	display: grid;
+	gap: var(--space-2);
+	justify-items: start;
+}
+
+.heroStatusMessage {
+	max-width: 64ch;
+	color: var(--color-text-muted);
+}
+
+.heroStatusMessage[data-status="failed"] {
+	color: var(--color-danger-text, var(--color-text));
+}
+
 .title {
   @include text-display;
   font-family: var(--font-family-display);
@@ -194,6 +209,19 @@
   background: color-mix(in srgb, var(--color-success-surface, var(--color-surface-secondary)) 80%, transparent);
 }
 
+.statusBadge[data-status="pending"],
+.statusBadge[data-status="running"] {
+	color: var(--bootstrap-accent);
+	border-color: color-mix(in srgb, var(--bootstrap-accent) 38%, transparent);
+	background: color-mix(in srgb, var(--bootstrap-accent) 10%, var(--color-surface-secondary));
+}
+
+.statusBadge[data-status="failed"] {
+	color: var(--color-danger-text, var(--color-text));
+	border-color: color-mix(in srgb, var(--color-danger-border, var(--color-border)) 68%, transparent);
+	background: color-mix(in srgb, var(--color-danger-surface, var(--color-surface-secondary)) 80%, transparent);
+}
+
 .statusBadge[data-status="error"] {
   color: var(--color-danger-text, var(--color-text));
   border-color: color-mix(in srgb, var(--color-danger-border, var(--color-border)) 68%, transparent);

Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx

@@ -1,6 +1,6 @@
 // Path: Frontend/src/components/workspace-home/WorkspaceHome/WorkspaceHome.tsx
 
-import { For, Show, createEffect, createMemo, createSignal, type JSX } from "solid-js";
+import { For, Show, createEffect, createMemo, createSignal, onCleanup, type JSX } from "solid-js";
 import { Portal } from "solid-js/web";
 import { createStore } from "solid-js/store";
 import { resolveAPIBase } from "../../../lib/api";
@@ -21,6 +21,31 @@ type BootstrapSubmissionState = {
 	error: string;
 };
 
+type InstanceForm = {
+	protocol: "http" | "https";
+	access: "local" | "remote";
+	host: string;
+};
+
+type ModeForm = {
+	mode: "personal" | "organizational";
+	name: string;
+};
+
+type AdminForm = {
+	displayName: string;
+	email: string;
+	password: string;
+};
+
+type StructureForm = {
+	departmentName: string;
+	teamName: string;
+	projectName: string;
+};
+
+type MaterializationState = "not_started" | "pending" | "running" | "succeeded" | "failed";
+
 const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	{
 		id: "instance",
@@ -44,43 +69,45 @@ const bootstrapStepDefinitions: readonly BootstrapStepDefinition[] = [
 	},
 ];
 
-const defaultInstanceForm = {
+const defaultInstanceForm: InstanceForm = {
 	protocol: "http",
 	access: "local",
 	host: "localhost",
-} as const;
+};
 
-const defaultModeForm = {
+const defaultModeForm: ModeForm = {
 	mode: "personal",
 	name: "",
-} as const;
+};
 
-const defaultAdminForm = {
+const defaultAdminForm: AdminForm = {
 	displayName: "Admin",
 	email: "admin@example.com",
 	password: "",
-} as const;
+};
 
 const personalStructureDefaults = {
 	departmentName: "Default",
 	teamName: "Personal",
-} as const;
+};
 
 const organizationalStructureDefaults = {
 	departmentName: "Department",
 	teamName: "Team",
-} as const;
+};
 
-const defaultStructureForm = {
+const defaultStructureForm: StructureForm = {
 	...personalStructureDefaults,
 	projectName: "Project",
-} as const;
+};
 
 const initialSubmissionState = (): BootstrapSubmissionState => ({
 	status: "idle",
 	error: "",
 });
 
+const materializationPollIntervalMs = 2000;
+
 const readResponseBody = async (response: Response): Promise<unknown> => {
 	const raw = await response.text();
 
@@ -148,10 +175,10 @@ type WorkspaceHomeProps = {
 
 export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const appShellData = useAppShellData();
-	const [instanceForm, setInstanceForm] = createStore({ ...defaultInstanceForm });
-	const [modeForm, setModeForm] = createStore({ ...defaultModeForm });
-	const [adminForm, setAdminForm] = createStore({ ...defaultAdminForm });
-	const [structureForm, setStructureForm] = createStore({ ...defaultStructureForm });
+	const [instanceForm, setInstanceForm] = createStore<InstanceForm>({ ...defaultInstanceForm });
+	const [modeForm, setModeForm] = createStore<ModeForm>({ ...defaultModeForm });
+	const [adminForm, setAdminForm] = createStore<AdminForm>({ ...defaultAdminForm });
+	const [structureForm, setStructureForm] = createStore<StructureForm>({ ...defaultStructureForm });
 	const [stepState, setStepState] = createStore<Record<BootstrapStepKey, BootstrapSubmissionState>>({
 		instance: initialSubmissionState(),
 		mode: initialSubmissionState(),
@@ -162,6 +189,51 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const [isBootstrapComplete, setIsBootstrapComplete] = createSignal(false);
 	const [isWizardOpen, setIsWizardOpen] = createSignal(false);
 	const [currentStepIndex, setCurrentStepIndex] = createSignal(0);
+	const installation = createMemo(() => appShellData.installation());
+	const materializationState = createMemo<MaterializationState>(() => {
+		const status = installation()?.materializationStatus;
+
+		switch (status) {
+			case "pending":
+			case "running":
+			case "failed":
+			case "succeeded":
+			case "not_started":
+				return status;
+			default:
+				return installation()?.isBootstrapped ? "succeeded" : "not_started";
+		}
+	});
+	const isBootstrapPersisted = createMemo(() => installation()?.isBootstrapped ?? false);
+	const isMaterializationInFlight = createMemo(
+		() => materializationState() === "pending" || materializationState() === "running",
+	);
+	const hasMaterializationFailed = createMemo(() => materializationState() === "failed");
+	const materializationStatusLabel = createMemo(() => {
+		switch (materializationState()) {
+			case "pending":
+				return "Materialization queued";
+			case "running":
+				return "Materialization running";
+			case "failed":
+				return "Materialization failed";
+			case "succeeded":
+				return "Ready";
+			default:
+				return "Not started";
+		}
+	});
+	const materializationMessage = createMemo(() => {
+		if (isMaterializationInFlight()) {
+			return "Your bootstrap is saved. The worker is still creating the POSIX skeleton and rebuilding the app shell index.";
+		}
+
+		if (hasMaterializationFailed()) {
+			return installation()?.materializationError || "Bootstrap saved, but background materialization did not finish cleanly.";
+		}
+
+		return "";
+	});
 
 	createEffect(() => {
 		if (modeForm.mode === "personal") {
@@ -190,19 +262,51 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 			return;
 		}
 
-		const installationAccessor = appShellData.installation;
-		const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
-		const isPersistedBootstrap = installation?.isBootstrapped ?? false;
-
-		if (!isPersistedBootstrap) {
+		if (!isBootstrapPersisted()) {
 			resetWizardState();
 		}
 
-		setIsBootstrapComplete(isPersistedBootstrap);
-		setIsWizardOpen(!isPersistedBootstrap);
+		setIsBootstrapComplete(isBootstrapPersisted() && !isMaterializationInFlight());
+		setIsWizardOpen(!isBootstrapPersisted());
 		setIsBootstrapStateResolved(true);
 	});
 
+	createEffect(() => {
+		if (!isBootstrapPersisted() || !isMaterializationInFlight()) {
+			return;
+		}
+
+		let cancelled = false;
+		let timeoutId: number | undefined;
+
+		const scheduleReload = (): void => {
+			timeoutId = window.setTimeout(async () => {
+				if (cancelled) {
+					return;
+				}
+
+				// The final bootstrap step only persists relational state. Poll while the
+				// worker is materializing the POSIX skeleton so the page can transition from
+				// queued/running to ready/failed without a manual refresh.
+				await appShellData.reload();
+
+				if (!cancelled && isBootstrapPersisted() && isMaterializationInFlight()) {
+					scheduleReload();
+				}
+			}, materializationPollIntervalMs);
+		};
+
+		scheduleReload();
+
+		onCleanup(() => {
+			cancelled = true;
+
+			if (timeoutId !== undefined) {
+				window.clearTimeout(timeoutId);
+			}
+		});
+	});
+
 	const sidebarToggleLabel = (): string =>
 		props.sidebarCollapsed ? "Expand left workspace sidebar" : "Collapse left workspace sidebar";
 	const breadcrumb = (): string => `${appShellData.activeServer().name} / ${appShellData.activeProject().name} / Home`;
@@ -217,7 +321,7 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 	const currentStepState = createMemo<BootstrapSubmissionState>(() => stepState[currentStep().id]);
 	const isFirstStep = (): boolean => currentStepIndex() === 0;
 	const isLastStep = (): boolean => currentStepIndex() === bootstrapStepDefinitions.length - 1;
-	const canDismissWizard = (): boolean => isBootstrapComplete();
+	const canDismissWizard = (): boolean => isBootstrapPersisted();
 
 	const resetWizardState = (): void => {
 		setInstanceForm({ ...defaultInstanceForm });
@@ -290,12 +394,9 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 
 		if (isLastStep()) {
 			await appShellData.reload();
-			const installationAccessor = appShellData.installation;
-			const installation = typeof installationAccessor === "function" ? installationAccessor() : undefined;
-			const isPersistedBootstrap = installation?.isBootstrapped ?? false;
 
-			setIsBootstrapComplete(isPersistedBootstrap);
-			setIsWizardOpen(!isPersistedBootstrap);
+			setIsBootstrapComplete(isBootstrapPersisted() && !isMaterializationInFlight());
+			setIsWizardOpen(!isBootstrapPersisted());
 			setIsBootstrapStateResolved(true);
 			return;
 		}
@@ -360,14 +461,33 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 				</div>
 
 				<section class={styles.hero} data-slot="workspace-home-hero">
-					<h1 class={styles.title}>{isBootstrapComplete() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
-					<Show when={isBootstrapStateResolved() && !isBootstrapComplete()}>
-						<div class={styles.heroActions}>
-							<button type="button" class={styles.primaryButton} onClick={(): void => setIsWizardOpen(true)}>
-								Open bootstrap wizard
-							</button>
+					<h1 class={styles.title}>{isBootstrapPersisted() ? appShellData.activeServer().name : bootstrapTargetLabel()}</h1>
+					<Show when={isBootstrapStateResolved() && isBootstrapPersisted() && materializationState() !== "succeeded"}>
+						<div class={styles.heroStatus}>
+							<div class={styles.statusBadge} data-status={materializationState()}>
+								{materializationStatusLabel()}
+							</div>
+							<Show when={materializationMessage()}>
+								<p class={styles.heroStatusMessage} data-status={materializationState()}>
+									{materializationMessage()}
+								</p>
+							</Show>
 						</div>
-					</Show>
+				</Show>
+				<Show when={isBootstrapStateResolved() && !isBootstrapComplete()}>
+					<div class={styles.heroActions}>
+						<button
+							type="button"
+							class={styles.primaryButton}
+							disabled={isBootstrapPersisted()}
+							onClick={(): void => {
+								setIsWizardOpen(true);
+							}}
+						>
+							{isBootstrapPersisted() ? "Bootstrap saved" : "Open bootstrap wizard"}
+						</button>
+					</div>
+				</Show>
 				</section>
 			</main>
 
@@ -384,7 +504,13 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 									</h2>
 								</div>
 								<Show when={canDismissWizard()}>
-									<button type="button" class={styles.wizardCloseButton} onClick={(): void => setIsWizardOpen(false)}>
+									<button
+										type="button"
+										class={styles.wizardCloseButton}
+										onClick={(): void => {
+											setIsWizardOpen(false);
+										}}
+									>
 										Close
 									</button>
 								</Show>
@@ -421,26 +547,38 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 
 								<div class={styles.wizardStepPanel} data-slot="bootstrap-wizard-step-panel">
 									<div class={styles.sectionHeader}>
-										<div>
-											<span class={styles.wizardStepEyebrow}>{`Step ${currentStepIndex() + 1} of ${bootstrapStepDefinitions.length}`}</span>
-											<h3 class={styles.sectionTitle}>{currentStep().title}</h3>
-										</div>
-					<div class={styles.statusBadge} data-status={currentStepState().status}>{statusLabel(currentStepState())}</div>
-				</div>
+								<div>
+									<span class={styles.wizardStepEyebrow}>{`Step ${currentStepIndex() + 1} of ${bootstrapStepDefinitions.length}`}</span>
+									<h3 class={styles.sectionTitle}>{currentStep().title}</h3>
+								</div>
+								<div class={styles.statusBadge} data-status={currentStepState().status}>
+									{statusLabel(currentStepState())}
+								</div>
+							</div>
 
 									<form class={styles.form} onSubmit={handleCurrentStepSubmit}>
 										<Show when={currentStep().id === "instance"}>
 											<>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Protocol</span>
-													<select value={instanceForm.protocol} onInput={(event): void => setInstanceForm("protocol", event.currentTarget.value)}>
+												<select
+													value={instanceForm.protocol}
+													onInput={(event): void =>
+														setInstanceForm("protocol", event.currentTarget.value as InstanceForm["protocol"])
+													}
+												>
 														<option value="http">http</option>
 														<option value="https">https</option>
 													</select>
 												</label>
 												<label class={styles.field}>
 													<span class={styles.fieldLabel}>Access</span>
-													<select value={instanceForm.access} onInput={(event): void => setInstanceForm("access", event.currentTarget.value)}>
+												<select
+													value={instanceForm.access}
+													onInput={(event): void =>
+														setInstanceForm("access", event.currentTarget.value as InstanceForm["access"])
+													}
+												>
 														<option value="local">local</option>
 														<option value="remote">remote</option>
 													</select>
@@ -461,7 +599,10 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 							<>
 								<label class={styles.field}>
 									<span class={styles.fieldLabel}>Mode</span>
-									<select value={modeForm.mode} onInput={(event): void => setModeForm("mode", event.currentTarget.value)}>
+								<select
+									value={modeForm.mode}
+									onInput={(event): void => setModeForm("mode", event.currentTarget.value as ModeForm["mode"])}
+								>
 										<option value="personal">personal</option>
 										<option value="organizational">organizational</option>
 									</select>
@@ -553,7 +694,9 @@ export const WorkspaceHome = (props: WorkspaceHomeProps): JSX.Element => {
 												type="button"
 												class={styles.secondaryButton}
 												disabled={isFirstStep()}
-												onClick={(): void => setCurrentStepIndex((index) => Math.max(index - 1, 0))}
+												onClick={(): void => {
+													setCurrentStepIndex((index) => Math.max(index - 1, 0));
+												}}
 											>
 												Back
 											</button>