clean up and standardize types across the codebase, unify atomic operations, improve UTF-8 handling throughout the system, remove obsolete input and named queue interfaces, redesign process preparation and creation, tighten IPC and service boundaries, improve error handling and reliability, minor documentation cleanup, fix doom surfaces, fix panic in ini parsing.

code/public/ntlite/process_loader.h

@@ -13,7 +13,7 @@
 #define NTL_PROCESS_LOAD_FLAG_NONE 0x00000000u
 #define NTL_PROCESS_STARTUP_DATA_MAX 1024u
 
-// Generic userspace process vectors. The builder copies every view into the
+// Generic userspace process vectors. The loader copies every view into the
 // child loader block; callers retain ownership of the source arrays/strings.
 typedef struct NTL_PROCESS_STRING_VECTOR {
     const SYS_STRING_VIEW* Entries;
@@ -28,16 +28,13 @@ typedef struct NTL_PROCESS_STARTUP_CAPABILITY {
     uint32_t DuplicateFlags;
 } NTL_PROCESS_STARTUP_CAPABILITY;
 
-// Reusable inert-process builder used by policy services such as posixsrv.
-// The storage is opaque to callers; initialize it to zero before first use.
-#define NTL_PROCESS_BUILDER_OPAQUE_WORDS 160u
-typedef struct NTL_PROCESS_BUILDER {
-    uintptr_t Opaque[NTL_PROCESS_BUILDER_OPAQUE_WORDS];
-} NTL_PROCESS_BUILDER;
+// Opaque preparation owned by the userspace process loader. A successful
+// prepare returns one allocation consumed by Start or Abort; never copy it.
+typedef struct NTL_PROCESS_PREPARATION NTL_PROCESS_PREPARATION;
 
 // Describes construction of an inert child. Unlike NTL_CREATE_PROCESS_AT_REQUEST,
 // preparation does not start the process and therefore has no output handle field.
-typedef struct NTL_PROCESS_BUILDER_REQUEST {
+typedef struct NTL_PREPARE_PROCESS_REQUEST {
     uint32_t Size;
     uint32_t Flags;
     SYS_HANDLE RootHandle;
@@ -55,7 +52,7 @@ typedef struct NTL_PROCESS_BUILDER_REQUEST {
     NTL_PROCESS_STRING_VECTOR Environment;
     const void* StartupData;
     size_t StartupDataSize;
-} NTL_PROCESS_BUILDER_REQUEST;
+} NTL_PREPARE_PROCESS_REQUEST;
 
 // Creates and starts one PE32+ process entirely through the userspace image loader.
 typedef struct NTL_CREATE_PROCESS_AT_REQUEST {
@@ -113,25 +110,28 @@ typedef struct NTL_CREATE_SYSTEM_PROCESS_REQUEST {
 #define NTL_PROCESS_LOADER_API
 #endif
 
-// Prepares an inert child and materializes its image/dependencies/bootstrap data.
-// imageFile may be SYS_HANDLE_INVALID to open request->Path relative to RootHandle.
-NTL_PROCESS_LOADER_API KSTATUS NtlProcessBuilderPrepare(NTL_PROCESS_BUILDER* builder,
-                                                        const NTL_PROCESS_BUILDER_REQUEST* request,
-                                                        SYS_HANDLE imageFile);
-// Returns the prepared process capability without transferring ownership from the builder.
-// The borrowed handle remains valid only until Start or Abort consumes the builder.
-NTL_PROCESS_LOADER_API KSTATUS NtlProcessBuilderGetProcessHandle(NTL_PROCESS_BUILDER* builder,
-                                                                 SYS_HANDLE* processHandleOut);
-// Starts a prepared child and returns the retained process capability to the caller.
-// On success the builder is consumed and reset to the empty state.
-NTL_PROCESS_LOADER_API KSTATUS NtlProcessBuilderStart(NTL_PROCESS_BUILDER* builder,
-                                                      SYS_HANDLE* processHandleOut);
-// Aborts a prepared child, terminating the inert native process and releasing loader state.
-NTL_PROCESS_LOADER_API void NtlProcessBuilderAbort(NTL_PROCESS_BUILDER* builder);
+// Allocates and prepares an inert child, including image, dependencies, inherited
+// capabilities, and bootstrap data. On failure *preparationOut is NULL and no
+// prepared process or child handle is retained. imageFile may be invalid to
+// open request->Path relative to RootHandle.
+NTL_PROCESS_LOADER_API KSTATUS NtlPrepareProcess(const NTL_PREPARE_PROCESS_REQUEST* request,
+                                                 SYS_HANDLE imageFile,
+                                                 NTL_PROCESS_PREPARATION** preparationOut);
+// Borrows the native process capability without transferring ownership. This
+// handle must not be closed by the caller and is valid only until Start/Abort.
+NTL_PROCESS_LOADER_API KSTATUS NtlPreparedProcessGetHandle(
+    const NTL_PROCESS_PREPARATION* preparation, SYS_HANDLE* processHandleOut);
+// Consumes one valid preparation on both success and ordinary start failure.
+// On success returns the caller-owned native process capability. On failure
+// the inert child is discarded and *processHandleOut is invalid.
+NTL_PROCESS_LOADER_API KSTATUS NtlStartPreparedProcess(
+    NTL_PROCESS_PREPARATION* preparation, SYS_HANDLE* processHandleOut);
+// Consumes one prepared child without starting it. NULL is accepted.
+NTL_PROCESS_LOADER_API void NtlAbortPreparedProcess(NTL_PROCESS_PREPARATION* preparation);
 
 NTL_PROCESS_LOADER_API KSTATUS NtlCreateProcessAt(const NTL_CREATE_PROCESS_AT_REQUEST* request);
 NTL_PROCESS_LOADER_API KSTATUS NtlCreateSystemProcess(const NTL_CREATE_SYSTEM_PROCESS_REQUEST* request);
-// Copies the optional opaque startup data supplied by the userspace process builder.
+// Copies the optional opaque startup data supplied at process construction.
 NTL_PROCESS_LOADER_API KSTATUS NtlGetProcessStartupData(void* buffer,
                                                         size_t bufferSize,
                                                         size_t* sizeOut);