util/time.c

Go to the documentation of this file.

 
#include "ascii-chat/common/error_codes.h"
#include <ascii-chat/util/time.h>
 
#undef SOKOL_TIME_INCLUDED
#define SOKOL_TIME_IMPL
#include <ascii-chat-deps/sokol/sokol_time.h>
#include <ascii-chat/common.h>
#include <ascii-chat/asciichat_errno.h>
#include <ascii-chat/util/lifecycle.h>
#include <ascii-chat/platform/rwlock.h>
#include <ascii-chat/platform/abstraction.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <time.h>
#include <ctype.h>
#include <ascii-chat/atomic.h>
 
// ============================================================================
// Global State
// ============================================================================
 
static struct {
  timer_record_t *timers; 
  rwlock_t rwlock;        
  lifecycle_t lifecycle;  
} g_timer_manager = {
    .timers = NULL,
    .lifecycle = LIFECYCLE_INIT,
};
 
static bool g_sokol_time_initialized = false;
 
// ============================================================================
// Human-Readable Time Formatting Helper
// ============================================================================
 
static int format_human_readable_time_ago(double total_seconds, int minutes, int hours, int days, int months, int years,
                                          const char *suffix, char *buffer, size_t buffer_size) {
  int written = 0;
 
  if (total_seconds < 3) {
    written = safe_snprintf(buffer, buffer_size, "a moment %s", suffix);
  } else if (total_seconds < 10) {
    written = safe_snprintf(buffer, buffer_size, "a few seconds %s", suffix);
  } else if (total_seconds < 45) {
    written = safe_snprintf(buffer, buffer_size, "%d seconds %s", (int)total_seconds, suffix);
  } else if (total_seconds < 90) {
    written = safe_snprintf(buffer, buffer_size, "a minute %s", suffix);
  } else if (minutes < 45) {
    written = safe_snprintf(buffer, buffer_size, "%d minutes %s", minutes, suffix);
  } else if (minutes < 90) {
    written = safe_snprintf(buffer, buffer_size, "an hour %s", suffix);
  } else if (hours < 22) {
    written = safe_snprintf(buffer, buffer_size, "%d hours %s", hours, suffix);
  } else if (hours < 36) {
    written = safe_snprintf(buffer, buffer_size, "a day %s", suffix);
  } else if (days < 25) {
    written = safe_snprintf(buffer, buffer_size, "%d days %s", days, suffix);
  } else if (days < 45) {
    written = safe_snprintf(buffer, buffer_size, "a month %s", suffix);
  } else if (months < 11) {
    written = safe_snprintf(buffer, buffer_size, "%d months %s", months, suffix);
  } else if (months < 18) {
    written = safe_snprintf(buffer, buffer_size, "a year %s", suffix);
  } else {
    written = safe_snprintf(buffer, buffer_size, "%d years %s", years, suffix);
  }
 
  return written;
}
 
// ============================================================================
// Core Monotonic Timing Implementation
// ============================================================================
 
uint64_t time_get_ns(void) {
  // sokol_time provides monotonic clock that never goes backwards
  // stm_ns() converts ticks to nanoseconds
  // Ensure sokol_time is initialized before use (defensive programming)
  if (!g_sokol_time_initialized) {
    stm_setup();
    g_sokol_time_initialized = true;
  }
  return (uint64_t)stm_ns(stm_now());
}
 
uint64_t time_get_realtime_ns(void) {
#ifdef _WIN32
  // Windows: Use GetSystemTimePreciseAsFileTime (Win8+) for high-precision wall clock
  // FILETIME is 100-nanosecond intervals since January 1, 1601
  FILETIME ft;
  GetSystemTimePreciseAsFileTime(&ft);
  // Convert FILETIME to nanoseconds
  uint64_t filetime = ((uint64_t)ft.dwHighDateTime << 32) | ft.dwLowDateTime;
  // Convert 100-nanosecond intervals to nanoseconds
  return filetime * 100;
#else
  // Get wall-clock (real-time) timestamp
  struct timespec ts;
  if (clock_gettime(CLOCK_REALTIME, &ts) != 0) {
    // Fallback on error (unlikely)
    return 0;
  }
  return time_timespec_to_ns(&ts);
#endif
}
 
void time_sleep_ns(uint64_t ns) {
  // Use platform abstraction for cross-platform sleep
  // Convert nanoseconds to microseconds (1 us = 1000 ns)
  unsigned int usec = (unsigned int)(ns / 1000);
  if (usec == 0 && ns > 0) {
    usec = 1; // Minimum 1 microsecond
  }
  platform_sleep_us(usec);
}
 
uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns) {
  // Handle wraparound (defensive - uint64_t won't wrap in practice at nanosecond resolution)
  // but this is safe and handles any theoretical edge cases
  if (end_ns >= start_ns) {
    return end_ns - start_ns;
  }
  // Wraparound case (extremely unlikely)
  return (UINT64_MAX - start_ns) + end_ns + 1;
}
 
// ============================================================================
// Conversion Functions (moved from inline in header to avoid circular deps)
// ============================================================================
 
uint64_t time_timespec_to_ns(const struct timespec *ts) {
  if (!ts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null ts");
    return 0;
  }
  // Use __uint128_t to prevent overflow during multiplication of large time values
  __uint128_t result = (__uint128_t)ts->tv_sec * NS_PER_SEC_INT;
  if (result > UINT64_MAX) {
    SET_ERRNO(ERROR_INVALID_PARAM, "time_timespec_to_ns: timespec value would overflow");
    return UINT64_MAX;
  }
  return (uint64_t)result + (uint64_t)ts->tv_nsec;
}
 
void time_ns_to_timespec(uint64_t ns, struct timespec *ts) {
  if (!ts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null ts");
    return;
  }
  ts->tv_sec = (time_t)(ns / NS_PER_SEC_INT);
  ts->tv_nsec = (long)(ns % NS_PER_SEC_INT);
}
 
// ============================================================================
// Timer System Implementation
// ============================================================================
 
bool timer_system_init(void) {
  if (lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return true;
  }
 
  // Initialize sokol_time
  stm_setup();
 
  // Initialize rwlock and lifecycle together
  g_timer_manager.lifecycle.sync_type = LIFECYCLE_SYNC_RWLOCK;
  g_timer_manager.lifecycle.sync.rwlock = &g_timer_manager.rwlock;
  if (!lifecycle_init(&g_timer_manager.lifecycle, "timer_manager")) {
    SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize timer system (already initialized by another thread)");
    return true; // Another thread already initialized it
  }
 
  g_timer_manager.timers = NULL;
 
  log_dev("Timer system initialized");
  return true;
}
 
void timer_system_destroy(void) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Free all timer records
  int timer_count = 0;
  timer_record_t *current, *tmp;
  HASH_ITER(hh, g_timer_manager.timers, current, tmp) {
    HASH_DEL(g_timer_manager.timers, current);
    SAFE_FREE(current->name);
    SAFE_FREE(current);
    timer_count++;
  }
 
  g_timer_manager.timers = NULL;
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
 
  /* Shutdown lifecycle and destroy rwlock together */
  lifecycle_shutdown(&g_timer_manager.lifecycle);
 
  log_debug("Timer system cleaned up (freed %d timers)", timer_count);
}
 
bool timer_start(const char *name) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return false;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return false;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Check if timer already exists - this is an error, timers must be unique
  timer_record_t *existing = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, existing);
 
  if (existing) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_INVALID_STATE, "Timer '%s' already exists - timers must have unique names", name);
    return false;
  }
 
  // Create new timer record
  timer_record_t *timer = SAFE_MALLOC(sizeof(timer_record_t), timer_record_t *);
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer record");
    return false;
  }
 
  // Use platform-safe string duplication
  size_t name_len = strlen(name) + 1;
  timer->name = SAFE_MALLOC(name_len, char *);
  if (!timer->name) {
    SAFE_FREE(timer);
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer name");
    return false;
  }
  SAFE_STRNCPY(timer->name, name, name_len);
 
  timer->start_ticks = stm_now();
 
  // Add to hashtable
  HASH_ADD_KEYPTR(hh, g_timer_manager.timers, timer->name, strlen(timer->name), timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return true;
}
 
