0483 nwfs: document NSS namespace bottom-up dependency order

AI.md

@@ -47,7 +47,7 @@ unfinished work out of `TODO.md` merely because its architecture is documented.
 
 Latest patch marker expected in an up-to-date bundle:
 
-- `0482 nwfs: drop artificial namespace model`
+- `0483 nwfs: document NSS namespace bottom-up dependency order`
 
 When a later chat receives a new `mars-nwe-master` bundle, compare `git log -1`
 with this marker.  If the uploaded bundle already contains this commit subject,
@@ -67,24 +67,23 @@ The active line is expected to include:
 
 Last generated patch:
 
-- `0482 nwfs: drop artificial namespace model`
+- `0483 nwfs: document NSS namespace bottom-up dependency order`
 
 Purpose of that patch:
 
-- Remove the artificial `nameSpaceModel` layer and its CTest because it is not Novell/NSS code and does not prove the namespace import.
-- Move `lsaPrivate.h` out of `src/nwfs` into `include/nwfs` like the other NWFS headers.
-- Keep legacy namespace reply helpers in `src/namspace.c` until the real NSS dependency chain is imported bottom-up.
-- Correct the initial DOS namespace import by removing the temporary reduced
-  headers and `nssNamespaceCompat.c` compile shim.
-- Move the imported DOS namespace header to `include/nwfs/` and import only the
-  required NSS headers flat as `include/nwfs/<name>.h`; use `include/core` for
-  headers already owned by core instead of duplicating them.
-- Keep `src/nwfs/dosNSpace.c` as the unwrapped NSS source, but do not compile it
-  into libnwfs until the real bottom-up dependencies (`nameSpace.c`, beast/admin
-  volume/common-layer pieces and any lower libraries they require) are imported.
-- Add `nwfs.nss.namespace-import-layout` so future patches cannot accidentally
-  reintroduce local namespace shims or build DOS before its real NSS dependency
-  chain exists.
+- Record the bottom-up dependency order for the real NSS namespace import.
+- Keep `dosNSpace.c` imported but not built until `nameSpace.c` and its real
+  beast/admin-volume/runtime dependencies are present.
+- Identify the next code work as the smallest real NSS runtime base below
+  `comnBeasts.h`: `latch.h`, `xCache.h`, FSM/scheduler/cache headers and their
+  source owners, while reusing existing `include/core` headers instead of
+  duplicating them under `include/nwfs`.
+- Preserve the `_ADMIN` volume policy for the later admin-volume import:
+  `SYS` is volume ID `0`, `_ADMIN` is volume ID `1`, and normal volumes start
+  at `2`; `_ADMIN` may be built before NCP exposure but must remain hidden until
+  the runtime path is ready.
+- Extend the namespace import-layout test so it fails if future patches skip the
+  documented runtime/latch/cache/beast/admin-volume order or reintroduce shims.
 
 
 Directory/NDS work order before any FLAIM storage conversion:

doc/NSS_NAMESPACE_AUDIT.md

