fix: stale slot indices, cascade OOB, pending over-alloc, collect_dependents bounds, size_t format on Windows

- stk_poll: unify load loops to always append on compacted array, removing stale pre-compaction slot indices
- stk_poll: heap-allocate cascade_indices per iteration, removing fixed 256-slot stack bound
- stk_pending_retry: shrink module array to actual count after retry loop completes
- stk_collect_dependents: add capacity parameter and bounds guard before index write
- stk_log_modules: cast module_count to unsigned long for C89 portable %lu on Windows

CHANGELOG.md

@@ -7,7 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.1.1] - 2026-02-15
+## [1.0.0-pre.8] - 2026-03-08
+
+### Fixed
+- `stk_poll()`: stale index corruption when simultaneous load and unload events occurred in the same poll cycle. New modules were previously loaded into pre-compaction slot indices; they now always append to the compacted array via `module_count + successful_appends`, matching the `append_modules` path. The two load loops have been unified into one.
+- `stk_poll()`: `cascade_indices` was a fixed-size stack array of `STK_PATH_MAX` (256) elements with no bounds check. It is now heap-allocated to `module_count` entries per iteration, eliminating the silent overflow risk.
+- `stk_pending_retry()`: module array was pre-allocated to `module_count + stk_pending_count` but never shrunk when fewer entries loaded than were pending. Now calls `stk_module_realloc_memory(module_count)` after the retry loop completes.
+- `stk_collect_dependents()`: missing bounds guard on the `indices` write: `(*count)++` had no check against the buffer capacity before writing. Added `capacity` parameter (passed as `module_count` from the call site) and a guard that skips the write if the capacity is reached, preventing a silent overflow.
+- `stk_log_modules()`: `%lu` format specifier used with `size_t` is undefined behaviour on platforms where `unsigned long` is narrower than `size_t` (e.g. MSVC 64-bit). Fixed with an explicit `(unsigned long)` cast, preserving C89 compatibility.
+
+## [1.0.0-pre.7] - 2026-03-07
+
+### Fixed
+- `stk_module_load()`: added missing dependency failure logging when a module is deferred to the pending queue.
+
+## [1.0.0-pre.6] - 2026-03-07
+
+### Changed
+- `stk_poll()`: replaced per-module `stk_pending_add()` calls inside the load holes and `append_modules` loops with batch collection followed by a single `stk_pending_add_batch()` call after both loops complete.
+
+## [1.0.0-pre.5] - 2026-03-07
+
+### Changed
+- `stk_init()`: replaced per-module `stk_pending_add()` calls inside the deferred module loop with batch collection followed by a single `stk_pending_add_batch()` call after the loop.
+
+## [1.0.0-pre.4] - 2026-03-07
+
+### Changed
+- `stk_pending_retry()`: replaced per-module `realloc` at `attempt_load` with a single bulk allocation upfront (`module_count + stk_pending_count`) before the retry loop.
+- `stk_poll()`: replaced per-module `stk_pending_add()` calls inside the unload and cascade loops with batch collection followed by a single `stk_pending_add_batch()` call after each loop.
+
+## [1.0.0-pre.3] - 2026-03-07
+
+### Added
+- `STK_MOD_DEP_LOG_BUFFER` (2048) added to `stk.h`
+
+### Changed
+- Dependency failure logging now emits a single line per module listing all unmet deps with their reason: `not found` or `requires <constraint>, have <version>`
+  - `Deferring 'test_mod_dep': unmet deps: test_mod (not found)`
+  - `Unloading 'test_mod_dep': unmet deps: test_mod (not found), renderer (requires ^2.0.0, have 1.3.0)`
+- Silent defer at `stk_init` and vague `"unmet dependencies"` cascade log in `stk_poll` replaced with `stk_log_dependency_failures()`
+- Kahn topological sort refactored into generic `stk_kahn_sort()` accepting a `has_dep` callback and an `on_cycle` callback, decoupling it from `stk_modules`. `stk_topo_sort()` is now a thin wrapper. `stk_sort_load_order()` uses the same core via `stk_batch_has_dep()`, inspecting tmp files so simultaneous load events are processed dependency-first without a retry cycle
+- `stk_module_load()` split into `stk_module_preload()`, `stk_module_activate()`, `stk_module_discard()`, and `stk_validate_dependencies_single()`. Init is not called if deps are unmet
+- On UNLOAD events in `stk_poll()`, the unload set is expanded to include all transitively dependent modules via `stk_collect_dependents()`, sorted dependents-first via `stk_sort_unload_order()`. Modules unloaded due to expansion are queued to pending
+- On LOAD events with unmet dependencies, the tmp path is added to the pending queue instead of being dropped
+- `stk_pending_retry()` now skips already-loaded entries and prunes entries whose file no longer exists
+- `free_poll` label moved above `stk_pending_retry()` so retry always runs regardless of exit path
+
+## [1.0.0-pre.2] - 2026-03-06
+
+### Fixed
+- Module `init` is no longer called if dependencies are not satisfied. The library handle is unloaded and a dep error is returned. 
+
+## [1.0.0-pre.1] - 2026-03-06
+
+### Added
+- **Dependency System**: Full module dependency declaration and resolution
+  - Modules declare dependencies via an exported `stk_mod_deps` symbol, no stk headers required in modules, only the memory layout contract must be respected (`{ char[64], char[32] }` sentinel-terminated array)
+  - Version constraint operators: `=` (exact), `>=` (minimum, default), `^` (compatible — same major, greater or equal minor/patch)
+  - Version defaults to `0.0.0` if not provided or unparseable
+  - Dependency validation on `stk_init` and every `stk_poll` cycle
+  - Topological sort with cycle detection, load and unload ordering enforced
+  - All dependency failures logged before returning
+- **Cascade Unload**: When a module is removed, all dependents cascade unload automatically and are added to the pending queue. Cascades repeat until the loaded set is stable
+- **Pending Queue**: Modules that fail dependency validation are deferred. When their dependencies become available they are retried and loaded automatically. Entries are removed if their file is deleted
+
+### Changed
+- `stk_set_module_dependencies_fn` renamed to `stk_set_module_deps_sym`. Deps are now an exported array symbol, not a function
+- Default deps symbol name changed from `stk_mod_dependencies` to `stk_mod_deps`
+- `stk_dep_t` added to public header `stk.h`
+- `stk_mod_t` field order changed to largest-to-smallest for correct memory alignment with zero padding waste
+- Dependency validation failure during `stk_init` no longer fatal, affected modules are deferred to the pending queue
+- Poll cycle now logs the full loaded module list as a single summary after any event that changes the loaded set, instead of logging each module individually
+
+### Notes
+- This release marks Phase 1 complete: hot-reloading foundation with dependency management
+- Memory layout contract for `stk_mod_deps`: sentinel-terminated array of `{ char[64], char[32] }`. Modules do not need to include `stk.h`, define the struct inline or via your engine's own header as long as the layout matches
+
+## [0.1.3] - 2026-02-25
+
+### Added
+- **Module Metadata**: Optional metadata support for modules
+  - `stk_mod_name` - human-readable module name
+  - `stk_mod_version` - semantic version string
+  - `stk_mod_description` - module description
+  - All three are optional, missing symbols are not errors
+  - Metadata stored in tight-packed arrays with index mappings
+  - Setter functions to override default symbol names before `stk_init()`
+
+## [0.1.2] - 2026-02-15
+
+### Fixed
+- **Windows**
+    - Module reload now works correctly, idk how it was broken
+    - Temp directory creation fixed
+    - `.tmp` directory now hidden via FILE_ATTRIBUTE_HIDDEN
+    - Test build fixed
+        - Force cmd.exe shell in gmake.mk
+        - Fix bash syntax errors when running build.bat
+- **All Platforms**: platform_mkdir now checks if directory exists before creating
+
+## [0.1.1] - 2026-02-14
 
 ### Fixed
 - **Logging**: Corrected log level severity order in enum
