From 64f73420abea7d18071c1b57ee30fb0d8ee8b960 Mon Sep 17 00:00:00 2001
From: x <a@b>
Date: Mon, 1 Jun 2026 07:34:18 +0000
Subject: [PATCH] tests: document hidden salvage repository paths

---
 AI.md                                | 17 +++++++++++++++++
 tests/README.md                      | 13 +++++++++++++
 tests/salvage/README.md              | 22 ++++++++++++++++++++++
 tests/salvage/salvage_smoke_suite.sh |  8 ++++++--
 4 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/AI.md b/AI.md
index 418a979..5ff004d 100644
--- a/AI.md
+++ b/AI.md
@@ -44,6 +44,23 @@ use, the current project status that the user pasted into the chat.
 - Do not add a new trustee or xattr database.  Salvage JSON is a snapshot; real
   restore should feed existing mars_nwe trustee/xattr/AFP mechanisms.
 
+## NCP path and hidden repository notes
+
+- Normal NCP path resolution intentionally treats Unix dot path components as
+  hidden/special.  In the classic path resolver (`build_dir_name()` in
+  `connect.c`), a component beginning with `.` is accepted only for `.`/`..`
+  semantics; a component such as `.recycle` or `.salvage` returns invalid path
+  (`0x899c`).
+- `nwattrib.c` also marks Unix dot files/directories hidden by default when no
+  explicit NetWare attributes are stored.
+- Therefore `.recycle` and `.salvage` are backend repositories, not user-visible
+  NCP paths.  Tests must not expect `SYS:.recycle/...` or `SYS:.salvage/...` to
+  open through ordinary NCP file calls.
+- Use the official salvage endpoints (`87/16` scan, `87/17` recover, `87/18`
+  purge, and old `22/27`-`22/29`) to observe or operate on salvage entries.
+  Verify recovered payload content by reading the restored live file through
+  NCP, not by opening backend repository paths through NCP.
+
 ## Salvage endpoint rules
 
 - `NCP 0x2222 / 87 / 16` is decimal 87/16, implemented as function `0x57`,
diff --git a/tests/README.md b/tests/README.md
index 34b332d..dda164f 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -34,3 +34,16 @@ the test client, not necessarily as root.  Pre-clean of old `.recycle` or
 `.salvage` artifacts is therefore best-effort: permission failures are reported
 as warnings and do not by themselves fail the smoke.  The actual pass/fail check
 is based on artifacts created by the NCP delete path.
+
+## NCP path visibility
+
+Normal mars_nwe NCP path resolution does not expose Unix dot directories as
+ordinary user-visible NetWare paths.  In the classic path resolver, leading-dot
+components are handled as special `.`/`..` syntax, so names such as `.recycle`
+or `.salvage` return invalid path (`0x899c`) through normal file open/read
+requests.  Directory scans also skip names beginning with `.`.
+
+Tests must therefore not validate salvage payloads by opening
+`SYS:.recycle/...` or `SYS:.salvage/...` through normal NCP file calls.  Use the
+salvage scan/recover/purge endpoints for repository state and verify payload
+content by reading the restored live file through NCP.
diff --git a/tests/salvage/README.md b/tests/salvage/README.md
index c926067..48938b9 100644
--- a/tests/salvage/README.md
+++ b/tests/salvage/README.md
@@ -101,6 +101,28 @@ require a running mars_nwe server and does not use NCP.
 It verifies the basic `.recycle`/`.salvage` directory contract and stale JSON
 detection.
 
+## NCP path visibility
+
+`.recycle` and `.salvage` are backend repository directories.  They are not
+ordinary user-visible NetWare paths.  The classic mars_nwe path resolver treats
+leading-dot path components as special `.`/`..` syntax and rejects names such as
+`.recycle` or `.salvage` with invalid path (`0x899c`).  Dot files/directories
+are also hidden by default in the NetWare attribute layer.
+
+Smoke tests therefore must not validate backend payloads by opening
+`SYS:.recycle/...` or metadata by opening `SYS:.salvage/...` through normal NCP
+file calls.  The correct NCP-level checks are:
+
+- create/write/read the live file through NCP,
+- delete the live file through NCP,
+- use salvage scan `87/16` to confirm that a salvageable entry exists,
+- use recover `87/17` or purge `87/18` on the scan sequence,
+- read the restored live file through NCP to verify payload content.
+
+Local filesystem layout tests may still inspect `.recycle` and `.salvage`
+directly when they intentionally test backend layout and run with suitable Unix
+permissions.
+
 ## NCP smoke suite
 
 `salvage_smoke_suite.sh` is the single integration check for the server-side
diff --git a/tests/salvage/salvage_smoke_suite.sh b/tests/salvage/salvage_smoke_suite.sh
index 465101d..24e5a51 100755
--- a/tests/salvage/salvage_smoke_suite.sh
+++ b/tests/salvage/salvage_smoke_suite.sh
@@ -469,8 +469,12 @@ run_delete_capture_cycle() {
     run_ncp_create_with_payload "$label: NCP create/write live file" "$content" || return 1
     run_ncp_delete_only "$label: NCP delete live file" || return 1
 
-    ncp_read_text_file "$label: NCP read recycle payload before recover" "$recycle_nw_path" "$content"
-    ncp_read_metadata "$label: NCP read salvage metadata before recover" "$meta_nw_path"
+    section "$label: backend salvage repositories are hidden from normal NCP paths"
+    emit "recycle_backend_path=$recycle_path"
+    emit "metadata_backend_path=$meta_path"
+    emit "recycle_ncp_path_not_tested=$recycle_nw_path"
+    emit "metadata_ncp_path_not_tested=$meta_nw_path"
+    emit "note=.recycle/.salvage are backend repositories; normal NCP reads are expected to fail for dot-directory paths"
 }
 
 run_version_capture_cycles() {