docs: define namespace userspace uniqueness boundary

AI.md

@@ -47,7 +47,7 @@ unfinished work out of `TODO.md` merely because its architecture is documented.
 
 Latest commit in an up-to-date tree:
 
-- `docs: update AI nwnss userspace backend guidance`
+- `docs: define namespace userspace uniqueness boundary`
 
 Compare `git log -1 --format="%s"` with this subject.  If the tree is older,
 check which COMN audit commits are missing and replay them before starting new
@@ -55,27 +55,23 @@ work.
 
 ## Current patch handoff block
 
-Last completed work block: **libnwnss userspace backend split documentation**
+Last completed work block: **namespace userspace uniqueness boundary**
 
-The COMN import/audit chain is complete and the HMC/SourceCompat/build-glue
-audit is clean.  The latest design work documents how the next XAttr/LSA and
-I/O backend imports must be split for userspace: keep original NSS files as
-close to the `nss.tar.bz2` / `nss-common.tar.bz2` sources as possible, add only
-small explicit backend decision points there, and put HostFS, OtherFS, sidecar,
-FUSE and `io_uring` policy into parallel `*Userspace.c` / `*Userspace.h`
-boundary files with NSS-like names.
+The latest design work clarifies how imported NSS namespace code should be used
+for future Mars/NWFS integration.  `libnwnss` remains the NSS namespace provider
+using the real `src/nwnss/comn/namespace` implementations.  A later `nwfs`
+wrapper will translate Mars volume options, host paths, search handles and
+compatibility policy before calling into `libnwnss`; the current half-finished
+`nwfs` namespace staging remains ignored until that cleanup phase.
 
-`virtualIO` has been rechecked and is **not** a disk/block backend.  It is the
-NSS `_ADMIN` / management virtual-file and XML datastream layer.  Future
-mountable filesystem work belongs behind FUSE/`nwnssmount`; future async
-file/block access belongs behind an explicit libnwnss backend context/vtable
-that may use `io_uring`.  XAttr/LSA imports should come from the original NSS
-archives; Novell/Micro Focus/NDK packages are reference documentation only.
-
-Next step: start the XAttr/LSA import track in `libnwnss` by importing the real
-NSS media/interface definitions such as `shared/sdk/public/zXattr.h` and
-`shared/sdk/include/extAttrBeast.h`, then inspect/import `public_core/lsa`
-semantics with userspace backend policy kept in separate boundary files.
+Most namespace operations are pure provider helpers and can be called through the
+real NSS families directly: compare, wildcard match/replace, ASCII/Unicode
+conversion, legal-name checks and component scanning for DOS, LONG/OS2,
+UNIX/NFS, MAC, DATASTREAM and EA.  `*_generateUniqueName()` is the exception: it
+requires directory uniqueness/collision lookup.  HostFS, OtherFS, sidecar or
+Mars directory enumeration for that path belongs in a parallel
+`nameSpaceUserspace.c` / `nameSpaceUserspace.h` boundary, not inline in
+`dosNSpace.c`, `longNSpace.c`, `unixNSpace.c`, `macNSpace.c` or `nameSpace.c`.
 
 ## Directory/NDS work order
 
@@ -115,6 +111,12 @@ inside `libnwnss`, not `nwfs` migration yet:
 - Do not touch or migrate the existing local `nwfs` XAttr code in this phase;
   `nwfs` will consume the libnwnss semantics later after the libnwnss side is
   tested.
+- For namespace, keep `libnwnss` as the NSS provider and put Mars/NWFS
+  compatibility wrappers in `nwfs` later.  Most namespace helpers are pure
+  string/provider operations; `*_generateUniqueName()` needs a userspace
+  directory collision boundary (`nameSpaceUserspace.c` / `.h`) because HostFS or
+  OtherFS enumeration must not be added directly to the original NSS namespace
+  files.
 
 Before namespace code changes, keep the legacy logging audit in mind: old MARS
 accepts numeric debug thresholds from `0` to `99`, but the actual source mostly
@@ -187,6 +189,14 @@ Then continue the NSS namespace track inside `libnwnss`:
 8. Keep `src/namspace.c` as NCP glue over the future namespace engine.  Do not
    expand old MARS `namedos`/`nameos2` as the long-term solution; they are
    replacement targets.
