# 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.