docs: add AI notes and logging schema todo

AI.md

@@ -0,0 +1,124 @@
+# AI working notes for mars-nwe
+
+This file is for future ChatGPT sessions.  It records general working rules and
+local build/test notes only.  It should not be used as the current project
+status log; the current patch stack and task context should be pasted into a new
+chat separately.
+
+## Start of a new chat
+
+When the user says this is a new chat or asks to continue mars-nwe work, first
+read this file before proposing patches or making assumptions.  Then ask for, or
+use, the current project status that the user pasted into the chat.
+
+## Patch workflow
+
+- Produce patches that apply with exactly:
+
+  ```sh
+  git am patchname.patch
+  ```
+
+- Assume the user has already applied and committed accepted earlier patches.
+  Build every new patch against the current tree the user provides.
+- Do not ask the user to apply a long patch chain unless they explicitly say
+  earlier patches were not committed.
+- Keep follow-up patches small and reviewable.  Do not mix functional changes,
+  cleanup, and logging refactors unless the user asks for that.
+- If a patch is only documentation or test cleanup, keep it that way.
+
+## mars-nwe coding style rules
+
+- Prefer existing mars_nwe / NetWare functions over new helper code.
+- Before adding a helper, search the tree for an existing equivalent.
+- Do not introduce parallel mechanisms for paths, trustees, xattrs, AFP
+  metadata, copy/write/restore, u16/u32 packing, or logging.
+- Use existing integer and wire-format macros such as `GET_16`, `GET_32`,
+  `U16_TO_16`, `U32_TO_32`, and related mars_nwe helpers instead of open-coded
+  byte parsing/serialization.
+- Use existing namespace/path conversion and basehandle logic instead of parsing
+  NetWare paths by hand.
+- For file restore/copy/write behavior, prefer the existing Novell/mars_nwe file
+  functions over direct POSIX operations.  Use POSIX only where there is no
+  suitable internal mechanism, and keep it clearly isolated.
+- 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.
+
+## Salvage endpoint rules
+
+- `NCP 0x2222 / 87 / 16` is decimal 87/16, implemented as function `0x57`,
+  subfunction `0x10`.
+- `NCP 0x2222 / 87 / 17` is decimal 87/17, function `0x57`, subfunction
+  `0x11`.
+- `NCP 0x2222 / 87 / 18` is decimal 87/18, function `0x57`, subfunction
+  `0x12`.
+- Keep `0x57` subfunction dispatch in `handle_func_0x57()` / namespace code,
+  not as a second subfunction switch in `nwconn.c`.
+- Versioned salvage entries may have different `.recycle`/`.salvage` names but
+  `87/16` returns the original deleted filename for every version.  Do not match
+  recover/purge by display name alone.
+- Scan, recover, and purge should share the same scan/sequence/basehandle view
+  so that a sequence returned by scan identifies the exact sidecar used later.
+- Append salvage endpoint tests to `tests/salvage/salvage_smoke_suite.sh` rather
+  than creating unrelated top-level scripts.
+
+## Logging rules
+
+Desired future server log format:
+
+```text
+<LVL4> <AREA> <DEC-CODE> <EVENT> key=value ...
+```
+
+- `LVL4` is exactly four characters: `INFO`, `DBUG`, `WARN`, `ERRR`.
+- `AREA` examples: `NCP`, `SALVAGE`, `AFP`, `MAP`, `BIND`, `TRUST`, `AUTH`,
+  `CONN`, `FILE`, `QUEUE`.
+- The front code should be human/protocol decimal where applicable, for example
+  `87/16`, `87/17`, `87/18`.
+- Exact wire values should still be logged later as key/value hex fields, for
+  example `fn=0x57 sub=0x10 seq=0x00000000 base=0x00000004 result=0x89ff`.
+- Unknown or unimplemented endpoints should be easy to grep, for example:
+
+  ```text
+  INFO NCP 87/18 UNKNOWN fn=0x57 sub=0x12 msg="not implemented"
+  INFO NCP 87/255 UNKNOWN fn=0x57 sub=0xff msg="unknown subfunction"
+  INFO NCP 136 UNKNOWN fn=0x88 msg="unknown function"
+  ```
+
+- Do not invent a parallel logger casually.  Reuse existing mars_nwe logging
+  functions/macros and normalize message format gradually.
+
+## Build and test notes
+
+Dependencies used during local checks in this conversation:
+
+- `gdbm-1.26.tar.gz`
+- `Linux-PAM-1.7.2.tar.xz` for PAM headers; link against system PAM if present
+- `ncpfs-master.zip` for the salvage smoke helper client build
+- `yyjson` under `third_party/yyjson`
+
+If CMake finds GDBM but a target still cannot see `gdbm.h`, pass include paths
+explicitly for local verification, for example:
+
+```sh
+CFLAGS="-I/path/to/gdbm/include -I/path/to/Linux-PAM-1.7.2/libpam/include" \
+cmake -S . -B build
+cmake --build build --target nwconn ncp_salvage_scan_smoke ncp_salvage_recover_smoke
+```
+
+Useful quick checks:
+
+```sh
+bash -n tests/salvage/salvage_smoke_suite.sh
+cc -DLINUX -fsyntax-only -Iinclude -Isrc -Ithird_party/yyjson/src src/nwsalvage.c src/namspace.c
+```
+
+Runtime smoke suite:
+
+```sh
+tests/salvage/salvage_smoke_suite.sh
+```
+
+The suite may run pre-clean warning-only when `.recycle` or `.salvage` artifacts
+are server/root-owned.  Treat the final summary (`failures=0`, `ncp_warnings=0`)
+as the important signal.