+9. Namespace pure helpers can stay provider-shaped in `libnwnss`: compare,
+   wildcard match/replace, ASCII/Unicode conversion, legal-name checks and
+   component scan for DOS, LONG/OS2, UNIX/NFS, MAC, DATASTREAM and EA.
+   `*_generateUniqueName()` is not a pure string helper; it needs directory
+   uniqueness lookup.  Preserve the original NSS namespace files and put HostFS,
+   OtherFS, sidecar or Mars directory-collision policy in a parallel
+   `nameSpaceUserspace.c` / `nameSpaceUserspace.h` boundary when that path is
+   implemented.
 
 ## NCP notation rule
 

REDESIGN.md

@@ -788,6 +788,39 @@ The first libnwnss XAttr patches should therefore be ordered as follows:
 4. keep any later FUSE or `io_uring` implementation behind an explicit backend
    vtable/context that `nwfs` or a future `nwnssmount` service can call.
 
+### Namespace provider and userspace unique-name boundary
+
+`libnwnss` is the NSS namespace provider.  Future Mars compatibility wrappers
+belong in `nwfs`, where Mars volume options, host paths, search handles and
+legacy request/response glue can be translated before calling into `libnwnss`.
+The current half-finished `nwfs` namespace staging should be ignored during
+`libnwnss` import work and later removed, replaced or adapted as a separate
+cleanup.
+
+The imported NSS namespace families already cover all namespace IDs that matter
+for the provider side: DOS, LONG/OS2, UNIX/NFS, MAC, DATASTREAM and EA.  Pure
+operations should remain direct provider calls into the real NSS families:
+compare, length compare, wildcard match/replace, ASCII/Unicode conversion,
+legal-name checks and component scanning.
+
+`*_generateUniqueName()` is different.  It needs directory collision lookup: in
+the original NSS flow this goes through `NamedBeast_s`, `NameSpace_s` and
+`NAME_FindZidForNameInDir()`.  For HostFS, OtherFS, sidecar-backed metadata or a
+future `nwfs` wrapper, do not add `opendir(3)`, host path traversal or Mars
+volume policy directly to `dosNSpace.c`, `longNSpace.c`, `unixNSpace.c`,
+`macNSpace.c` or `nameSpace.c`.  Keep those files original-near and add a
+parallel boundary when needed, for example:
+
+```text
+src/nwnss/comn/namespace/nameSpaceUserspace.c
+include/nwnss/comn/namespace/nameSpaceUserspace.h
+```
+
+That boundary should answer the NSS-style uniqueness question using an explicit
+backend/context supplied by the later `nwfs` wrapper or mount service.  It is the
+namespace equivalent of the LSA/XAttr `*Userspace.c` split: original NSS logic
+stays in original files, host filesystem and OtherFS policy stays beside it.
+
 The public libnwnss userspace API should expose libnwnss handles or backend
 contexts, not real Linux kernel `struct dentry *`, `struct inode *` or
 `struct super_block *` as stable ABI.  Original NSS internals may still use

nwnss-audit.md

@@ -102,6 +102,30 @@ or `io_uring` providers: libnwnss owns NSS media layouts, metadata/trustee/quota
 semantics and original control flow; the backend owns host paths, xattr storage,
 sidecar files, registered files/buffers and asynchronous I/O execution.
 
+### Namespace userspace uniqueness boundary
+
+The COMN namespace imports are the NSS provider layer, not the Mars/NWFS
+compatibility wrapper.  Future `nwfs` code may map Mars `NAME_DOS`, `NAME_OS2`,
+`NAME_NFS` and `NAME_MAC` to the imported NSS DOS, LONG, UNIX and MAC namespace
+families, and it should also account for DATASTREAM and EA namespace behavior.
+The existing partial `nwfs` namespace staging is ignored during this libnwnss
+audit/import phase and should be cleaned separately.
+
+Most namespace functions are pure provider helpers and do not need a libnwnss
+userspace sidecar: compare, wildcard matching/replacement, ASCII/Unicode
+conversion, legal-name checks and component scanning can stay in the original
+NSS namespace files.  `*_generateUniqueName()` is the exception because it
+requires directory collision lookup.  The original files expect
+`NamedBeast_s`/`NameSpace_s`/`NAME_FindZidForNameInDir()`; HostFS, OtherFS,
+sidecar or Mars directory enumeration must not be added inline there.
+
+If the userspace provider needs to support unique-name generation before a full
+NSS directory context exists, add a parallel boundary such as
+`nameSpaceUserspace.c` / `nameSpaceUserspace.h`.  That boundary may ask a later
+`nwfs` wrapper or mount backend whether a candidate name already exists, while
+leaving `dosNSpace.c`, `longNSpace.c`, `unixNSpace.c`, `macNSpace.c` and
+`nameSpace.c` original-near.
+
 ### Port resolution workflow
 
 For every `PORT` entry below, audit in this order: