diff --git a/nwnss-audit.md b/nwnss-audit.md index 33390a9..c19584b 100644 --- a/nwnss-audit.md +++ b/nwnss-audit.md @@ -40,6 +40,52 @@ Current inventory summary: - `TEMP`: 2 files - Total listed files: 489 + +## Audit policies + +### Header policy + +Header files imported from NSS should stay complete and close to the +original source, even when many declarations are not used by the current +`libnwnss` build yet. Unused declarations are useful for later imports and +should not be removed to hide compile errors. Header changes are allowed +only for concrete compile conflicts, include-path fixes, or narrowly scoped +`MARS_NWE_NWNSS_USERSPACE` compatibility. Prefer local `.c` compile fixes +or private Mars compat headers over rewriting public NSS headers. + +### Source policy + +For `.c` and `sharedsrc/*.c.h` files, original NSS provenance is preferred. +When a symbol is missing, search the complete NSS and nss-common source set, +including `public_core/sharedsrc/*.c.h` and the original makefile wrapper +pattern, before adding or keeping a Mars port. Source code may be guarded for +`MARS_NWE_NWNSS_USERSPACE` only where the original Linux kernel path can run +in userspace without real kernel disk/block/VFS I/O. Real disk/block/VFS I/O +code stays in the tree but remains disabled in the default userspace build +until it is ported to the Mars userspace I/O layer. + +### Port resolution workflow + +For every `PORT` entry below, audit in this order: + +1. Search the full NSS and nss-common sources for an original `.c` provider. +2. Search `public_core/sharedsrc/*.c.h` and original makefiles for wrapper + patterns. +3. If an original provider exists, replace or shrink the Mars port. +4. If the provider is an external service not present in the shipped sources + (for example NEB/nebus), keep a clearly named Mars port with a comment + explaining the missing provenance and add/keep tests. +5. If original files cannot be used for licensing reasons (for example the + Novell Unicode TAB tables), keep a clearly marked replacement with tests. +6. Do not mark the file `AUDITED` until the provenance decision and test + coverage are recorded here. + +### Per-patch audit rule + +Future audit patches should include the source/header cleanup and the matching +test changes in the same patch whenever behavior is affected. Each patch must +update this checklist for the files it verifies. + ## 1. Currently audited or partially audited focus areas | Status | File / block | Kind | Test coverage | Notes |