TODO.md

@@ -153,6 +153,53 @@ Follow-up:
 - Verify that the quota-disabled fallback remains compatible with requesters
   and with the WebSDK rule for invalid object IDs.
 
+
+
+### Server logging schema
+
+Current status:
+
+- Server logging is useful during protocol work, but output is still noisy and
+  not formatted consistently across NCP, namespace/path mapping, AFP, bindery,
+  file, queue, trustee, and salvage code.
+- During salvage endpoint development, verbose logs are preferred over missing
+  diagnostic information, but the messages should become easier to grep and
+  compare across subsystems.
+
+Follow-up:
+
+- Normalize new server log lines toward this shape:
+
+  ```text
+  <LVL4> <AREA> <DEC-CODE> <EVENT> key=value ...
+  ```
+
+- Use four-character levels so columns do not jump around:
+  - `INFO`
+  - `DBUG`
+  - `WARN`
+  - `ERRR`
+- Put the level first, then the subsystem/function area, for example `NCP`,
+  `SALVAGE`, `AFP`, `MAP`, `BIND`, `TRUST`, `AUTH`, `CONN`, `FILE`, or `QUEUE`.
+- Use decimal/protocol-facing endpoint identifiers near the front when they are
+  what the documentation uses, for example `87/16`, `87/17`, and `87/18`.
+- Keep exact wire values as hex key/value fields later in the same line, for
+  example `fn=0x57 sub=0x10 ns=0x00 seq=0x00000000 vol=0x0000
+  base=0x00000004 result=0x89ff`.
+- Mark missing or unimplemented endpoints with a stable `UNKNOWN` event, for
+  example:
+
+  ```text
+  INFO NCP 87/18 UNKNOWN fn=0x57 sub=0x12 msg="not implemented"
+  INFO NCP 87/255 UNKNOWN fn=0x57 sub=0xff msg="unknown subfunction"
+  INFO NCP 136 UNKNOWN fn=0x88 msg="unknown function"
+  ```
+
+- Prefer existing mars_nwe logging functions/macros.  Do not introduce a second
+  logging subsystem just to change the message format.
+- Convert noisy areas gradually, starting with NCP function/subfunction dispatch
+  and the salvage endpoints.
+
 ## Printing / Queue backend
 
 ### Q_UNIX_PRINT backend status