From 4138b3cad8122c5333c51f6b41b8a85dd2d767d5 Mon Sep 17 00:00:00 2001
From: Mario Fetka <mario.fetka@gmail.com>
Date: Tue, 2 Jun 2026 08:36:39 +0000
Subject: [PATCH] docs: clarify nwlog facade file layout

---
 REDESIGN.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 58 insertions(+), 7 deletions(-)

diff --git a/REDESIGN.md b/REDESIGN.md
index 7ef471e..c09e4f0 100644
--- a/REDESIGN.md
+++ b/REDESIGN.md
@@ -1383,18 +1383,69 @@ typedef enum {
 } NwLogCategory;
 ```
 
-Conceptual call sites should look like:
+Conceptual call sites should be short and category-specific, not manual
+construction of large event structures in every handler:
 
 ```c
-nwlog_info(NWLOG_HANDOFF, ctx,
-           "provider=%s request_id=%u selector=%s handoff=start",
-           provider_name, request_id, selector_path);
+nwlog_handoff(ctx, NWLOG_INFO,
+              "provider=%s request_id=%u selector=%s handoff=start",
+              provider_name, request_id, selector_path);
 
-nwlog_warn(NWLOG_RECOVERY, ctx,
-           "admin password recovery requested dn=%s uid=%lu",
-           redacted_dn, (unsigned long)uid);
+nwlog_recovery(ctx, NWLOG_WARN,
+               "admin password recovery requested dn=%s uid=%lu",
+               redacted_dn, (unsigned long)uid);
+
+nwlog_ncp(ctx, NWLOG_DEBUG,
+          "reply completion=0x%02x len=%u", completion, reply_len);
+
+nwlog_directory(ctx, NWLOG_INFO,
+                "schema migration step=%s", step_name);
 ```
 
+The implementation can still normalize all events through a shared internal
+structure before they reach a backend:
+
+```c
+struct nwlog_event {
+  NwLogCategory category;
+  NwLogLevel level;
+  const char *module;
+  const char *file;
+  int line;
+
+  uint32_t connection_id;
+  uint32_t request_id;
+  uint32_t sequence;
+  uint32_t task_id;
+
+  const char *ncp_path;
+  const char *provider;
+  const char *message;
+};
+
+void nwlog_emit(const struct nwlog_event *event);
+```
+
+Normal endpoint and provider code should use wrappers such as `nwlog_ncp()`,
+`nwlog_handoff()`, `nwlog_bindery()`, `nwlog_queue()`, `nwlog_directory()`,
+`nwlog_nds()`, `nwlog_ldap()`, `nwlog_auth()`, `nwlog_acl()`,
+`nwlog_recovery()`, and `nwlog_security()`.  Those wrappers populate the shared
+`nwlog_event` fields from the current NCP/provider context and pass the result to
+`nwlog_emit()`.  Only unusual code paths should build `nwlog_event` manually.
+
+The project-level layout should follow the existing include/source split:
+
+```text
+include/nwlog.h   public internal logging facade used by mars-nwe modules
+src/nwlog.c       facade implementation, redaction, common formatting
+src/nwlog_zlog.c  optional zlog backend, if enabled at build time
+src/nwlog_syslog.c or built-in backend code for simple builds
+```
+
+Protocol handlers, providers, `nwconn`, `nwserv`, `nwbind`, future `nwqueue`,
+`nwdirectory`, and `nwnds` should include `include/nwlog.h` only.  They should
+not include zlog headers or call zlog macros directly.
+
 That facade can initially keep using the existing mars-nwe logging functions,
 `stderr`, or `syslog`.  Later it may use an advanced backend.