From 3814fb315a99e59a4fb916bff959e70bee28c3ea Mon Sep 17 00:00:00 2001 From: OpenAI Date: Fri, 5 Jun 2026 20:25:49 +0000 Subject: [PATCH] docs: update AI handoff for redesign and FLAIM work --- AI.md | 156 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/AI.md b/AI.md index b3ea6a2..a140331 100644 --- a/AI.md +++ b/AI.md @@ -1585,4 +1585,160 @@ Next patch number should be `0253`. libowfat changes limited to import/build/CMake/portability work in the same spirit as MatrixSSL and FLAIM. +## 2026-06-05 - Current handoff for next chat: redesign + FLAIM/directory storage track + +This section is the current working handoff for the next mars-nwe chat. It is +newer than the old patch-number notes above. If the user starts a fresh chat, +ask for the current bundles/commits of all submodules first and rebuild the tree +from those, because the live work has moved beyond the old `0269` documentation +line. + +Current repositories used in this work: + +- `mars-nwe`: `https://gitea.disconnected-by-peer.at/mars_nwe/mars-nwe` +- `mars-flaim`: `https://gitea.disconnected-by-peer.at/mars_nwe/mars-flaim` + +There are now two separate workstreams. Keep patches and tests separated by +workstream. + +### Workstream A: mars-nwe redesign of existing code + +Goal: make the existing mars-nwe codebase more future-proof without doing a big +rewrite. + +Near-term first redesign task: + +- introduce small enum/type layers before moving logic; +- reduce magic strings / magic numbers at provider and directory boundaries; +- centralize string-to-enum mapping at the edges; +- add smoke/CTest coverage for known mappings; +- do not move large chunks of logic in the first enum patch. + +Likely first targets: + +- operation/request enums for internal handoff/provider dispatch; +- directory/NDS object and attribute identifiers once the real NetWare 4.11 + schema is available; +- typed config/setup enums for future `nwsetup`. + +Keep the redesign direction from `REDESIGN.md`: `nwserv` is control plane and +provider registry, not a data-plane payload broker; `nwconn` owns client reply +envelopes; providers/modules get clearer boundaries over time. + +### Workstream B: vendored infrastructure for future directory/storage rewrite + +Today’s integrated infrastructure work is not the redesign itself. It prepares +the replacement of old ad-hoc/self-built functions and flat-file directory +storage with maintained, namespaced libraries: + +- `libnwowfat` +- `libnwsodium` +- `libnwmatrixssl` +- `libnwssl` +- `libnwflaimtk`, `libnwflaim`, `libnwxflaim` +- `libnwdirectory` / `nwdirectory` from the tinyldap-derived tree + +Namespace policy: + +- historical mars-nwe programs keep their established names: `nwserv`, + `ncpserv`, `nwclient`, `dbmtool`, `ftrustee`; +- vendored/system-colliding libraries, headers, CMake packages, and imported + helper tools use the `nw` namespace/prefix; +- TinyLDAP/directory tools and FLAIM/XFLAIM tools install with `nw` prefixes; +- vendored headers stay below namespaced include directories such as + `nwcore/`, `nwssl/`, `nwflaim/`, `nwmatrixssl/`, `nwsodium/`, + `nwlibowfat/`, and `nwdirectory/`. + +FLAIM/MatrixSSL/NWSSL status at this handoff: + +- MatrixSSL is built as `libnwmatrixssl` and must export CPU/compiler feature + options such as AES flags to consumers so `PSCRYPTO_CONFIG` matches between + library and consumer. +- `yyjson` is built into `libnwcore`; public header is installed under + `include/nwcore/yyjson.h`. +- `nwssl` owns OpenSSL-compat headers under `include/nwssl/openssl/*.h` and + private NICI/CCS headers under `include/nwssl/private/nici/*.h`. +- The temporary OpenSSL-compat code was removed from MatrixSSL; OpenSSL-style + compatibility belongs in `nwssl`, not MatrixSSL. +- `nwssl` now has a functional NICI/CCS compatibility layer used by classic + FLAIM at-rest encryption. +- NICI support must be scoped to classic FLAIM targets only. Do not define + `FLM_USE_NICI` globally for XFLAIM; XFLAIM has a different NICI path and will + not compile against the classic FLAIM compat API. +- FLAIMSQL remains experimental and default-OFF. Do not make the default build + depend on `libnwflaimsql`; keep SQLFLAIM work separate. +- FLAIM is currently required only when directory support is enabled. + +Current green tests at the end of the 2026-06-05 session: + +```sh +ctest -L nwflaim --output-on-failure +# nwflaim.database.create-and-check ... Passed + +ctest -L flaim --output-on-failure +# nwflaim.database.create-and-check ......... Passed +# mars_nwe.flaim.api-create-query-encrypt ... Passed +# mars_nwe.xflaim.api-alloc ................. Passed +``` + +These tests confirm: + +- FLAIM tools can create and check a database; +- mars-nwe can use classic FLAIM API from the root test tree; +- classic FLAIM at-rest encryption works through `nwssl` NICI/CCS compat; +- XFLAIM still builds/runs its allocation smoke test without the incompatible + classic NICI path. + +Known important FLAIM fixes from this session: + +- GigaTest final rate calculation had a divide-by-zero/SIGFPE when elapsed time + was zero; this was fixed in `mars-flaim` source, not hidden in CTest. +- FLAIM dictionary add path needed to treat missing dictionary-name lookup EOF as + no-conflict. +- FLAIM base64 key decode needed to treat EOF after successful decode as + successful completion. +- FLAIM EncDef test dictionary syntax: `encdef` is valid on index definitions; + encrypted data fields in the root API test are created by adding an EncDef + dictionary record and using the API with that EncDef ID, not by putting + `encdef` below a field record. + +Planned directory/storage direction: + +- tinyldap/nwdirectory currently has flat-file/mmap storage. Long term it + should write through `libdirectory -> libnwflaim`, not directly to flat files. +- At-rest encryption was tested hard now because the future directory store will + contain keys, password verifiers, and other sensitive objects. +- When the user extracts the real NetWare 4.11 Directory/NDS schema, use it as + truth rather than inventing schema by hand. Important data to capture: + object classes, numeric IDs if available, attributes, syntax types, + single/multi-value flags, mandatory/optional attributes, naming attributes, + inheritance/superclasses, and index expectations. + +Useful future TinyLDAP/Directory tests: + +- initialize an empty directory database; +- add organization/container/user/group objects; +- authenticate a user/password; +- ensure password/secret material is not plaintext in the FLAIM files; +- close/reopen and verify all objects still exist; +- duplicate-name/object conflict handling; +- rename/move/delete object behavior; +- group membership add/remove lookup; +- indexed lookup for common attributes; +- schema validation once the real NetWare 4.11 schema is available. + +Future `nwsetup` direction: + +- Add a curses/ncurses `nwsetup` tool after the directory foundation exists. +- It should mimic the NetWare setup flow from installation phase 2 enough to + provision a mars-nwe directory: tree/server/org/O/user/admin password, + defaults, config files, and initial storage. +- `nwsetup` should write only hashes/verifiers/sealed keys to the store; no + reusable plaintext passwords in config. +- The user referenced the NetWare 6.5 Proxmox installation article as UI/setup + inspiration, not as an implementation dependency. + +When tomorrow’s chat starts, ask the user for the current bundles of `mars-nwe` +and all submodules, then rebuild a clean tree before producing new patches. + Next patch number should be `0269`.