docs: describe libnwnss integration boundaries

REDESIGN.md

@@ -14,6 +14,7 @@ major design areas.
 | DOS namespace adaptation | 🟨 Active next | Adapt NSS DOS namespace semantics before broad 4.x work. |
 | LONG/OS2 namespace adaptation | ⬜ Later | Start after DOS namespace is stable. |
 | Salvage metadata/export model | 🟨 Planned | Keep `.recycle` compatibility, add NSS-shaped deleted metadata/xattrs for backup tools through shared libnwcore/libnwfs helpers. |
+| libnwnss semantic provider | 🟨 Planned | Use libnwnss first for names, Unicode, rights, xattrs, AdminVolume and reply-buffer ownership hooks; keep COMN file I/O for later. |
 | NCP dispatch context cleanup | ⬜ Later | Replace magic forwarding results with named dispatch results and a typed request context. |
 | Isolated live-test environment | ⬜ Later | Use the CMake/test build with generated SYS/QUOTA images once transport can run without host IPX. |
 
@@ -623,6 +624,83 @@ This is especially important for nested selector families and old/new endpoint
 variants, where a provider may need to choose different reply structures based on
 a level, verb, or information type.
 
+### NCP reply allocator boundary
+
+The imported NSS low-level library contains the real `mallocForNCPReply` and
+`freeForNCPReply` entry points.  Their original purpose is not to provide a
+separate NSS pool; it is to allocate reply memory outside NSS internal malloc
+debug/tracking because the NetWare NCP handler may own and free generated reply
+buffers.
+
+In current MARS-NWE, normal NCP replies are built in the existing connection
+reply buffers, so `libnwnss` should keep its userspace implementation as a plain
+external allocator boundary (`malloc`/`free`) rather than trying to route through
+`nwconn` or the MARS helper allocators.  Do not use `xmalloc` here: NSS callers
+expect allocation failure to be a return value, not a process exit.
+
+The design value is future ownership, not immediate replacement.  If a later
+provider path lets `libnwnss` or an NSS-shaped service generate client-visible
+NCP reply payloads, `mallocForNCPReply` is the right semantic hook for those
+buffers:
+
+```text
+MARS-NWE NCP request
+  -> libnwnss / provider builds a logical reply payload
+  -> nwconn owns the final NCP response envelope and transport send
+  -> the reply-buffer owner frees through the matching NCP-reply free path
+```
+
+At that point the backend may become a MARS reply-buffer pool, a zero-copy send
+buffer, or a statistics/debug wrapper.  Until such a handoff exists, keep the
+function as a documented boundary and do not make it an active dependency from
+MARS connection code into `libnwnss`.
+
+### libnwnss as a future MARS-NWE semantics provider
+
+The useful long-term dependency direction is not to route all MARS-NWE file I/O
+or all NCP replies through `libnwnss` immediately.  MARS-NWE should remain the
+connection/session/transport owner, while `libnwnss` grows into the provider for
+NSS/NetWare semantics that are currently hard to keep compatible in scattered
+MARS code.
+
+Good future integration points are:
+
+- namespace and Unicode handling: DOS/LONG/UNIX/MAC namespace startup, short-name
+  generation, case rules and NSS Unicode conversion should become reusable
+  helpers before broad 4.x endpoint work depends on name semantics;
+- trustee, inherited-rights and effective-rights calculation: MARS endpoint code
+  should eventually ask one shared NSS-shaped rights engine instead of carrying
+  independent interpretations in several protocol handlers;
+- EA/XATTR and NSS metadata export: `netware.metadata`, `netware.ncpstat`, quota
+  views and Mac metadata should serialize the same state used by NCP handlers,
+  backup tools and host-side admin views;
+- AdminVolume / `_ADMIN`: first bring this up inside `libnwnss` as in-memory
+  AdminVolume and namespace state, then expose it through a small `nwadminvol`
+  smoke harness, and only later connect it to `nwconn` or a provider process;
+- NCP reply buffers: keep `mallocForNCPReply` as a documented ownership hook so
+  an NSS-shaped provider can later hand reply payload buffers to the MARS NCP
+  layer without forcing normal `nwconn` replies to use `libnwnss` today;
+- COMN file I/O: treat this as a later backend/provider candidate, not the first
+  integration step.  The current MARS host-filesystem paths should not be
+  replaced until the `libnwnss` virtual-I/O boundary, metadata state and tests are
+  strong enough.
+
+This makes `libnwnss` a semantics layer first and a storage engine only later:
+
+```text
+MARS-NWE transport / NCP session / endpoint dispatch
+  -> MARS providers or libnwfs bridge
+  -> libnwnss for NSS names, rights, metadata, AdminVolume and future reply
+     ownership hooks
+  -> host xattrs, sidecar state, virtual I/O or later storage backends
+```
+
+The rule for future patches is to integrate one semantic seam at a time.  Do not
+make `nwconn` depend on low-level `libnwnss` allocation or COMN file-I/O helpers
+just because the symbols exist.  Add an integration only when the caller can name
+the NSS semantic it needs, when ownership is clear, and when tests cover both the
+old MARS-visible behavior and the new NSS-shaped provider result.
+
 ### Logging and audit benefit
 
 A normalized handoff reply gives logging one consistent shape: