From 36277f26ef3e9494ec3dc5677714848592583b2b Mon Sep 17 00:00:00 2001
From: Gaspard Kirira <gaspardkirira9@gmail.com>
Date: Sun, 25 Jan 2026 16:04:15 +0300
Subject: [PATCH 1/3] docs(core): document Vix Console contract and integrate
 core console module

- Add professional documentation for Vix Console (Node-like, dev-proof, zero-config)
- Describe guarantees, performance model, I/O constraints, and anti-spam behavior
- Register updated core module containing vix::console implementation
- Clarify that console is runtime/dev-only and not a production logger
---
 docs/console.md | 333 ++++++++++++++++++++++++++++++++++++++++++++++++
 modules/core    |   2 +-
 2 files changed, 334 insertions(+), 1 deletion(-)
 create mode 100644 docs/console.md

diff --git a/docs/console.md b/docs/console.md
new file mode 100644
index 0000000..2fe0b1a
--- /dev/null
+++ b/docs/console.md
@@ -0,0 +1,333 @@
+# Vix Console (core)
+
+Vix Console is a **Node.js-like runtime console** designed for **developer-facing output**: quick feedback, local debugging, and lightweight observability during development.
+
+It is intentionally **not** a production logger. For structured logs, persistence, ingestion, and production-grade pipelines, use **`vix::utils::Logger`** (modules/utils).
+
+---
+
+## Goals (what Vix Console guarantees)
+
+Vix Console is built around a “Dev-proof / Node-like trust contract”:
+
+- **Zero-config**: usable immediately after `#include <vix/console.hpp>`.
+- **Node-like DX**: `log/info/warn/error/debug` with familiar semantics.
+- **Safe defaults**:
+  - Default level = `info`
+  - `debug` is **OFF** by default
+  - `warn/error` → `stderr`
+  - `log/info/debug` → `stdout`
+- **Stable behavior**:
+  - Environment variables are read **once** (startup / first use).
+  - No “magical reconfiguration” mid-execution.
+- **Performance-safe**:
+  - **If a level is filtered, the call is near-zero cost** (no formatting, no timestamp, no lock, no I/O).
+- **Thread-safe, readable output**:
+  - Each call emits **one atomic line** (no interleaving between threads).
+- **Minimalism**:
+  - No files, no JSON by default, no heavy dependencies.
+
+---
+
+## Non-goals (what it is not)
+
+Vix Console does **not** aim to:
+
+- be a production logging system
+- write to files
+- provide JSON/KV structured output by default
+- integrate with ingestion pipelines (ELK, OpenTelemetry, etc.)
+- guarantee non-blocking I/O under all environments
+- replace or compete with `vix::utils::Logger`
+
+---
+
+## Quick start
+
+```cpp
+#include <vix/console.hpp>
+
+int main() {
+  vix::console.log("Hello");
+  vix::console.info("Server started on", 8080);
+  vix::console.warn("Deprecated API used:", "/v1/users");
+  vix::console.error("Crash detected:", "segfault");
+  vix::console.debug("x =", 42); // debug is OFF by default
+}
+```
+
+Expected output format (stable):
+
+```
+HH:MM:SS [info]  Hello
+HH:MM:SS [info]  Server started on 8080
+HH:MM:SS [warn]  Deprecated API used: /v1/users
+HH:MM:SS [error] Crash detected: segfault
+```
+
+---
+
+## API and semantics
+
+### Methods
+
+- `console.log(...)`
+- `console.info(...)`
+- `console.warn(...)`
+- `console.error(...)`
+- `console.debug(...)`
+
+### Level policy
+
+- `log` **==** `info`
+- Default visibility:
+  - `info/warn/error`: **visible**
+  - `debug`: **hidden**
+- Stream routing:
+  - `warn` + `error` → **stderr**
+  - `log` + `info` + `debug` → **stdout**
+
+This routing aligns with standard UNIX expectations and enables common redirection patterns.
+
+---
+
+## Environment variables (read once, stable)
+
+Vix Console supports environment-driven configuration without code changes.
+
+### `VIX_CONSOLE_LEVEL`
+
+Controls the initial minimum level.
+
+Supported values:
+
+- `debug`
+- `info`
+- `warn`
+- `error`
+- `off`
+
+Examples:
+
+```bash
+VIX_CONSOLE_LEVEL=debug ./app
+VIX_CONSOLE_LEVEL=warn  ./app
+VIX_CONSOLE_LEVEL=off   ./app
+```
+
+**Stability rule**: environment is read once (startup / first use).
+Changing environment variables during runtime must not cause “mid-flight” behavior changes.
+
+### Color control
+
+Vix Console follows widely adopted conventions:
+
+- `NO_COLOR`
+  If set, colors are disabled unconditionally.
+- `VIX_COLOR=auto|always|never`
+  - `auto` (default): colors only when writing to a TTY
+  - `always`: force colors
+  - `never`: disable colors
+
+Notes:
+- When output is piped to files / CI log collectors, `auto` typically disables colors to preserve readability.
+
+---
+
+## Performance model (critical contract)
+
+### The golden rule
+
+**If a level is filtered, the call is near-zero cost.**
+
+When a level is disabled (example: `debug` off by default), Vix Console guarantees:
+
+- no message construction
+- no heap allocation
+- no concatenation
+- no formatting stream (`ostringstream`)
+- no timestamp generation
+- no lock acquisition
+- no I/O
+
+This is the primary reason developers can safely leave `console.debug(...)` in code paths without fearing “silent performance cliffs”.
+
+### Practical guidance
+
+- `console.debug(...)` is designed to be “almost free” when disabled.
+- `console.info/log(...)` in hot loops can still be expensive because:
+  - it performs I/O
+  - it may lock
+  - output sinks can block (pipes, collectors)
+
+For performance-sensitive paths, keep high-frequency logging behind explicit guards or prefer dedicated telemetry mechanisms.
+
+---
+
+## Thread safety and atomic lines
+
+### Guarantee
+
+Each call to `console.*` emits a **single atomic line**, preventing log interleaving across threads.
+
+This improves readability in multi-threaded servers and avoids partial line corruption.
+
+### Implication
+
+- A mutex is used internally.
+- The mutex duration is minimized by building the line outside the lock when possible.
+
+---
+
+## I/O behavior and constraints (important)
+
+### Best-effort I/O
+
+`stdout` and `stderr` are inherently environment-dependent:
+
+- In TTY: typically buffered lightly
+- In pipes / Docker / CI / journald: may be buffered differently and can block
+- In overloaded collectors: can become slow
+
+Vix Console follows a **best-effort** approach:
+
+- avoids aggressive flushing by default
+- writes one line at a time to reduce interleaving
+- remains no-throw and never crashes an app intentionally
+
+### Flush policy
+
+Flushing after every line can create a severe performance cliff.
+
+Default policy:
+
+- **No flush per line** (to avoid synchronous penalties)
+- Optional flush may be applied for `error` only (implementation-dependent) to increase visibility before crashes
+
+---
+
+## Ordering guarantees
+
+- Ordering is guaranteed **within the same stream**:
+  - `stdout` lines preserve order relative to other `stdout` lines
+  - `stderr` lines preserve order relative to other `stderr` lines
+- Ordering between `stdout` and `stderr` is **not guaranteed** due to independent buffering and collectors.
+
+If strict ordering is required, route everything to one stream (or use a production logger with ordering semantics).
+
+---
+
+## Anti-spam protection (dev-proof)
+
+### Why it exists
+
+Many developers coming from Node.js/Python/PHP will naturally write:
+
+```cpp
+while (...) {
+  vix::console.log("tick");
+}
+```
+
+In C++ server workloads, this can destroy throughput.
+
+### Policy
+
+Vix Console may apply a minimal **rate limit** for `log/info` when volume becomes abnormal.
+
+- Affected: `log`, `info`
+- Not affected: `warn`, `error` (never suppressed)
+- Behavior when active:
+  - excessive `log/info` lines are suppressed
+  - at most **once per second**, Vix Console prints a summary line:
+
+Example:
+
+```
+HH:MM:SS [warn] (console) suppressed 153 log/info lines (rate limit)
+```
+
+This preserves performance and signals misuse without turning console into a full logger.
+
+---
+
+## Reliability notes (crash/shutdown)
+
+- Vix Console is **no-throw** (it must never throw exceptions).
+- In a hard crash (SIGKILL, power loss, abrupt termination), some output can be lost.
+- `error` lines may be more likely to be visible depending on the environment and flush policy.
+
+---
+
+## Recommended usage patterns
+
+### Good
+
+- quick startup messages
+- “what’s happening” output in dev mode
+- warnings about deprecated APIs or unexpected states
+- error reporting when a subsystem fails
+
+### Avoid
+
+- high-frequency logs in hot loops
+- using console as an audit trail
+- using console for production observability pipelines
+
+If your needs include retention, filtering, sampling, structured fields, or ingestion, switch to `vix::utils::Logger`.
+
+---
+
+## Integration
+
+### Include
+
+Use:
+
+```cpp
+#include <vix/console.hpp>
+```
+
+This exposes the global singleton:
+
+```cpp
+vix::console
+```
+
+### Umbrella headers
+
+Vix may also include console in higher-level umbrella headers (e.g., `core.hpp` / `vix.hpp`) to make it available by default in Vix applications.
+
+---
+
+## FAQ
+
+### Is Vix Console asynchronous?
+
+No. Console output is fundamentally I/O-bound and depends on the output sink.
+Vix Console minimizes overhead and avoids flush cliffs, but it does not attempt to make `stdout/stderr` non-blocking “by magic”.
+
+### Why not auto-enable debug by default?
+
+Because it would be a silent performance hazard in production-like workloads.
+The default (`info`) preserves developer signal while protecting runtime performance.
+
+### Why not structured JSON by default?
+
+Because console is meant to be minimal and stable across environments.
+Production logging and structured pipelines belong to `vix::utils::Logger`.
+
+---
+
+## Summary
+
+Vix Console provides a **safe, stable, zero-config**, Node-like console designed for runtime/dev usage:
+
+- trusted defaults
+- filtered == near-free
+- thread-safe atomic lines
+- environment config read once
+- minimal anti-spam guardrails
+
+For production logging, use `vix::utils::Logger`.
+
diff --git a/modules/core b/modules/core
index 1740475..664dabc 160000
--- a/modules/core
+++ b/modules/core
@@ -1 +1 @@
-Subproject commit 17404752674c8006acd0a2d509051b9115108331
+Subproject commit 664dabc768f9f6049c3f0cb42b5d2e68e8fb9bfe

From c58af4e788af51750945ffa09cbfd1e97ee2aa93 Mon Sep 17 00:00:00 2001
From: Gaspard Kirira <gaspardkirira9@gmail.com>
Date: Sun, 25 Jan 2026 16:21:26 +0300
Subject: [PATCH 2/3] docs(console): clarify scope, non-goals, and logger
 separation

- Explicitly document that Vix Console is intentionally minimal and Node-like in spirit
- Clarify that advanced console features (table, group, time, count, assert) are out of scope
- Direct users to vix::utils::Logger for structured, performance, and production-grade debugging
- Document precedence between VIX_CONSOLE_LEVEL and VIX_LOG_LEVEL to avoid ambiguity
- Reinforce stable, dev-proof usage guidelines
---
 docs/console.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/docs/console.md b/docs/console.md
index 2fe0b1a..e722863 100644
--- a/docs/console.md
+++ b/docs/console.md
@@ -40,6 +40,17 @@ Vix Console does **not** aim to:
 - guarantee non-blocking I/O under all environments
 - replace or compete with `vix::utils::Logger`
 
+## What Vix Console is NOT (by design)
+
+Vix Console intentionally does **not** replicate the full JavaScript `console.*` API
+such as `console.table`, `console.group`, `console.time`, or `console.count`.
+
+Those features require shared mutable state, heavy formatting, or implicit timing,
+which are unsafe or unpredictable in a multi-threaded C++ runtime.
+
+For advanced debugging, structured output, performance analysis, or production-grade
+instrumentation, use **`vix::utils::Logger`** instead.
+
 ---
 
 ## Quick start
@@ -98,6 +109,9 @@ Vix Console supports environment-driven configuration without code changes.
 ### `VIX_CONSOLE_LEVEL`
 
 Controls the initial minimum level.
+> **Note (default behavior):** `VIX_CONSOLE_LEVEL` is an advanced, manual override.
+> When unset, `vix::console` follows `VIX_LOG_LEVEL`, which is typically set by the Vix CLI.
+This keeps a single “verbosity control” for most users (`--log-level`), while still allowing expert overrides.
 
 Supported values:
 
@@ -275,6 +289,8 @@ This preserves performance and signals misuse without turning console into a ful
 - using console for production observability pipelines
 
 If your needs include retention, filtering, sampling, structured fields, or ingestion, switch to `vix::utils::Logger`.
+If you find yourself wanting tables, counters, timers, or grouped output,
+this is a signal to switch from `vix::console` to `vix::utils::Logger`.
 
 ---
 

From 05685024fe5a73cbdbf0db75ffa2e6f6579eabcb Mon Sep 17 00:00:00 2001
From: Gaspard Kirira <gaspardkirira9@gmail.com>
Date: Sun, 25 Jan 2026 16:40:48 +0300
Subject: [PATCH 3/3] v1.22.0 Runtime Console & DX Stabilization

---
 CHANGELOG.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 107 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e891241..aee7eec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,113 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ---
 
 ## [Unreleased]
+## v1.22.0 — Runtime Console & DX Stabilization
+
+**Release focus:** developer experience, runtime safety, and clear separation between dev console and production logging.
+
+---
+
+## ✨ New
+
+## Vix Console (core)
+
+Introduces a Node.js–inspired, **zero-config runtime console** available directly via:
+
+```cpp
+#include <vix/console.hpp>
+
+vix::console.log("Hello");
+```
+
+Designed for **developer-facing output** with **strict runtime guarantees**.
+
+---
+
+## 🧠 Design & Runtime Guarantees
+
+## Zero configuration by default
+
+- Console works immediately after `#include`
+- No init calls
+- No setup required
+
+## Safe defaults
+
+- Default level: `info`
+- `debug` **OFF** by default
+- `log == info`
+- `warn` / `error` → `stderr`
+- `log` / `info` / `debug` → `stdout`
+
+## Performance contract
+
+- If a level is filtered, the call is **near-zero cost**
+  - No message construction
+  - No allocation
+  - No lock
+  - No I/O
+
+## Thread-safe, atomic output
+
+- Each console call emits a **single atomic line**
+
+## Stable environment configuration
+
+- Supports:
+  - `VIX_CONSOLE_LEVEL`
+  - `NO_COLOR`
+  - `VIX_COLOR`
+- Environment is read **once** (startup / first use)
+- Behavior is fixed afterward
+
+## Minimal anti-spam protection
+
+- Prevents accidental performance collapse from excessive `log` / `info` usage
+- `warn` and `error` are **never suppressed**
+
+---
+
+## 📖 Documentation
+
+## New documentation: Vix Console
+
+- Clearly defines:
+  - Scope
+  - Guarantees
+  - Constraints
+  - Non-goals
+
+## Explicit separation
+
+- `vix::console` → runtime / developer output
+- `vix::utils::Logger` → production logging, structured output
+
+## Clarified non-goals
+
+- No `console.table`
+- No `console.group`
+- No `console.time`
+- No `console.count`
+
+Advanced debugging and observability belong to `vix::utils::Logger`.
+
+---
+
+## 🔒 Philosophy Clarification
+
+- Vix Console is **intentionally not a production logger**
+- Borrows **Node.js developer trust**
+- Enforces **C++ runtime discipline**
+- Designed to be safe **even if developers do not read documentation**
+
+---
+
+## 🔗 Commits
+
+- `docs(core): document Vix Console contract and integrate core console module`
+- `docs(console): clarify scope, non-goals, and logger separation`
+
+
 ## v1.21.1
 - chore(cli): bump CLI submodule to v1.19.12 (cleaner sanitizer output, unified timeout logic, refined code frames)
 - docs/examples: add `examples/vix_routes_showcase.cpp` (HTTP routes + query params showcase)