0527 doc: define NSS userspace adaptation boundary

doc/NSS_USERSPACE_ADAPTATION.md

@@ -0,0 +1,79 @@
+# NSS userspace adaptation boundary
+
+The NSS import is a source and behaviour reference for Mars NWE. The goal is
+not to recreate the Novell NSS filesystem or its Linux kernel modules in
+userspace. The goal is to reuse the useful NSS semantics as libraries that Mars
+NWE can call.
+
+## Target semantics
+
+The useful exported behaviour is primarily:
+
+- namespace handling for DOS, LONG/OS2 and later MAC/UNIX/DataStream/EA;
+- trustee and rights-management semantics;
+- effective-rights calculation;
+- extended-attribute and metadata semantics;
+- the `_ADMIN`/AdminVolume view as a Mars-provided in-memory/config-backed
+  userspace volume;
+- salvage/compression/repair-related helpers where they expose useful NetWare
+  semantics.
+
+These pieces should become library code owned by Mars NWE integration points,
+not a standalone NSS volume implementation.
+
+## Storage and persistence boundary
+
+NSS code may contain logic for writing metadata, names, trustees or xattrs into
+an NSS volume. In Mars NWE, that storage backend is different:
+
+- metadata and xattrs should be mapped to the underlying host filesystem, using
+  the existing or future Mars/NWFS xattr layer;
+- AdminVolume data should be generated from Mars configuration/runtime state,
+  not stored in a fake NSS disk format;
+- namespace and rights functions should operate on Mars volume/file abstractions
+  once the dependency chain is available;
+- no Linux kernel module, NSS disk format or hidden NSS volume should become a
+  runtime requirement.
+
+During initial imports, keep NSS files as close to original as practical so the
+real dependencies are visible. Later integration patches may replace NSS storage
+hooks with Mars userspace hooks, but those replacements should be explicit and
+well documented.
+
+## Makefile and module-list audit
+
+The NSS `Makefile`, `*Modules.mk` and buildtool files are useful as dependency
+maps. They should be used to identify which sources belong to features such as
+AdminVolume, namespace, common Beast objects, LSA, cache/runtime support and
+rights handling.
+
+They are not a build target for Mars NWE. Mars should import only the source
+files and headers required to expose the desired library behaviour, then wire
+those pieces into the CMake library targets.
+
+## Import strategy
+
+1. Import bottom-up runtime dependencies with original filenames and directory
+   shape where practical.
+2. Prefer real NSS implementation files over invented wrappers.
+3. Keep public include roots as `include/core` and `include/nwfs`; keep NSS
+   subdirectories in include names.
+4. Add small CTests for each imported runtime group.
+5. When NSS code reaches filesystem persistence, replace that boundary with Mars
+   userspace adapters instead of carrying NSS kernel/disk assumptions forward.
+6. Audit already-imported or rewritten Mars files, especially `nwfs/lsa`, before
+   building higher-level namespace/AdminVolume features on top of them.
+
+## AdminVolume direction
+
+`_ADMIN` should be represented as a Mars NWE userspace/admin library view. The
+NSS sources should provide the semantics and object layout clues, while Mars
+provides the backing data. The initial integration should keep `_ADMIN` internal
+and not expose it over NCP until namespace, metadata, rights and generated-file
+behaviour are reliable.
+
+Volume numbering remains:
+
+- `SYS = 0`
+- `_ADMIN = 1`
+- further configured volumes start at `2`

doc/librarys/README.md

@@ -34,3 +34,9 @@ standalone public page. For example, iniparser and Unicode tables are internal
 The directory names use the `nw...` prefix for documentation even when the
 underlying CMake target or upstream project keeps its original name. This keeps
 Mars-specific documentation grouped and avoids collisions with upstream docs.
+
+## NSS userspace adaptation boundary
+
+See `../NSS_USERSPACE_ADAPTATION.md` for the rule that NSS imports provide
+semantics and dependency provenance, while Mars NWE provides the userspace
+storage, xattr, AdminVolume and integration backends.

doc/librarys/nwfs/README.md

@@ -31,3 +31,13 @@ all active yet.
 Mars code should prefer the active `nwfs` public headers for metadata and quota
 operations. NSS namespace internals should remain internal until the full
 Namespace, Beast and AdminVolume dependency chain is available.
+
+## NSS adaptation boundary
+
+`nwfs` should expose NetWare/NSS semantics to Mars NWE, not embed a fake NSS
+filesystem. NSS xattr, metadata, namespace and rights code may be imported as
+provenance-preserving library code, but persistence must be mapped onto Mars
+userspace storage: host filesystem xattrs, Mars metadata files, and generated
+AdminVolume state.
+
+See `doc/NSS_USERSPACE_ADAPTATION.md` for the project-wide boundary.