@@ -133,6 +133,75 @@ public_core/comn/authsys/*
 That code references bindery/auth/common-layer internals and should become a
 future `libnwbind` or `libnwauth` block, not a core namespace import.
 
+## Bottom-up namespace dependency order
+
+The namespace import is now intentionally ordered from the lowest reusable NSS
+state upward.  Do not make `dosNSpace.c` compile by adding local shim functions
+or reduced replacement headers.  If an imported file needs another NSS symbol,
+find the source/header that owns that symbol, check whether the corresponding
+primitive already exists in `include/core`, and import the missing layer first.
+
+Current dependency walk from the imported DOS namespace source:
+
+```text
+dosNSpace.c
+  -> DOSNS_Startup()
+  -> COMN_RegisterNameSpace()
+  -> public_core/comn/namespace/nameSpace.c
+  -> comnBeastClass.h / comnBeasts.h / adminVolume.h / pssStartup.h
+  -> latch.h + xCache.h + NSS MPK/OS abstraction headers
+```
+
+`comnBeasts.h` is the first blocker, not the DOS namespace code itself.  It
+includes `latch.h` and `xCache.h`; `xCache.h` then pulls the scheduler/FSM/cache
+header family (`alarm.h`, `control.h`, `fsm.h`, `asyncio.h`), and `latch.h` pulls
+`pssmpk.h`, `pssDebug.h`, `fsm.h` and `parse.h`.  These are NSS runtime
+abstractions, so the next import must start below beast/namespace with the
+smallest real buildable support layer rather than with `nameSpace.c`.
+
+Core-owned headers must not be duplicated under `include/nwfs`.  The following
+are already supplied by the existing core layer and should be found through the
+`mars_nwe::core` dependency or the explicit core include path:
+
+```text
+include/core/bit.h
+include/core/guid.h
+include/core/omni.h
+include/core/que.h
+include/core/utc.h
+include/core/xError.h
+include/core/xUnicode.h
+include/core/zOmni.h
+```
+
+Headers that are genuinely NSS/NWFS-specific are imported flat as
+`include/nwfs/<header>.h`; do not keep them under `include/nwfs/nss/...`, and do
+not add private copies under `src/nwfs/`.
+
+The planned code order is therefore:
+
+1. `nwfs-nss-runtime-base`: the smallest real subset of NSS MPK/scheduler/FSM
+   headers and sources needed by `latch.h`/`xCache.h`, with Linux-kernel-only or
+   NDPS/DDS-only includes removed or guarded only when the filesystem path does
+   not use them.
+2. `nwfs-latch-cache-base`: direct imports for `latch`/cache types required by
+   beast structures.
+3. `nwfs-beast-base`: beast class and root-beast structure support.
+4. `nwfs-admin-volume`: build the `_ADMIN` virtual volume model, but do not
+   expose it through NCP until the runtime path is ready.
+5. `nwfs-namespace-registry`: `nameSpace.c` and registration state.
+6. DOS namespace activation: build `dosNSpace.c` only after the registry and its
+   real dependencies are present.
+
+The `_ADMIN` volume ID policy for that later import is fixed even while the
+volume is hidden from NCP:
+
+```text
+SYS     => volume ID 0
+_ADMIN  => volume ID 1
+other volumes start at ID 2
+```
+
 ## `_ADMIN` virtual volume
 
 NSS also carries the `_ADMIN` management volume model.  It is storage/filesystem

tests/nwfs/nwfs_nss_namespace_import_layout_test.sh.in

@@ -53,4 +53,14 @@ fi
 grep -q 'DOSNS_Startup' "$SRC/src/nwfs/dosNSpace.c" || fail "DOS namespace source is not the NSS implementation"
 grep -q 'COMN_RegisterNameSpace' "$SRC/src/nwfs/dosNSpace.c" || fail "DOS namespace source no longer depends on the real NSS namespace registry"
 
+DOC="$SRC/doc/NSS_NAMESPACE_AUDIT.md"
+test -f "$DOC" || fail "missing NSS namespace audit document"
+grep -q 'dosNSpace.c' "$DOC" || fail "dependency order must start from imported DOS namespace source"
+grep -q 'nameSpace.c' "$DOC" || fail "dependency order must record the namespace registry source"
+grep -q 'comnBeasts.h' "$DOC" || fail "dependency order must record the beast base header"
+grep -q 'latch.h' "$DOC" || fail "dependency order must record the latch dependency"
+grep -q 'xCache.h' "$DOC" || fail "dependency order must record the cache dependency"
+grep -q 'SYS     => volume ID 0' "$DOC" || fail "audit must reserve SYS as volume ID 0"
+grep -q '_ADMIN  => volume ID 1' "$DOC" || fail "audit must reserve _ADMIN as volume ID 1"
+
 exit 0