@@ -15,7 +115,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Fixes filtering logic where ERROR/WARN were incorrectly blocked
   - Default INFO level now properly shows INFO, WARN, and ERROR while filtering DEBUG
 
-## [0.1.0] - 2026-02-15
+## [0.1.0] - 2026-02-14
 
 ### Fixed
 - **C89 Compliance**: Removed stdint.h dependency (C99 feature)
@@ -92,7 +192,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Dependency management and versioning not yet implemented
 - API is unstable and subject to change in future releases
 
-[Unreleased]: https://github.com/anth64/stk/compare/v0.1.1...HEAD
+[Unreleased]: https://github.com/anth64/stk/compare/v1.0.0-pre.8...HEAD
+[1.0.0-pre.8]: https://github.com/anth64/stk/compare/v1.0.0-pre.7...v1.0.0-pre.8
+[1.0.0-pre.7]: https://github.com/anth64/stk/compare/v1.0.0-pre.6...v1.0.0-pre.7
+[1.0.0-pre.6]: https://github.com/anth64/stk/compare/v1.0.0-pre.5...v1.0.0-pre.6
+[1.0.0-pre.5]: https://github.com/anth64/stk/compare/v1.0.0-pre.4...v1.0.0-pre.5
+[1.0.0-pre.4]: https://github.com/anth64/stk/compare/v1.0.0-pre.3...v1.0.0-pre.4
+[1.0.0-pre.3]: https://github.com/anth64/stk/compare/v1.0.0-pre.2...v1.0.0-pre.3
+[1.0.0-pre.2]: https://github.com/anth64/stk/compare/v1.0.0-pre.1...v1.0.0-pre.2
+[1.0.0-pre.1]: https://github.com/anth64/stk/compare/v0.1.3...v1.0.0-pre.1
+[0.1.3]: https://github.com/anth64/stk/releases/tag/v0.1.3
+[0.1.2]: https://github.com/anth64/stk/releases/tag/v0.1.2
+[0.1.1]: https://github.com/anth64/stk/releases/tag/v0.1.1
 [0.1.1]: https://github.com/anth64/stk/releases/tag/v0.1.1
 [0.1.0]: https://github.com/anth64/stk/releases/tag/v0.1.0
 [0.0.4]: https://github.com/anth64/stk/releases/tag/v0.0.4

README.md

@@ -14,7 +14,7 @@ It is designed to run on modern systems running POSIX and Windows using C89.
 - **Hot-swapping** of modules at runtime
 - **Cross-platform** (Linux, BSD, Windows, macOS)
 - **Optional WASM support** for multi-language modules (planned)
-- **Developer tools**: lightweight metadata, logging/tracing, and dependency management (in progress)
+- **Developer tools**: lightweight metadata, logging/tracing, and dependency management
 - **Minimal, portable API**
 
 ---
@@ -131,6 +131,42 @@ cc -shared -o my_module.dll my_module.c
 
 Place the compiled module in the `mods/` directory (default), and `stk` will automatically load it and watch for changes.
 
