From 341d7d92a8fa7e4602f08eca6bfa5bf2e05be419 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Thu, 18 Jun 2026 18:45:37 +0000 Subject: [PATCH] docs: clarify generic userspace boundary pattern --- AI.md | 66 ++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 40 insertions(+), 26 deletions(-) diff --git a/AI.md b/AI.md index 88ae4a1..bdc46b3 100644 --- a/AI.md +++ b/AI.md @@ -46,7 +46,7 @@ unfinished work out of `TODO.md` merely because its architecture is documented. Latest commit in an up-to-date tree: -- `docs: update XAttr/LSA import checklist and userspace boundary rules` +- `docs: clarify generic userspace boundary pattern` Compare `git log -1 --format="%s"` with this subject. If the tree is older, check which documentation/import-boundary commits are missing and replay them @@ -54,15 +54,17 @@ before starting new work. ## Current patch handoff block -Last completed work block: **XAttr/LSA import checklist and userspace boundary refresh** +Last completed work block: **Generic userspace boundary pattern refresh** `AI.md`, `REDESIGN.md` and `nwnss-audit.md` now describe the active libnwnss userspace-backend split. The next concrete implementation step is the real XAttr/LSA import from `nss.tar.bz2` and `nss-common.tar.bz2`, while local -`nwfs` XAttr/quota/salvage code remains adapter material only. The documented -follow-on direction is to build quota and salvage userspace boundaries on top of -that XAttr/LSA foundation rather than treating the current `nwfs` code as the -semantic source. +`nwfs` XAttr/quota/salvage code remains adapter material only. XAttr/LSA is the +metadata storage/lookup foundation for later quota and salvage boundaries, but +quota, salvage and namespace unique-name handling remain separate semantic areas +that follow the same generic companion-file rule: keep original NSS source files +as original-like as possible, add only small dispatch points, and put backend +selection in parallel `*Userspace.c` / `*Userspace.h` files. Ownership boundaries are current: `nwserv` is the process governor, `nwconn` is the NCP server, `libnwfs` is the Mars/NCP file wrapper, `libnwnss` is the NSS @@ -124,21 +126,25 @@ 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. -- Treat the XAttr/LSA import as the foundation for later quota and salvage - userspace boundaries. Quota and salvage ownership stays in `libnwnss`; - `libnwfs` only translates Mars/NCP requests to those provider operations. +- Treat the XAttr/LSA import as the metadata storage/lookup foundation for later + quota and salvage userspace boundaries, not as their semantic owner. Quota + and salvage remain separate NSS semantic areas, but their valid OtherFS state + should be found through NSS-shaped xattrs or NSS metadata. `libnwnss` owns + those provider operations; `libnwfs` only translates Mars/NCP requests to + them. - 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. + string/provider operations; `*_generateUniqueName()` needs the same generic + userspace companion-file pattern because HostFS/OtherFS directory collision + lookup may need NSS-shaped xattrs or NSS metadata and must not be added + directly to the original NSS namespace files. -- Quota and salvage follow the same ownership split. `libnwnss` is the NSS - provider for quota and salvage semantics imported from `nss`/`nss-common`; - `nwfs` is the later Mars wrapper/adapter. Existing `nwfs` quota and salvage - code is only an implementation inventory and must not be treated as - provenance or moved wholesale into `libnwnss`. +- Quota, salvage, namespace unique-name handling and future backend-sensitive + NSS functions all follow the same ownership split. `libnwnss` is the NSS + provider for semantics imported from `nss`/`nss-common`; `nwfs` is the later + Mars wrapper/adapter. Existing `nwfs` quota and salvage code is only an + implementation inventory and must not be treated as provenance or moved + wholesale into `libnwnss`. - OtherFS/HostFS quota policy such as Linux `quotactl()`, project-quota or metadata-only accounting belongs in parallel userspace boundary files such as `lsaQuotaUserspace.c` or `dirQuotasUserspace.c`, not inline in original NSS @@ -306,11 +312,15 @@ work. `nebEventPort.c`, Unicode TAB data (GENERATED PORT DATA from Unicode.org, not Novell blobs). When a PORT entry is found during audit, search for original `.c` or `sharedsrc/*.c.h` before accepting the port as final. -- For LSA/XAttr/COMN I/O backend work, keep imported original files focused on - original control flow and small backend decisions. Put userspace backend +- For LSA/XAttr/COMN I/O backend work, and for every future NSS function that + needs a userspace/backend decision, keep imported original files focused on + original control flow and small dispatch points. Put userspace backend selection and host adaptation in separate `*Userspace.c` / `*Userspace.h` - files. `virtualIO` is already the NSS `_ADMIN`/management virtual-file layer; - do not reuse that name for future disk/block/`io_uring` backends. + files. Those companions decide whether the operation targets the real + NSS/io_uring backend path or an OtherFS/HostFS path, then call the appropriate + backend-specific functions. `virtualIO` is already the NSS `_ADMIN`/ + management virtual-file layer; do not reuse that name for future disk/block/ + `io_uring` backends. - `*Userspace.c` / `*Userspace.h` companion files have two distinct roles. Companions such as `nameSpaceUserspace.c`, `lsaXattrUserspace.c` or `dirQuotasUserspace.c` are ALLOWED: they sit alongside the matching imported @@ -336,9 +346,10 @@ work. - `libnwnss` owns NSS provider semantics and the future real NSS backend boundaries: FUSE, `io_uring`, HostFS/OtherFS and the explicit `*Userspace.c` / `*Userspace.h` companion files for XAttr, namespace - uniqueness, quota and salvage. `nwnssmount` is the future FUSE mount - consumer of `libnwnss`; `nwnssmu` is the future TUI management utility for - admin, inspect, repair, quota, salvage, namespace and XAttr operations. + uniqueness, quota, salvage and any later backend-sensitive NSS operation. + `nwnssmount` is the future FUSE mount consumer of `libnwnss`; `nwnssmu` is + the future TUI management utility for admin, inspect, repair, quota, salvage, + namespace and XAttr operations. - `libnwbind` is for bindery identity/storage. NDS/eDirectory compatibility belongs in a future `libnwnds`, backed by `libnwdirectory`; `nwdirectory` is the LDAP/TinyLDAP-based directory server. An `nwnds` process may be added @@ -385,7 +396,10 @@ work. replacement wrappers. - Stable namespace state belongs in `netware.metadata`: file ID, parent file ID, DOS name, LONG/OS2 name, MAC name, UNIX/backend name, casefold/hash fields and - namespace flags. + namespace flags. `*_generateUniqueName()` must use the generic userspace + companion-file pattern when it needs HostFS/OtherFS directory collision lookup + or metadata/xattr-backed namespace state; do not put that lookup directly into + the original NSS namespace source files. - Existing Linux files created by Samba, rsync or local admin tools must be reconciled by libnwfs watcher/scanner work, not by a private side database. - MAC namespace is a namespace/stream/metadata problem, not a transport problem.