double timer_stop(const char *name) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return -1.0;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return -1.0;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Find timer
  timer_record_t *timer = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, timer);
 
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    log_dev("Timer '%s' not found (may have already been stopped)", name);
    return -1.0;
  }
 
  // Calculate elapsed time in nanoseconds for maximum precision
  uint64_t end_ticks = stm_now();
  uint64_t elapsed_ticks = stm_diff(end_ticks, timer->start_ticks);
  double elapsed_ns = stm_ns(elapsed_ticks);
 
  // Format duration for human-readable logging
  char duration_str[32];
  time_pretty((uint64_t)elapsed_ns, -1, duration_str, sizeof(duration_str));
 
  // Log the result (dev level - only shown with --verbose)
  log_dev("Timer '%s': %s", name, duration_str);
 
  // Save pointers to free BEFORE removing from hashtable
  char *timer_name = timer->name;
 
  // Remove from hashtable (HASH_DEL only removes from hash, doesn't free memory)
  HASH_DEL(g_timer_manager.timers, timer);
 
  // Free timer->name first (this was allocated separately)
  SAFE_FREE(timer_name);
 
  // Nullify the timer->name field so debug_free doesn't try to access it
  // when freeing the timer structure itself
  timer->name = NULL;
 
  // Free the timer record itself
  SAFE_FREE(timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return elapsed_ns; // Return nanoseconds
}
 
bool timer_is_initialized(void) {
  return lifecycle_is_initialized(&g_timer_manager.lifecycle);
}
 
// ============================================================================
// Time Formatting Implementation
// ============================================================================
 
int format_uptime_hms(int hours, int minutes, int seconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Validate components
  if (hours < 0 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60) {
    return -1;
  }
 
  // Format as HH:MM:SS with zero-padding
  int written = safe_snprintf(buffer, buffer_size, "%02d:%02d:%02d", hours, minutes, seconds);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
// ============================================================================
// Pretty Time Formatting with Spaces and Configurable Precision
// ============================================================================
 
static int strip_trailing_zeros(char *str) {
  if (!str || !*str)
    return 0;
 
  int len = (int)strlen(str);
  if (len <= 0)
    return len;
 
  // Find decimal point
  char *decimal = strchr(str, '.');
  if (!decimal)
    return len; // No decimal point
 
  // Find where the number ends (space indicates unit follows)
  char *space = strchr(decimal, ' ');
  int end_pos = space ? (int)(space - str) - 1 : len - 1;
 
  // Strip trailing zeros from the fractional part
  int pos = end_pos;
  while (pos > (int)(decimal - str) && str[pos] == '0') {
    pos--;
  }
 
  // If we end up at the decimal point itself, remove it too
  if (pos == (int)(decimal - str)) {
    pos--;
  }
 
  // Shift everything after pos (the unit) forward, or just null-terminate if no unit
  if (space) {
    // Move unit to new position
    int space_idx = (int)(space - str);
    memmove(str + pos + 1, str + space_idx, len - space_idx + 1);
  } else {
    // Just null-terminate
    str[pos + 1] = '\0';
  }
 
  return (int)strlen(str);
}
 
int time_pretty(uint64_t nanoseconds, int decimals, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Handle zero
  if (nanoseconds == 0) {
    int written = safe_snprintf(buffer, buffer_size, "0 ns");
    return (written < 0 || (size_t)written >= buffer_size) ? -1 : written;
  }
 
  // Determine decimals for this range if not explicitly set
  int actual_decimals = decimals;
  if (decimals == -1) {
    if (nanoseconds < NS_PER_MIN_INT) {
      actual_decimals = (nanoseconds < NS_PER_SEC_INT) ? 3 : 2; // ns/µs/ms or seconds
    } else {
      actual_decimals = 3; // colon notation
    }
  }
 
  // Clamp decimals to valid range
  if (actual_decimals < 0)
    actual_decimals = 0;
  if (actual_decimals > 9)
    actual_decimals = 9;
 
  int written = 0;
 
  // Nanoseconds (< 1µs)
  if (nanoseconds < NS_PER_US_INT) {
    written = safe_snprintf(buffer, buffer_size, "%llu ns", (unsigned long long)nanoseconds);
  }
  // Microseconds (< 1ms)
  else if (nanoseconds < NS_PER_MS_INT) {
    double us = (double)nanoseconds / NS_PER_US;
    char temp_buf[64];
    // Use a direct snprintf with large enough buffer first
    snprintf(temp_buf, sizeof(temp_buf), "%.*f µs", actual_decimals, us);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Milliseconds (< 1s)
  else if (nanoseconds < NS_PER_SEC_INT) {
    double ms = (double)nanoseconds / NS_PER_MS;
    char temp_buf[64];
    snprintf(temp_buf, sizeof(temp_buf), "%.*f ms", actual_decimals, ms);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Seconds (< 1 minute)
  else if (nanoseconds < NS_PER_MIN_INT) {
    double s = (double)nanoseconds / NS_PER_SEC;
    char temp_buf[64];
    snprintf(temp_buf, sizeof(temp_buf), "%.*f s", actual_decimals, s);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Minutes (< 1 hour) - use colon notation: M:SS.frac
  else if (nanoseconds < NS_PER_HOUR_INT) {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    uint64_t minutes = total_seconds / 60;
    uint64_t seconds = total_seconds % 60;
    uint64_t remainder_ns = nanoseconds % NS_PER_SEC_INT;
    double fraction = (double)remainder_ns / NS_PER_SEC;
 
    char temp_buf[64];
    if (actual_decimals == 0) {
      snprintf(temp_buf, sizeof(temp_buf), "%llu:%02llu", (unsigned long long)minutes, (unsigned long long)seconds);
    } else {
      snprintf(temp_buf, sizeof(temp_buf), "%llu:%02llu.%.*f", (unsigned long long)minutes, (unsigned long long)seconds,
               actual_decimals, fraction);
      strip_trailing_zeros(temp_buf);
    }
 
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Hours+ - use colon notation: H:MM:SS or HH:MM:SS
  else {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    uint64_t hours = total_seconds / 3600;
    uint64_t remaining = total_seconds % 3600;
    uint64_t minutes = remaining / 60;
    uint64_t seconds = remaining % 60;
 
    written = safe_snprintf(buffer, buffer_size, "%llu:%02llu:%02llu", (unsigned long long)hours,
                            (unsigned long long)minutes, (unsigned long long)seconds);
  }
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_pretty_now(int decimals, char *buffer, size_t buffer_size) {
  uint64_t ns = time_get_ns();
  return time_pretty(ns, decimals, buffer, buffer_size);
}
 
// ============================================================================
// Human-Readable Time Formatting (moment.js style)
// ============================================================================
 
int time_human_readable_unsigned(uint64_t nanoseconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)nanoseconds / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, "ago", buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_human_readable(int64_t nanoseconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Determine direction (past vs future)
  bool is_future = nanoseconds < 0;
  uint64_t abs_ns = is_future ? (uint64_t)(-nanoseconds) : (uint64_t)nanoseconds;
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)abs_ns / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  const char *suffix = is_future ? "from now" : "ago";
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, suffix, buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_human_readable_now(char *buffer, size_t buffer_size) {
  int64_t ns = (int64_t)time_get_ns();
  return time_human_readable(ns, buffer, buffer_size);
}
 
// ============================================================================
// Adaptive Sleep Implementation
// ============================================================================
 
void adaptive_sleep_init(adaptive_sleep_state_t *state, const adaptive_sleep_config_t *config) {
  if (!state || !config) {
    return;
  }
 
  // Copy configuration
  state->config = *config;
 
  // A multiplier of 1.0 preserves the configured interval. Clamp it for
  // configurations whose allowed range does not include the baseline.
  state->current_speed_multiplier = 1.0;
  if (state->current_speed_multiplier < config->min_speed_multiplier) {
    state->current_speed_multiplier = config->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > config->max_speed_multiplier) {
    state->current_speed_multiplier = config->max_speed_multiplier;
  }
 
  state->last_sleep_ns = (uint64_t)(config->baseline_sleep_ns / state->current_speed_multiplier);
}
 
uint64_t adaptive_sleep_calculate(adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth) {
  if (!state) {
    return 0;
  }
 
  const adaptive_sleep_config_t *cfg = &state->config;
 
  // Determine if we need to speed up or slow down
  double desired_multiplier;
 
  if (queue_depth > target_depth) {
    // Queue is building up - speed up processing
    // The more items in queue, the faster we should process
    size_t backlog = queue_depth - target_depth;
 
    // Calculate desired speed based on backlog
    // Each item above target increases speed proportionally
    // This ensures we drain the queue faster the more backed up we are
    double backlog_factor = 1.0 + ((double)backlog / (double)(target_depth + 1));
    desired_multiplier = cfg->min_speed_multiplier * backlog_factor;
 
    // Clamp to max speed
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_speed_multiplier;
    }
 
    // Ramp up gradually based on speedup_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->speedup_rate;
 
  } else {
    // Queue is at or below target - slow down to baseline
    desired_multiplier = 1.0;
    if (desired_multiplier < cfg->min_speed_multiplier) {
      desired_multiplier = cfg->min_speed_multiplier;
    }
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_speed_multiplier;
    }
 
    // Ramp down gradually based on slowdown_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->slowdown_rate;
  }
 
  // Ensure we stay within configured bounds
  if (state->current_speed_multiplier < cfg->min_speed_multiplier) {
    state->current_speed_multiplier = cfg->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > cfg->max_speed_multiplier) {
    state->current_speed_multiplier = cfg->max_speed_multiplier;
  }
 
  // Calculate actual sleep time: baseline / speed_multiplier
  // Higher multiplier = shorter sleep = faster processing
  uint64_t sleep_ns = (uint64_t)(cfg->baseline_sleep_ns / state->current_speed_multiplier);
 
  // Store for debugging
  state->last_sleep_ns = sleep_ns;
 
  return sleep_ns;
}
 
void adaptive_sleep_do(adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth) {
  uint64_t sleep_ns = adaptive_sleep_calculate(state, queue_depth, target_depth);
 
  if (sleep_ns > 0) {
    platform_sleep_ns(sleep_ns);
  }
}
 
/* ============================================================================
 * Time Format Validation and Formatting Implementation
 * ============================================================================ */
 
static const char SUPPORTED_SPECIFIERS[] = "YmmdHMSaAbBjwuIpZzcxXFTsGgV";
 
bool time_format_is_valid_strftime(const char *format_str) {
  if (!format_str) {
    return false;
  }
 
  for (const char *p = format_str; *p; p++) {
    if (*p == '%') {
      p++;
      if (!*p) {
        /* Unterminated % at end of string */
        log_error("Invalid time format: unterminated %% at end");
        return false;
      }
 
      if (*p == '%') {
        /* Escaped %% - this is valid, just skip it */
        continue;
      }
 
      /* Optional: flag characters (-, 0, +, space) */
      if (*p == '-' || *p == '0' || *p == '+' || *p == ' ') {
        p++;
        if (!*p) {
          log_error("Invalid time format: flag character without specifier");
          return false;
        }
      }
 
      /* Optional: width specifier (digits or *) */
      if (*p == '*' || isdigit((unsigned char)*p)) {
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: width specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: precision specifier (.digits or .*) */
      if (*p == '.') {
        p++;
        if (!*p) {
          log_error("Invalid time format: precision specifier incomplete");
          return false;
        }
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: precision specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: modifier characters (E for %Ex, O for %Ox) */
      if (*p == 'E' || *p == 'O') {
        p++;
        if (!*p) {
          log_error("Invalid time format: modifier character without specifier");
          return false;
        }
      }
 
      /* Validate that the final character is a supported specifier */
      if (!strchr(SUPPORTED_SPECIFIERS, *p)) {
        log_error("Invalid time format: unsupported specifier %%%c (at position %ld)", *p, (p - format_str));
        return false;
      }
    }
  }
 
  return true;
}
 
int time_format_now(const char *format_str, char *buf, size_t buf_size) {
  if (!format_str || !buf || buf_size < 2) {
    SET_ERRNO(ERROR_INVALID_PARAM, "time_format_now: invalid arguments - format_str=%p, buf=%p, buf_size=%zu",
              format_str, buf, buf_size);
    return 0;
  }
 
  /* Get current wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
 
  /* Extract seconds and nanoseconds */
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
 
  /* Convert seconds to struct tm */
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
 
  /* Format using strftime */
  size_t len = strftime(buf, buf_size, format_str, &tm_info);
 
  /* Check for strftime errors or buffer overflow */
  if (len == 0) {
    /* strftime returned 0 - either error or exact buffer fill */
    log_debug("strftime returned 0 for format: %s", format_str);
    return 0;
  }
 
  if (len >= buf_size - 1) {
    /* Buffer would overflow - strftime filled entire buffer or hit exact size */
    log_error("time_format_now: buffer too small (need %zu, have %zu)", len + 1, buf_size);
    return 0;
  }
 
  return (int)len;
}
 
asciichat_error_t time_format_safe(const char *format_str, char *buf, size_t buf_size) {
  /* Check NULL pointers */
  if (!format_str) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: format_str is NULL");
  }
 
  if (!buf) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: buf is NULL");
  }
 
  /* Check minimum buffer size */
  if (buf_size < 64) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: buffer too small (minimum 64 bytes, got %zu)", buf_size);
  }
 
  /* Validate format string */
  if (!time_format_is_valid_strftime(format_str)) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: invalid time format: %s", format_str);
  }
 
  /* Format the time */
  int result = time_format_now(format_str, buf, buf_size);
  if (result <= 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "time_format_safe: strftime formatting failed");
  }
 
  return ASCIICHAT_OK;
}