refactor(api): add deprecation markers for v1.0 API freeze (#676)

* refactor(api): add deprecation markers for v1.0 API freeze

Mark legacy APIs scheduled for removal in v2.0.0 so consumers see compiler
warnings during the migration window. The v3.0.0 pass removed legacy types
but left transitional surfaces without [[deprecated]] attributes.

- compatibility.h: emit #pragma message for thread_system/thread_module/
  thread_namespace/utility_module aliases (namespace aliases cannot carry
  a portable [[deprecated]] attribute). Suppressible via
  THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING.
- thread_logger.h: attach [[deprecated]] to user-facing methods
  (log/log_error/set_level/set_enabled/set_lightweight_mode). Keep the
  SDOF-safe helpers (instance/is_shutting_down/prepare_shutdown) stable
  because thread_context still depends on them. Leave log_level enum
  without an attribute to avoid internal self-warnings from member
  declarations; its deprecation propagates through the deprecated
  methods that accept it.
- lockfree/lockfree_queue.h: emit #pragma message on include of the
  forwarding header. Suppressible via
  THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING.
- queue.cppm: define the suppression macro before including
  lockfree_queue.h so the module re-export path stays quiet.

Part of #670
Closes #672

* docs(migration): document v1.0.0 API freeze and deprecation policy

Add a v1.0.0 section to MIGRATION.md that records the frozen public
surface, the deprecated APIs scheduled for removal in v2.0.0, and the
migration paths and suppression macros consumers can use during the
migration window.

Previously the document only described the v3.0.0 common_system
transition. With v1.0.0 being an API stability commitment, consumers
need a single place that lists what is frozen, what remains
transitional, and how to silence legacy include warnings without
editing upstream headers.

Part of #670
Closes #672

Author: kcenon

docs/advanced/MIGRATION.md

@@ -16,6 +16,7 @@ category: "MIGR"
 
 ## Table of Contents
 
+- [v1.0.0 API Freeze (current)](#v100-api-freeze-current)
 - [v3.0.0 Migration (common_system)](#v300-migration-common_system)
 - [Overview](#overview)
 - [Migration Status](#migration-status)
@@ -35,6 +36,78 @@ category: "MIGR"
   - [Current Status (2025-09-13)](#current-status-2025-09-13)
   - [Detailed Status Log](#detailed-status-log)
 
+## v1.0.0 API Freeze (current)
+
+**Release Date:** 2026-04-14
+
+v1.0.0 is an **API stability commitment**. From v1.0.0 onward, any breaking change
+to the public API requires a major version bump. This section records the surface
+that was frozen and the legacy APIs that remain only for migration support.
+
+### Frozen Public Surface
+
+The authoritative public headers live under `include/kcenon/thread/`:
+
+| Subsystem | Path | Notes |
+|-----------|------|-------|
+| Core threading | `core/` | `thread_pool`, `thread_worker`, `job`, `job_queue`, `cancellation_token`, `future_job`, `submit_options` |
+| Queues | `queue/`, `concurrent/` | `adaptive_job_queue`, `concurrent_queue`, `queue_factory` |
+| DAG | `dag/` | `dag_scheduler`, `dag_job`, `dag_job_builder` |
+| Configuration | `thread_config.h`, `config/` | Unified builder for pool, DAG, and aging settings |
+| Error handling | `core/error_handling.h` | `error_code` enum + `common::Result<T>` / `common::VoidResult` helpers |
+| Synchronization | `core/sync_primitives.h`, `core/hazard_pointer.h` | Lock-free reclamation helpers |
+
+### Deprecated in v1.0.0 (slated for removal in v2.0.0)
+
+The following APIs emit compiler warnings in v1.0.0 and will be removed in v2.0.0.
+
+| Symbol | Replacement | Trigger |
+|--------|-------------|---------|
+| `thread_system::` / `thread_module::` / `thread_namespace::` namespace aliases | Use `kcenon::thread::` directly | `#pragma message` on `compatibility.h` include |
+| `utility_module::` namespace alias | Use `kcenon::thread::utils::` directly | `#pragma message` on `compatibility.h` include |
+| `kcenon::thread::log_level` (enum in `thread_logger.h`) | `kcenon::thread::log_level_v2` or `common::interfaces::log_level` | Warnings via the deprecated `thread_logger` methods that consume it |
+| `kcenon::thread::thread_logger::log()`, `log_error()`, `set_enabled()`, `is_enabled()`, `set_level()`, `set_lightweight_mode()`, `is_lightweight_mode()` | `thread_context::log()` with `common::interfaces::ILogger` | `[[deprecated]]` attribute |
+| `<kcenon/thread/lockfree/lockfree_queue.h>` (forwarding header) | `<kcenon/thread/concurrent/concurrent_queue.h>` | `#pragma message` on include |
+| `<kcenon/thread/core/thread_pool_fmt.h>` (forwarding header) | `<kcenon/thread/formatters.h>` | `#pragma message` on include (pre-existing) |
+| `<kcenon/thread/dag/dag_config.h>` (documentation-only deprecation) | `<kcenon/thread/thread_config.h>` builder | Doxygen `@deprecated` |
+| `<kcenon/thread/impl/typed_pool/priority_aging_config.h>` (documentation-only deprecation) | `<kcenon/thread/thread_config.h>` builder | Doxygen `@deprecated` |
+
+### Silencing Legacy Warnings During Migration
+
+While migrating a dependent project, warnings emitted by legacy headers can be
+silenced by defining the following macros **before** the `#include`:
+
+```cpp
+// Legacy namespace aliases in compatibility.h
+#define THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING 1
+#include <kcenon/thread/compatibility.h>
+
+// Legacy forwarding header lockfree_queue.h
+#define THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING 1
+#include <kcenon/thread/lockfree/lockfree_queue.h>
+```
+
+These macros must be removed before v2.0.0 adoption.
+
+### API Changes Since v3.0.0
+
+- `cancellation_token::check_cancelled()` returns `common::VoidResult`
+  (previously `throw_if_cancelled()` threw `std::runtime_error`). See #671.
+- `cancellable_future<T>::get()` / `get_for()` return
+  `common::Result<T>` / `common::Result<std::optional<T>>`. See #671.
+- `thread_pool::submit_wait_any()` returns `common::Result<R>` with
+  `error_code::invalid_argument` for empty input. See #671.
+
+### Removed in v1.0.0
+
+Previously removed in v3.0.0 (kept for reference):
+
+- `kcenon::thread::result<T>` / `result_void` / `error` — use `common::Result<T>` / `common::VoidResult` / `common::error_info`.
+- `kcenon::thread::logger_interface` / `monitoring_interface` / `monitorable_interface` — use `common::interfaces::ILogger` / `IMonitor` / `IMonitorable`.
+- `kcenon::thread::throw_if_cancelled()` — removed in #671, replaced by `check_cancelled()` returning `common::VoidResult`.
+
+---
+
 ## v3.0.0 Migration (common_system)
 
 **Release Date:** 2025-12-19

include/kcenon/thread/compatibility.h

@@ -24,9 +24,28 @@ namespace detail {}
 
 // Legacy namespace aliases. These remain until dependent projects
 // migrate to the unified kcenon::thread namespace.
+//
+// @deprecated Since v1.0.0. These aliases will be removed in v2.0.0.
+// Use `kcenon::thread` and `kcenon::thread::utils` directly instead.
+//
+// NOTE: The C++ standard does not support `[[deprecated]]` on namespace
+// aliases (only on namespace definitions). Consumers that need compile-time
+// warnings should migrate include-by-include; an include-guard warning is
+// emitted once per translation unit below (suppressible by defining
+// THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING before the include).
 namespace thread_system = kcenon::thread;
 namespace thread_module = kcenon::thread;
 namespace thread_namespace = kcenon::thread;
 
 // Legacy utility namespace names still expected by some consumers.
 namespace utility_module = kcenon::thread::utils;
+
+#if !defined(THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING) \
+    && !defined(KCENON_THREAD_COMPATIBILITY_H_WARNED)
+#define KCENON_THREAD_COMPATIBILITY_H_WARNED 1
+#if defined(_MSC_VER)
+#pragma message("thread_system/thread_module/thread_namespace/utility_module namespace aliases are deprecated since v1.0.0 and will be removed in v2.0.0. Use 'kcenon::thread' directly. Define THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING to silence this warning.")
+#elif defined(__GNUC__) || defined(__clang__)
+#pragma message "thread_system/thread_module/thread_namespace/utility_module namespace aliases are deprecated since v1.0.0 and will be removed in v2.0.0. Use 'kcenon::thread' directly. Define THREAD_SUPPRESS_LEGACY_NAMESPACE_WARNING to silence this warning."
+#endif
+#endif

include/kcenon/thread/core/thread_logger.h

@@ -26,7 +26,18 @@ namespace kcenon::thread {
 
 /**
  * @enum log_level
- * @brief Logging severity levels
+ * @brief Logging severity levels (legacy).
+ *
+ * @deprecated Since v1.0.0. Use `kcenon::thread::log_level_v2` (from
+ * `<kcenon/thread/core/log_level.h>`) or `common::interfaces::log_level`
+ * (from common_system) instead. Will be removed in v2.0.0.
+ * See Issue #261 for migration details.
+ *
+ * NOTE: `[[deprecated]]` is applied at the `thread_logger` member-function
+ * level (log/set_level/log_error) rather than on this enum itself, because
+ * this type is still referenced internally by the SDOF-safe shutdown
+ * helpers. Using `log_level` via a deprecated API emits a warning; direct
+ * use without the logger does not.
  */
 enum class log_level {
     trace,
@@ -108,34 +119,60 @@ class thread_logger {
     }
 
     /**
-     * @brief Enable/disable logging
+     * @brief Enable/disable logging.
+     *
+     * @deprecated Since v1.0.0. Inject a `common::interfaces::ILogger`
+     * via `thread_context` and control logging through its implementation
+     * instead. Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Use 'common::interfaces::ILogger' via thread_context instead. "
+        "Will be removed in v2.0.")]]
     void set_enabled(bool enabled) {
         enabled_ = enabled;
     }
 
     /**
-     * @brief Check if logging is enabled
+     * @brief Check if logging is enabled.
+     *
+     * @deprecated Since v1.0.0. Check availability through
+     * `thread_context::has_logger()` instead. Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Use 'thread_context::has_logger()' instead. "
+        "Will be removed in v2.0.")]]
     bool is_enabled() const {
         return enabled_;
     }
 
     /**
-     * @brief Set minimum log level
+     * @brief Set minimum log level.
+     *
+     * @deprecated Since v1.0.0. Configure log level on the injected
+     * `common::interfaces::ILogger` implementation instead.
+     * Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Configure log level on 'common::interfaces::ILogger' instead. "
+        "Will be removed in v2.0.")]]
     void set_level(log_level level) {
         min_level_ = level;
     }
 
     /**
-     * @brief Log a message with context
+     * @brief Log a message with context.
      *
      * @param level Severity level
      * @param thread_name Thread identifier
      * @param message Log message
      * @param context Additional context (optional)
+     *
+     * @deprecated Since v1.0.0. Use `thread_context::log()` backed by
+     * `common::interfaces::ILogger` instead. Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Use 'thread_context::log()' with 'common::interfaces::ILogger' "
+        "instead. Will be removed in v2.0.")]]
     void log(log_level level, std::string_view thread_name,
              std::string_view message, std::string_view context = "") {
         // Early return during shutdown to avoid accessing potentially destroyed resources
@@ -179,9 +216,16 @@ class thread_logger {
     }
 
     /**
-     * @brief Log error with error code
+     * @brief Log error with error code.
+     *
+     * @deprecated Since v1.0.0. Use `thread_context::log()` with a
+     * `common::interfaces::ILogger` implementation instead. Will be
+     * removed in v2.0.0.
      */
     template<typename ErrorType>
+    [[deprecated(
+        "Use 'thread_context::log()' with 'common::interfaces::ILogger' "
+        "instead. Will be removed in v2.0.")]]
     void log_error(std::string_view thread_name, const ErrorType& error) {
         // Early return during shutdown
         if (is_shutting_down_.load(std::memory_order_acquire) || !enabled_) {
@@ -229,14 +273,21 @@ class thread_logger {
 
 public:
     /**
-     * @brief Enable lightweight mode (disables all logging for maximum performance)
+     * @brief Enable lightweight mode (disables all logging for maximum performance).
      *
      * In lightweight mode, all log calls become no-ops with minimal overhead.
      * Useful for performance-critical production deployments where diagnostics
      * are handled externally.
      *
      * @param enabled true to enable lightweight mode, false to use normal logging
+     *
+     * @deprecated Since v1.0.0. With `common::interfaces::ILogger`, a
+     * null logger in `thread_context` achieves the same effect without
+     * this toggle. Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Use a null 'common::interfaces::ILogger' in thread_context to "
+        "disable logging. Will be removed in v2.0.")]]
     void set_lightweight_mode(bool enabled) {
         lightweight_mode_ = enabled;
         // Disable logging when in lightweight mode
@@ -246,8 +297,14 @@ class thread_logger {
     }
 
     /**
-     * @brief Check if in lightweight mode
+     * @brief Check if in lightweight mode.
+     *
+     * @deprecated Since v1.0.0. See `set_lightweight_mode` deprecation.
+     * Will be removed in v2.0.0.
      */
+    [[deprecated(
+        "Superseded by 'common::interfaces::ILogger' injection. "
+        "Will be removed in v2.0.")]]
     bool is_lightweight_mode() const {
         return lightweight_mode_;
     }

include/kcenon/thread/lockfree/lockfree_queue.h

@@ -48,5 +48,15 @@
 
 #pragma once
 
+#if !defined(THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING) \
+    && !defined(KCENON_THREAD_LOCKFREE_QUEUE_H_WARNED)
+#define KCENON_THREAD_LOCKFREE_QUEUE_H_WARNED 1
+#if defined(_MSC_VER)
+#pragma message("<kcenon/thread/lockfree/lockfree_queue.h> is deprecated since v1.0.0 and will be removed in v2.0.0. Include <kcenon/thread/concurrent/concurrent_queue.h> instead. Define THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING to silence this warning.")
+#elif defined(__GNUC__) || defined(__clang__)
+#pragma message "<kcenon/thread/lockfree/lockfree_queue.h> is deprecated since v1.0.0 and will be removed in v2.0.0. Include <kcenon/thread/concurrent/concurrent_queue.h> instead. Define THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING to silence this warning."
+#endif
+#endif
+
 // Include the new location
 #include <kcenon/thread/concurrent/concurrent_queue.h>

src/modules/queue.cppm

@@ -38,6 +38,11 @@ module;
 #include <kcenon/thread/core/job_queue.h>
 #include <kcenon/thread/queue/adaptive_job_queue.h>
 #include <kcenon/thread/queue/queue_factory.h>
+
+// The legacy lockfree_queue.h re-exports concurrent_queue under the old
+// name for backward compatibility. Suppress its deprecation notice here
+// because the module itself is the authorized re-exporter.
+#define THREAD_SUPPRESS_LEGACY_LOCKFREE_QUEUE_WARNING 1
 #include <kcenon/thread/lockfree/lockfree_queue.h>
 #include <kcenon/thread/lockfree/lockfree_job_queue.h>
 #include <kcenon/thread/lockfree/work_stealing_deque.h>