+### Module Metadata
+
+Modules can optionally export metadata functions:
+
+```c
+const char *stk_mod_name(void)        { return "My Module"; }
+const char *stk_mod_version(void)     { return "1.2.0"; }
+const char *stk_mod_description(void) { return "Does something useful"; }
+```
+
+All three are optional. Version defaults to `0.0.0` if not exported or unparseable.
+
+### Declaring Dependencies
+
+Modules declare dependencies via an exported sentinel-terminated array. No stk headers are required in the module. The only requirement is that the memory layout matches: `{ char[64], char[32] }`.
+
+```c
+typedef struct {
+    char id[64];
+    char version[32];
+} dep_t;
+
+dep_t stk_mod_deps[] = {
+    { "physics", ">=2.0.0" },
+    { "renderer", "^1.0.0" },
+    { "", "" }  /* sentinel */
+};
+```
+
+Version constraint operators:
+- `=1.0.0` exact match
+- `>=2.0.0` minimum version, also the default if no operator is specified
+- `^1.0.0` same major, greater or equal minor/patch
+
+If a dependency is removed at runtime, all affected modules are unloaded and queued. When the dependency comes back, they load automatically.
+
 ### Configuration
 
 ```c
@@ -146,6 +182,18 @@ stk_set_module_init_fn("my_init");
 /* Set custom shutdown function name (default: "stk_mod_shutdown") */
 stk_set_module_shutdown_fn("my_shutdown");
 
+/* Set function name to get module name (default: "stk_mod_name") */
+stk_set_module_name_fn("my_mod_name");
+
+/* Set function name to get module version (default: "stk_mod_version") */
+stk_set_module_version_fn("my_mod_version");
+
+/* Set function name to get module description (default: "stk_mod_description") */
+stk_set_module_description_fn("my_mod_description");
+
+/* Set deps array symbol name (default: "stk_mod_deps") */
+stk_set_module_deps_sym("my_mod_deps");
+
 /*
  * All the above functions must be called before stk_init()
  * if the defaults need to be changed.
@@ -168,6 +216,10 @@ stk_init();
 - `void stk_set_tmp_dir_name(const char *name)` - Set temp directory name
 - `void stk_set_module_init_fn(const char *name)` - Set module init function name
 - `void stk_set_module_shutdown_fn(const char *name)` - Set module shutdown function name
+- `void stk_set_module_name_fn(const char *name);` - Set module name function name
+- `void stk_set_module_version_fn(const char *name);` - Set module version function name
+- `void stk_set_module_description_fn(const char *name);` - Set module description function name
+- `void stk_set_module_deps_sym(const char *name)` - Set module deps array symbol name (default: `stk_mod_deps`)
 
 #### Logging
 - `void stk_set_logging_enabled(unsigned char enabled)` - Enable/disable all logging
@@ -182,9 +234,7 @@ stk_init();
 
 ## Project Status
 
-**Current Version:** 0.1.1 (Pre-release)
+**Current Version:** 1.0.0-pre.8
-
-This release brings C89 compliance fixes and a complete logging system rewrite with levels, timestamps, and runtime configuration.
 
 ### What Works
 - Cross-platform module loading and hot-reloading
@@ -192,10 +242,15 @@ This release brings C89 compliance fixes and a complete logging system rewrite w
 - Robust hot-reload even during extremely rapid file changes
 - Enhanced logging with levels, timestamps, and filtering
 - Runtime-configurable logging behavior
+- Optional module metadata (name, version, description)
+- Dependency declaration, validation, and versioning
+- Detailed dependency failure logging (missing ids, version mismatches)
+- Cascade unload when dependencies are removed
+- Pending queue with automatic retry when deps become available
+- Topological sort with cycle detection
 
-### In Progress (Phase 1)
+### Phase 2
-- Module metadata (name, version, description)
+- WASM module support
-- Dependency management and versioning
 
 See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
 

include/stk.h

@@ -6,8 +6,13 @@
 
 /* Buffers */
 #define STK_LOG_PREFIX_BUFFER 64
+#define STK_MOD_DEP_OPERATOR_BUFFER 3
+#define STK_MOD_DEP_LOG_BUFFER 2048
+#define STK_MOD_DESC_BUFFER 256
 #define STK_MOD_DIR_BUFFER 256
 #define STK_MOD_ID_BUFFER 64
+#define STK_MOD_NAME_BUFFER 128
+#define STK_MOD_VERSION_BUFFER 32
 #define STK_PATH_MAX 256
 #define STK_PATH_MAX_OS 4096
 
@@ -23,6 +28,9 @@
 #define STK_MOD_LIBRARY_LOAD_ERROR 2
 #define STK_MOD_SYMBOL_NOT_FOUND_ERROR 3
 #define STK_MOD_REALLOC_FAILURE 4
+#define STK_MOD_DEP_NOT_FOUND_ERROR 5
+#define STK_MOD_DEP_VERSION_MISMATCH_ERROR 6
+#define STK_MOD_DEP_CIRCULAR_ERROR 7
 
 /* Platform return codes */
 #define STK_PLATFORM_OPERATION_SUCCESS 0
@@ -35,6 +43,11 @@
 #define STK_FLAG_INITIALIZED 0x01
 #define STK_FLAG_LOGGING_ENABLED 0x02
 
+/* Dependency constraint operators */
+#define STK_DEP_MIN 0
+#define STK_DEP_EXACT 1
+#define STK_DEP_COMPAT 2
+
 #if defined(__linux__) || defined(_WIN32)
 #define STK_EVENT_BUFFER 4096
 #endif
@@ -59,6 +72,11 @@ typedef enum {
 	STK_MOD_RELOAD
 } stk_module_event_t;
 
+typedef struct {
+	char id[STK_MOD_ID_BUFFER];
+	char version[STK_MOD_VERSION_BUFFER];
+} stk_dep_t;
+
 unsigned char stk_init(void);
 void stk_shutdown(void);
 size_t stk_module_count(void);
@@ -68,6 +86,10 @@ void stk_set_tmp_dir_name(const char *name);
 void stk_set_module_init_fn(const char *name);
 void stk_set_module_shutdown_fn(const char *name);
 void stk_set_logging_enabled(unsigned char enabled);
+void stk_set_module_name_fn(const char *name);
+void stk_set_module_version_fn(const char *name);
+void stk_set_module_description_fn(const char *name);
+void stk_set_module_deps_sym(const char *name);
 unsigned char stk_is_logging_enabled(void);
 
 #ifdef __cplusplus

include/stk_version.h

@@ -1,9 +1,9 @@
 #ifndef STK_VERSION_H
 #define STK_VERSION_H
 
-#define STK_VERSION_MAJOR 0
+#define STK_VERSION_MAJOR 1
-#define STK_VERSION_MINOR 1
+#define STK_VERSION_MINOR 0
-#define STK_VERSION_PATCH 1
+#define STK_VERSION_PATCH 0
 
 #define STK_STRINGIFY_HELPER(x) #x
 #define STK_STRINGIFY(x) STK_STRINGIFY_HELPER(x)

src/platform.c

@@ -107,9 +107,29 @@ typedef struct {
 unsigned char platform_mkdir(const char *path)
 {
 #ifdef _WIN32
-	return CreateDirectoryA(path, NULL) ? STK_PLATFORM_OPERATION_SUCCESS
+	DWORD attrib;
-					    : STK_PLATFORM_MKDIR_ERROR;
+
+	attrib = GetFileAttributesA(path);
+
+	if (attrib != INVALID_FILE_ATTRIBUTES &&
+	    (attrib & FILE_ATTRIBUTE_DIRECTORY))
+		return STK_PLATFORM_OPERATION_SUCCESS;
+
+	if (!CreateDirectoryA(path, NULL))
+		return STK_PLATFORM_MKDIR_ERROR;
+
+	if (strrchr(path, '\\') && *(strrchr(path, '\\') + 1) == '.')
+		SetFileAttributesA(path, FILE_ATTRIBUTE_HIDDEN);
+	else if (!strrchr(path, '\\') && path[0] == '.')
+		SetFileAttributesA(path, FILE_ATTRIBUTE_HIDDEN);
+
+	return STK_PLATFORM_OPERATION_SUCCESS;
 #else
+	struct stat st;
+
+	if (stat(path, &st) == 0 && S_ISDIR(st.st_mode))
+		return STK_PLATFORM_OPERATION_SUCCESS;
+
 	return mkdir(path, 0755) == 0 ? STK_PLATFORM_OPERATION_SUCCESS
 				      : STK_PLATFORM_MKDIR_ERROR;
 #endif

src/stk.c

@@ -8,18 +8,26 @@
 typedef int (*stk_init_mod_func)(void);
 typedef void (*stk_shutdown_mod_func)(void);
 
-extern void **stk_handles;
+typedef struct {
-extern stk_init_mod_func *stk_inits;
+	char desc[STK_MOD_DESC_BUFFER];
-extern stk_shutdown_mod_func *stk_shutdowns;
+	char name[STK_MOD_NAME_BUFFER];
-extern char (*stk_module_ids)[STK_MOD_ID_BUFFER];
+	char id[STK_MOD_ID_BUFFER];
+	char version[STK_MOD_VERSION_BUFFER];
+	void *handle;
+	stk_init_mod_func init;
+	stk_shutdown_mod_func shutdown;
+	stk_dep_t *deps;
+	size_t dep_count;
+} stk_mod_t;
 
+extern stk_mod_t *stk_modules;
 extern size_t module_count;
 
 unsigned char stk_flags = STK_FLAG_LOGGING_ENABLED;
 
 static char stk_mod_dir[STK_PATH_MAX_OS] = "mods";
 static char stk_tmp_name[STK_MOD_ID_BUFFER] = ".tmp";
-static char stk_tmp_dir[STK_PATH_MAX_OS] = "mods/.tmp";
+static char stk_tmp_dir[STK_PATH_MAX_OS] = "";
 static void *watch_handle = NULL;
 
 char (*platform_directory_init_scan(const char *path,
@@ -37,12 +45,27 @@ void extract_module_id(const char *path, char *out_id);
 int is_mod_loaded(const char *module_id);
 
 size_t stk_module_count(void);
+unsigned char stk_module_preload(const char *path, int index);
+unsigned char stk_module_activate(size_t index);
+unsigned char stk_validate_dependencies_single(size_t index);
+void stk_log_dependency_failures(size_t index, const char *action);
+void stk_module_discard(size_t index);
 unsigned char stk_module_load(const char *path, int index);
 unsigned char stk_module_load_init(const char *path, int index);
 unsigned char stk_module_init_memory(size_t capacity);
 unsigned char stk_module_realloc_memory(size_t new_capacity);
 void stk_module_unload(size_t index);
 void stk_module_unload_all(void);
+unsigned char stk_validate_dependencies(size_t count);
+unsigned char stk_topo_sort(size_t count, size_t *order);
+void stk_pending_add(const char *path);
+void stk_pending_add_batch(const char (*paths)[STK_PATH_MAX_OS], size_t count);
+void stk_pending_remove(const char *id);
+size_t stk_pending_retry(void);
+void stk_sort_unload_order(size_t *indices, size_t n);
+void stk_collect_dependents(size_t *indices, size_t *count, size_t capacity);
+void stk_sort_load_order(int *file_indices, size_t n,
+			 char (*file_names)[STK_PATH_MAX], const char *tmp_dir);
 
 static void build_path(char *dest, size_t dest_size, const char *dir,
 		       const char *file)
@@ -64,23 +87,65 @@ static const char *stk_error_string(int error_code)
 		return "init failure";
 	case STK_MOD_REALLOC_FAILURE:
 		return "memory reallocation failed";
+	case STK_MOD_DEP_NOT_FOUND_ERROR:
+		return "dependency not found";
+	case STK_MOD_DEP_VERSION_MISMATCH_ERROR:
+		return "dependency version mismatch";
+	case STK_MOD_DEP_CIRCULAR_ERROR:
+		return "circular dependency detected";
 	default:
 		return "unknown error";
 	}
 }
 
+static void stk_log_module(size_t index)
+{
+	const char *name =
+	    stk_modules[index].name[0] ? stk_modules[index].name : NULL;
+	const char *desc =
+	    stk_modules[index].desc[0] ? stk_modules[index].desc : NULL;
+
+	if (name && desc)
+		stk_log(STK_LOG_INFO, "  %s v%s - %s (%s)",
+			stk_modules[index].id, stk_modules[index].version, desc,
+			name);
+	else if (name)
+		stk_log(STK_LOG_INFO, "  %s v%s (%s)", stk_modules[index].id,
+			stk_modules[index].version, name);
+	else if (desc)
+		stk_log(STK_LOG_INFO, "  %s v%s - %s", stk_modules[index].id,
+			stk_modules[index].version, desc);
+	else
+		stk_log(STK_LOG_INFO, "  %s v%s", stk_modules[index].id,
+			stk_modules[index].version);
+}
+
+static void stk_log_modules(void)
+{
+	size_t i;
+	stk_log(STK_LOG_INFO,
+		"Loaded modules (%lu):", (unsigned long)module_count);
+	for (i = 0; i < module_count; i++)
+		stk_log_module(i);
+}
+
 unsigned char stk_init(void)
 {
 	char (*files)[STK_PATH_MAX] = NULL;
-	size_t file_count, i, successful_loads = 0;
+	char (*test_scan)[STK_PATH_MAX];
+	size_t file_count, i, j, write, successful_loads = 0;
+	size_t index, test_count;
 	char full_path[STK_PATH_MAX_OS];
 	char tmp_path[STK_PATH_MAX_OS];
 	int load_result;
+	unsigned char dep_result;
+	size_t *order = NULL;
+	char (*init_batch)[STK_PATH_MAX_OS] = NULL;
+	size_t init_batch_count = 0;
 
+	platform_mkdir(stk_mod_dir);
+	build_path(stk_tmp_dir, sizeof(stk_tmp_dir), stk_mod_dir, stk_tmp_name);
 	if (platform_mkdir(stk_tmp_dir) != STK_PLATFORM_OPERATION_SUCCESS) {
-		char (*test_scan)[STK_PATH_MAX];
-		size_t test_count;
-
 		test_scan =
 		    platform_directory_init_scan(stk_tmp_dir, &test_count);
 		if (test_scan)
@@ -115,22 +180,86 @@ unsigned char stk_init(void)
 			continue;
 		}
 
-		load_result = stk_module_load_init(tmp_path, successful_loads);
+		load_result = stk_module_preload(tmp_path, successful_loads);
 
 		if (load_result != STK_MOD_INIT_SUCCESS) {
-			stk_log(STK_LOG_ERROR, "Failed to load module %s: %s",
+			stk_log(STK_LOG_ERROR,
-				files[i], stk_error_string(load_result));
+				"Failed to preload module %s: %s", files[i],
+				stk_error_string(load_result));
 		} else {
 			successful_loads++;
+			module_count++;
 		}
 	}
 
-	if (successful_loads < file_count) {
+	if (successful_loads < file_count)
 		stk_module_realloc_memory(successful_loads);
-	}
 
 	free(files);
 
+	if (module_count == 0)
+		goto scanned;
+
+	order = malloc(module_count * sizeof(size_t));
+	if (order) {
+		dep_result = stk_topo_sort(module_count, order);
+		if (dep_result != STK_MOD_INIT_SUCCESS)
+			stk_log(STK_LOG_ERROR, "Dependency sort failed: %s",
+				stk_error_string(dep_result));
+	}
+
+	init_batch = malloc(module_count * sizeof(*init_batch));
+
+	for (j = 0; j < module_count; j++) {
+		index = order ? order[j] : j;
+		dep_result = stk_validate_dependencies_single(index);
+		if (dep_result != STK_MOD_INIT_SUCCESS) {
+			stk_log_dependency_failures(index, "Deferring");
+			if (init_batch) {
+				build_path(init_batch[init_batch_count],
+					   sizeof(init_batch[init_batch_count]),
+					   stk_tmp_dir, stk_modules[index].id);
+				strncat(
+				    init_batch[init_batch_count],
+				    STK_MODULE_EXT,
+				    sizeof(init_batch[init_batch_count]) -
+					strlen(init_batch[init_batch_count]) -
+					1);
+				init_batch_count++;
+			}
+			stk_module_discard(index);
+			continue;
+		}
+		if (stk_module_activate(index) != STK_MOD_INIT_SUCCESS) {
+			stk_log(STK_LOG_ERROR, "Failed to init module %s",
+				stk_modules[index].id);
+			stk_module_discard(index);
+		}
+	}
+
+	if (init_batch_count > 0)
+		stk_pending_add_batch(
+		    (const char (*)[STK_PATH_MAX_OS])init_batch,
+		    init_batch_count);
+
+	free(init_batch);
+	init_batch = NULL;
+
+	if (order) {
+		free(order);
+		order = NULL;
+	}
+
+	write = 0;
+	for (j = 0; j < module_count; j++) {
+		if (stk_modules[j].handle != NULL) {
+			if (write != j)
+				stk_modules[write] = stk_modules[j];
+			write++;
+		}
+	}
+	module_count = write;
+
 scanned:
 	watch_handle = platform_directory_watch_start(stk_mod_dir);
 	if (!watch_handle) {
@@ -141,9 +270,12 @@ scanned:
 		return STK_INIT_WATCH_ERROR;
 	}
 
-	stk_log(STK_LOG_INFO, "stk v%s initialized! Loaded %lu mod%s from %s/",
+	stk_pending_retry();
-		STK_VERSION_STRING, module_count, module_count != 1 ? "s" : "",
+
-		stk_mod_dir);
+	stk_log(STK_LOG_INFO, "stk v%s initialized, watching %s/",
+		STK_VERSION_STRING, stk_mod_dir);
+	if (module_count > 0)
+		stk_log_modules();
 
 	stk_flags |= STK_FLAG_INITIALIZED;
 	return STK_INIT_SUCCESS;
@@ -177,16 +309,47 @@ size_t stk_poll(void)
 		  unload_count = 0;
 	int *reloaded_mod_indices = NULL, *reloaded_mod_file_indices = NULL,
 	    *unloaded_mod_indices = NULL, *loaded_mod_indices = NULL;
-	size_t remaining_loads, new_capacity, holes_to_fill;
+	size_t new_capacity;
-	size_t write_pos, read_pos;
 	char full_path[STK_PATH_MAX_OS], tmp_path[STK_PATH_MAX_OS];
 	char mod_id[STK_MOD_ID_BUFFER];
 	int load_result;
 	size_t successful_appends = 0;
+	char (*module_ids)[STK_MOD_ID_BUFFER] = NULL;
+	unsigned char dep_result;
+	size_t *order = NULL;
+	size_t *unload_order = NULL;
+	size_t expanded_count;
+	size_t index, oi;
+	int is_orig;
+	size_t write;
+	int file_index, mod_index;
+	size_t *cascade_indices = NULL;
+	size_t cascade_count;
+	size_t j, k, cascade_write;
+	char (*dep_batch)[STK_PATH_MAX_OS] = NULL;
+	size_t dep_batch_count = 0;
+	char (*cascade_batch)[STK_PATH_MAX_OS] = NULL;
+	size_t cascade_batch_count = 0;
+	char (*load_batch)[STK_PATH_MAX_OS] = NULL;
+	size_t load_batch_count = 0;
+
+	if (module_count > 0) {
+		module_ids = malloc(module_count * sizeof(*module_ids));
+		if (module_ids) {
+			for (i = 0; i < module_count; i++) {
+				strncpy(module_ids[i], stk_modules[i].id,
+					STK_MOD_ID_BUFFER - 1);
+				module_ids[i][STK_MOD_ID_BUFFER - 1] = '\0';
+			}
+		}
+	}
+
+	events = platform_directory_watch_check(
+	    watch_handle, &file_list, &file_count, module_ids, module_count);
+
+	if (module_ids)
+		free(module_ids);
 
-	events = platform_directory_watch_check(watch_handle, &file_list,
-						&file_count, stk_module_ids,
-						module_count);
 	if (!events)
 		goto finish_poll;
 
@@ -244,25 +407,97 @@ size_t stk_poll(void)
 	goto begin_operations;
 
 handle_grow:
-	remaining_loads = load_count - unload_count;
+	new_capacity = module_count + load_count;
-	new_capacity = module_count + remaining_loads;
+	if (stk_module_realloc_memory(new_capacity) != STK_MOD_INIT_SUCCESS)
-	if (stk_module_realloc_memory(new_capacity) != STK_MOD_INIT_SUCCESS) {
 		goto free_poll;
-	}
 
 begin_operations:
-	for (i = 0; i < unload_count; ++i)
+	unload_order = malloc(module_count * sizeof(size_t));
-		stk_module_unload(unloaded_mod_indices[i]);
+	if (unload_order) {
+		expanded_count = unload_count;
+
+		for (i = 0; i < unload_count; i++)
+			unload_order[i] = (size_t)unloaded_mod_indices[i];
+
+		stk_collect_dependents(unload_order, &expanded_count,
+				       module_count);
+		stk_sort_unload_order(unload_order, expanded_count);
+
+		dep_batch = malloc(expanded_count * sizeof(*dep_batch));
+		dep_batch_count = 0;
+
+		for (i = 0; i < expanded_count; i++) {
+			index = unload_order[i];
+
+			stk_log(STK_LOG_INFO, "Unloaded module: %s",
+				stk_modules[index].id);
+			stk_pending_remove(stk_modules[index].id);
+
+			is_orig = 0;
+			for (oi = 0; oi < unload_count; oi++) {
+				if ((size_t)unloaded_mod_indices[oi] == index) {
+					is_orig = 1;
+					break;
+				}
+			}
+			if (!is_orig && dep_batch) {
+				build_path(dep_batch[dep_batch_count],
+					   sizeof(dep_batch[dep_batch_count]),
+					   stk_tmp_dir, stk_modules[index].id);
+				strncat(
+				    dep_batch[dep_batch_count], STK_MODULE_EXT,
+				    sizeof(dep_batch[dep_batch_count]) -
+					strlen(dep_batch[dep_batch_count]) - 1);
+				dep_batch_count++;
+			}
+
+			stk_module_unload(index);
+		}
+
+		if (dep_batch_count > 0)
+			stk_pending_add_batch(
+			    (const char (*)[STK_PATH_MAX_OS])dep_batch,
+			    dep_batch_count);
+
+		free(dep_batch);
+		dep_batch = NULL;
+		free(unload_order);
+		unload_order = NULL;
+	} else {
+		for (i = 0; i < unload_count; ++i) {
+			stk_log(STK_LOG_INFO, "Unloaded module: %s",
+				stk_modules[unloaded_mod_indices[i]].id);
+			stk_pending_remove(
+			    stk_modules[unloaded_mod_indices[i]].id);
+			stk_module_unload(unloaded_mod_indices[i]);
+		}
+	}
+
+	if (unload_count > 0) {
+		write = 0;
+		for (i = 0; i < module_count; i++) {
+			if (stk_modules[i].handle != NULL) {
+				if (write != i)
+					stk_modules[write] = stk_modules[i];
+				write++;
+			}
+		}
+		module_count = write;
+		if (module_count > 0)
+			stk_module_realloc_memory(module_count);
+	}
 
 	for (i = 0; i < reload_count; ++i) {
-		int file_index = reloaded_mod_file_indices[i];
+		file_index = reloaded_mod_file_indices[i];
-		int mod_index = reloaded_mod_indices[i];
+		mod_index = reloaded_mod_indices[i];
 
 		build_path(full_path, sizeof(full_path), stk_mod_dir,
 			   file_list[file_index]);
 		build_path(tmp_path, sizeof(tmp_path), stk_tmp_dir,
 			   file_list[file_index]);
 
+		stk_module_unload(mod_index);
+
 		if (platform_copy_file(full_path, tmp_path) !=
 		    STK_PLATFORM_OPERATION_SUCCESS) {
 			stk_log(STK_LOG_ERROR, "Failed to copy %s for reload",
@@ -270,68 +505,43 @@ begin_operations:
 			continue;
 		}
 
-		stk_module_unload(mod_index);
-
 		load_result = stk_module_load(tmp_path, mod_index);
-		if (load_result != STK_MOD_INIT_SUCCESS) {
+		if (load_result != STK_MOD_INIT_SUCCESS)
 			stk_log(STK_LOG_ERROR, "Failed to reload module %s: %s",
 				file_list[file_index],
 				stk_error_string(load_result));
-		}
 	}
 
-	holes_to_fill = (load_count < unload_count) ? load_count : unload_count;
+	for (i = 0; i < load_count; i++) {
-	for (i = 0; i < holes_to_fill; ++i) {
+		file_index = loaded_mod_indices[i];
-		int target_index = unloaded_mod_indices[i];
-		int file_index = loaded_mod_indices[i];
-
 		build_path(full_path, sizeof(full_path), stk_mod_dir,
 			   file_list[file_index]);
 		build_path(tmp_path, sizeof(tmp_path), stk_tmp_dir,
 			   file_list[file_index]);
-
+		platform_copy_file(full_path, tmp_path);
-		if (platform_copy_file(full_path, tmp_path) !=
-		    STK_PLATFORM_OPERATION_SUCCESS) {
-			stk_log(STK_LOG_ERROR, "Failed to copy %s for loading",
-				file_list[file_index]);
-			continue;
-		}
-
-		load_result = stk_module_load(tmp_path, target_index);
-		if (load_result != STK_MOD_INIT_SUCCESS) {
-			stk_log(STK_LOG_ERROR, "Failed to load module %s: %s",
-				file_list[file_index],
-				stk_error_string(load_result));
-		}
 	}
 
-	if (load_count > unload_count)
+	if (load_count > 1)
-		goto append_modules;
+		stk_sort_load_order(loaded_mod_indices, load_count, file_list,
+				    stk_tmp_dir);
 
-	if (unload_count > load_count)
+	load_batch = malloc(load_count * sizeof(*load_batch));
-		goto trim_arrays;
+	load_batch_count = 0;
 
-	goto free_poll;
+	for (i = 0; i < load_count; ++i) {
+		file_index = loaded_mod_indices[i];
 
-append_modules:
-	for (; i < load_count; ++i) {
-		int file_index = loaded_mod_indices[i];
-
-		build_path(full_path, sizeof(full_path), stk_mod_dir,
-			   file_list[file_index]);
 		build_path(tmp_path, sizeof(tmp_path), stk_tmp_dir,
 			   file_list[file_index]);
 
-		if (platform_copy_file(full_path, tmp_path) !=
-		    STK_PLATFORM_OPERATION_SUCCESS) {
-			stk_log(STK_LOG_ERROR, "Failed to copy %s for loading",
-				file_list[file_index]);
-			continue;
-		}
-
 		load_result = stk_module_load(tmp_path, module_count +
 							    successful_appends);
-		if (load_result != STK_MOD_INIT_SUCCESS) {
+		if (load_result == STK_MOD_DEP_NOT_FOUND_ERROR ||
+		    load_result == STK_MOD_DEP_VERSION_MISMATCH_ERROR) {
+			if (load_batch)
+				memcpy(load_batch[load_batch_count++], tmp_path,
+				       STK_PATH_MAX_OS);
+		} else if (load_result != STK_MOD_INIT_SUCCESS) {
 			stk_log(STK_LOG_ERROR, "Failed to load module %s: %s",
 				file_list[file_index],
 				stk_error_string(load_result));
@@ -342,34 +552,113 @@ append_modules:
 
 	module_count += successful_appends;
 
-	if (successful_appends < (load_count - holes_to_fill)) {
+	if (successful_appends < load_count)
 		stk_module_realloc_memory(module_count);
-	}
 
-	goto free_poll;
+	if (load_batch_count > 0)
+		stk_pending_add_batch(
+		    (const char (*)[STK_PATH_MAX_OS])load_batch,
+		    load_batch_count);
 
-trim_arrays:
+	free(load_batch);
-	write_pos = unloaded_mod_indices[holes_to_fill];
+	load_batch = NULL;
-	for (i = holes_to_fill + 1; i < unload_count; ++i) {
-		if (unloaded_mod_indices[i] < write_pos)
-			write_pos = unloaded_mod_indices[i];
-	}
 
-	for (read_pos = write_pos + 1; read_pos < module_count; ++read_pos) {
+	goto validate_deps;
-		if (stk_handles[read_pos] != NULL) {
+
-			stk_handles[write_pos] = stk_handles[read_pos];
+validate_deps:
-			stk_inits[write_pos] = stk_inits[read_pos];
+	if (module_count == 0)
-			stk_shutdowns[write_pos] = stk_shutdowns[read_pos];
+		goto free_poll;
-			memcpy(stk_module_ids[write_pos],
+
-			       stk_module_ids[read_pos], STK_MOD_ID_BUFFER);
+	do {
-			++write_pos;
+		cascade_count = 0;
+
+		cascade_indices = malloc(module_count * sizeof(size_t));
+		if (!cascade_indices)
+			break;
+
+		for (j = 0; j < module_count; j++) {
+			if (stk_modules[j].dep_count == 0)
+				continue;
+			for (k = 0; k < stk_modules[j].dep_count; k++) {
+				if (is_mod_loaded(stk_modules[j].deps[k].id) <
+				    0) {
+					cascade_indices[cascade_count++] = j;
+					break;
+				}
+			}
 		}
-	}
 
-	module_count = write_pos;
+		if (cascade_count == 0) {
-	stk_module_realloc_memory(module_count);
+			free(cascade_indices);
+			cascade_indices = NULL;
+			break;
+		}
+
+		cascade_batch = malloc(cascade_count * sizeof(*cascade_batch));
+		cascade_batch_count = 0;
+
+		for (j = 0; j < cascade_count; j++) {
+			index = cascade_indices[j];
+			stk_log_dependency_failures(index, "Unloading");
+			if (cascade_batch) {
+				build_path(
+				    cascade_batch[cascade_batch_count],
+				    sizeof(cascade_batch[cascade_batch_count]),
+				    stk_tmp_dir, stk_modules[index].id);
+				strncat(
+				    cascade_batch[cascade_batch_count],
+				    STK_MODULE_EXT,
+				    sizeof(cascade_batch[cascade_batch_count]) -
+					strlen(cascade_batch
+						   [cascade_batch_count]) -
+					1);
+				cascade_batch_count++;
+			}
+			stk_module_unload(index);
+		}
+
+		if (cascade_batch_count > 0)
+			stk_pending_add_batch(
+			    (const char (*)[STK_PATH_MAX_OS])cascade_batch,
+			    cascade_batch_count);
+
+		free(cascade_batch);
+		cascade_batch = NULL;
+
+		cascade_write = 0;
+		for (j = 0; j < module_count; j++) {
+			if (stk_modules[j].handle != NULL) {
+				if (cascade_write != j)
+					stk_modules[cascade_write] =
+					    stk_modules[j];
+				cascade_write++;
+			}
+		}
+		module_count = cascade_write;
+
+		free(cascade_indices);
+		cascade_indices = NULL;
+
+	} while (cascade_count > 0);
+
+	if (module_count > 0)
+		stk_module_realloc_memory(module_count);
+
+	order = malloc(module_count * sizeof(size_t));
+	if (order) {
+		dep_result = stk_topo_sort(module_count, order);
+		if (dep_result != STK_MOD_INIT_SUCCESS)
+			stk_log(STK_LOG_ERROR, "Dependency sort failed: %s",
+				stk_error_string(dep_result));
+		free(order);
+	}
 
 free_poll:
+	stk_pending_retry();
+
+	if (module_count > 0)
+		stk_log_modules();
+
 	free(reloaded_mod_indices);
 	free(reloaded_mod_file_indices);
 	free(unloaded_mod_indices);

test/bmake.mk

@@ -22,23 +22,27 @@ test_program: test.c
 test_mod$(MODULE_EXT): test_mod.c
 	$(CC) $(CFLAGS) -fPIC -shared -o $@ test_mod.c
 
+test_mod_dep$(MODULE_EXT): test_mod_dep.c
+	$(CC) $(CFLAGS) -fPIC -shared -o $@ test_mod_dep.c
+
 setup:
 	@mkdir -p mods
 	@cp -f test_mod$(MODULE_EXT) mods/ 2>/dev/null || true
-	@echo "Test environment ready: mods/ directory with test_mod$(MODULE_EXT)"
+	@cp -f test_mod_dep$(MODULE_EXT) mods/ 2>/dev/null || true
+	@echo "Test environment ready: mods/ directory with test modules"
 
-run: test_program test_mod$(MODULE_EXT) setup
+run: test_program test_mod$(MODULE_EXT) test_mod_dep$(MODULE_EXT) setup
 	@echo "Running integration test (CTRL+C to exit)..."
 	@./test_program
 
-test: test_program test_mod$(MODULE_EXT) setup
+test: test_program test_mod$(MODULE_EXT) test_mod_dep$(MODULE_EXT) setup
 	@echo "=== stk Integration Test ==="
 	@echo "1. Starting test program"
-	@echo "2. Will load test_mod$(MODULE_EXT) from mods/"
+	@echo "2. Will load test_mod and test_mod_dep from mods/"
 	@echo "3. Press CTRL+C to exit"
 	@echo "============================="
 	@./test_program || echo "Test completed."
 
 clean:
-	rm -f test_program test_mod$(MODULE_EXT)
+	rm -f test_program test_mod$(MODULE_EXT) test_mod_dep$(MODULE_EXT)
 	rm -rf mods/

test/gmake.mk

@@ -3,6 +3,8 @@ CFLAGS = -Wall -Wpedantic -I../include -std=c89
 LDFLAGS = -L../bin/debug -lstk
 
 ifeq ($(OS),Windows_NT)
+    SHELL := cmd.exe
+    .SHELLFLAGS := /c
     MODULE_EXT = .dll
     EXE_EXT = .exe
 else
@@ -21,16 +23,21 @@ test_program$(EXE_EXT): test.c
 test_mod$(MODULE_EXT): test_mod.c
 	$(CC) $(CFLAGS) -fPIC -shared -o $@ test_mod.c
 
+test_mod_dep$(MODULE_EXT): test_mod_dep.c
+	$(CC) $(CFLAGS) -fPIC -shared -o $@ test_mod_dep.c
+
 setup:
 ifeq ($(OS),Windows_NT)
 	@if not exist mods mkdir mods
 	@if exist test_mod.dll copy /Y test_mod.dll mods\ >nul 2>&1
+	@if exist test_mod_dep.dll copy /Y test_mod_dep.dll mods\ >nul 2>&1
 else
 	@mkdir -p mods
 	@cp -f test_mod.so mods/ 2>/dev/null || true
+	@cp -f test_mod_dep.so mods/ 2>/dev/null || true
 endif
 
-test: test_program$(EXE_EXT) test_mod$(MODULE_EXT) setup
+test: test_program$(EXE_EXT) test_mod$(MODULE_EXT) test_mod_dep$(MODULE_EXT) setup
 ifeq ($(OS),Windows_NT)
 	@set PATH=../bin/debug;%PATH% && cmd /C "test_program.exe"
 else
@@ -39,9 +46,9 @@ endif
 
 clean:
 ifeq ($(OS),Windows_NT)
-	@del /Q test_program.exe test_mod.dll 2>nul || true
+	@del /Q test_program.exe test_mod.dll test_mod_dep.dll 2>nul || true
 	@rmdir /S /Q mods 2>nul || true
 else
-	@rm -f test_program test_mod.so
+	@rm -f test_program test_mod.so test_mod_dep.so
 	@rm -rf mods
 endif

test/test_mod.c

@@ -2,8 +2,11 @@
 
 int stk_mod_init(void)
 {
-	printf("test mod initialized!\n");
+	printf("test_mod initialized!\n");
 	return 0;
 }
 
-void stk_mod_shutdown(void) { printf("test mod shut down.\n"); }
+void stk_mod_shutdown(void) { printf("test_mod shut down.\n"); }
+
+const char *stk_mod_name(void) { return "Test Module"; }
+const char *stk_mod_version(void) { return "1.0.0"; }

test/test_mod_dep.c

@@ -0,0 +1,19 @@
+#include <stdio.h>
+
+typedef struct {
+	char id[64];
+	char version[32];
+} dep_t;
+
+int stk_mod_init(void)
+{
+	printf("test_mod_dep initialized!\n");
+	return 0;
+}
+
+void stk_mod_shutdown(void) { printf("test_mod_dep shut down.\n"); }
+
+const char *stk_mod_name(void) { return "Dependent Test Module"; }
+const char *stk_mod_version(void) { return "1.0.0"; }
+
+dep_t stk_mod_deps[] = {{"test_mod", ">=1.0.0"}, {"", ""}};