From 96e9408e714db6e2df51d49976817b42c47ce5ac Mon Sep 17 00:00:00 2001 From: Test User Date: Tue, 2 Jun 2026 10:43:31 +0000 Subject: [PATCH] docs: update AI handoff notes for redesign work --- AI.md | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 176 insertions(+), 26 deletions(-) diff --git a/AI.md b/AI.md index e91ae85..dc2177d 100644 --- a/AI.md +++ b/AI.md @@ -11,38 +11,188 @@ 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. -## Current handoff status after patch 0171 +## Current handoff status after patch 0197 -The current accepted patch line for the endpoint-documentation work is expected -to be: +The current accepted patch line in this chat is expected to include: -- `0141-log-normalize-afp-get-file-info-mask-fields.patch` through - `0171-docs-document-ncp23-queue-core-layouts.patch` +- endpoint-audit/documentation patches through `0176-docs-audit-direct-lifecycle-buffer-endpoints.patch`; +- redesign documentation patches `0177` through `0197`; +- latest confirmed patch name: `0197-docs-define-nwserv-control-plane-role.patch`. -Do not apply or base work on these rejected/superseded patches: +When continuing in a new chat, first ask the user which patch was actually last +applied. If they confirm `0197`, build the next patch as `0198-...` against a +tree that already contains `0197`. If any patch failed or was skipped, rebuild +against the last confirmed applied patch instead of assuming the file in +`/mnt/data` was accepted. -- `0141-log-normalize-afp-file-information-bitmap-fields.patch` -- `0144-docs-add-root-changes-summary.patch` if it is the German version; use - `0144-docs-add-root-changes-summary-en.patch` instead -- `0152-docs-note-message-control-subfunction.patch` because it documented a - later NetWare 5.x/MOAB message-control subfunction outside the current - default compatibility target -- `0160-docs-gate-netware4-directory-stubs.patch` because it wrapped or moved - already implemented endpoints; use - `0160-docs-bucket-endpoint-audit-by-netware-generation.patch` instead -- `0161-docs-recheck-ncp22-websdk-endpoint-coverage.patch` because it mixed - SDK decimal notation with wire hex cases and placed comments at the wrong - spot; use `0161-docs-recheck-ncp22-websdk-coverage-corrected.patch` instead +Known numbering/patch-history notes from this chat: -Next likely endpoint block: continue `0x2222/23` Queue Management after the -core queue/job calls documented in `0171`. The next patch should inspect the -remaining queue/job-control subfunctions in `nwbind.c` and any `nwconn.c` -prehandlers, compare them against WebSDK/PDF/includes, and record only real -layout differences in `TODO.md`. +- `0190-docs-clarify-imported-nwlog-backend-layout.patch` was superseded because + patch number `0189` was accidentally skipped and the old `0190` failed after + `0188`. Do not reuse that old file. +- Use `0189-docs-clarify-imported-nwlog-backend-layout.patch` instead. +- Then use `0190-docs-clarify-simple-syslog-nwlog-backends.patch`, followed by + `0191` ... `0197`. -When handing off to a new chat, paste the latest patch name the user has -actually applied. If the user says a patch was not applied, rebuild the next -patch against the last confirmed applied patch, not against the rejected file. +The user prefers patch verification snippets to contain only: + +```sh +git am patchname.patch +``` + +Do not include `git diff --check HEAD^..HEAD` in the final summary unless the +user asks for it. + +## Current redesign decisions to preserve + +`REDESIGN.md` is now the place for broad architecture notes. Do not keep +growing `TODO.md` with long-term redesign material. `TODO.md` should remain +for concrete endpoint/test/fix follow-ups. + +High-level NCP architecture direction: + +- Add a small internal NCP dispatch/handoff layer over time; avoid a large + message-bus rewrite. +- Provider boundary is not the same as process boundary. +- `nwbind` remains legacy bindery provider/service. +- Queue is a strong candidate for a future `nwqueue` provider/process, but first + split it logically from bindery. +- Filesystem/volume/namespace should become a provider/module boundary first; a + separate process would be risky and later only. +- Semaphore, server-management, and most small call families should remain + modules/providers, not separate processes. +- `nwserv` is the control plane/supervisor/provider registry, not a data-plane + payload router. Normal requests should flow `client -> nwconn -> provider -> + nwconn -> client`, not through `nwserv` as broker. +- Provider processes must always return one formal internal handoff reply. + `NO_REPLY` is an explicit reply kind, not silence. `nwconn` owns the final + client NCP reply envelope and send. + +Transport direction: + +- TCP/IP support is a transport split below `nwconn`/`nwserv`, not a new daemon. +- Planned code layout: `src/nwtransport.c`, `src/nwipx.c`, `src/nwtcp.c`. +- `nwtransport` is a code/library boundary, not a process. +- Higher providers must not depend on raw `ipxAddr_t` long-term. +- IPX SAP/RIP/watchdog/broadcast behavior remains isolated as IPX-specific. + +Secure IPC/TLS direction: + +- Client-facing NetWare 4.x/NCP/NDS compatibility must not require TLS by + default. Keep historical clients compatible. +- LDAP/LDAPS/StartTLS for `nwdirectory` uses wolfSSL at the external LDAP edge. +- Internal provider IPC over TCP, if added later, must always use wolfSSL-backed + TLS with mutual authentication. No plaintext fallback for TCP provider IPC. +- Local IPC may remain Unix-domain sockets, pipes, socketpairs, or inherited FDs + with strict permissions; still avoid logging decoded secrets. +- Add `nwtls` as the internal TLS facade if/when wolfSSL is wired into runtime: + `include/nwtls.h`, `src/nwtls.c`, `src/nwtls_wolfssl.c`. + +Directory/NetWare 4.x direction: + +- `libdirectory` is the shared internal C API/library used by `nwbind`, future + `nwnds`, `nwdirectory`, and `nwsetup`. These components should not talk LDAP + internally just to reach the directory store. +- `libflaim` is the planned persistent store under `libdirectory`. FLAIM is C++; + keep its C++ API behind `libdirectory` so old mars-nwe C code does not include + FLAIM C++ headers directly. +- `nwdirectory` is the mars-nwe integration name for the tinyldap-derived + LDAP/LDAPS service. Standalone/upstream identity remains `tinyldap`; inside + mars-nwe it builds the `nwdirectory` service. +- Future `nwnds` is the NetWare 4.x/NDS compatibility layer and should use + `libdirectory`, not LDAP protocol calls, as its internal backend path. +- `nwbind` should eventually become a legacy bindery adapter over + `libdirectory`/`libflaim`, not maintain a second persistent truth. +- Do not mention or design Kerberos for the current NetWare 4.x target. + +Configuration and setup direction: + +- Move toward a real typed, documented INI format. Do not use JSON as the admin + config format. +- The generated INI is also user documentation. Writers must preserve comments + where possible or regenerate from a full documented template; never rewrite it + into an undocumented minimal key/value dump. +- `nwsetup` is the provisioning/setup tool. It should initialize the + `libdirectory`/`libflaim` store, create initial schema/tree/admin/server + objects, migrate bindery data later, and edit config atomically. +- No reusable Admin/Supervisor/NDS/LDAP plaintext passwords in the new typed INI. + Initial passwords and recovery resets belong to explicit `nwsetup` commands + and only hashes/verifiers go into the store. +- Legacy bindery config-password reset may remain only as deprecated compatibility + behavior; Directory/NDS mode uses `nwsetup` recovery commands. + +Logging direction: + +- Add a small internal `nwlog` facade instead of direct zlog/log.c calls in + handlers/providers. Project layout: `include/nwlog.h`, `src/nwlog.c`. +- Category wrappers should exist for normal code: `nwlog_ncp()`, + `nwlog_handoff()`, `nwlog_bindery()`, `nwlog_queue()`, `nwlog_directory()`, + `nwlog_nds()`, `nwlog_ldap()`, `nwlog_auth()`, `nwlog_acl()`, + `nwlog_recovery()`, `nwlog_security()`. They populate an internal + `nwlog_event` and call `nwlog_emit()`. +- `rxi/log.c` may be vendored/adapted as `nwlog_simple`, not exposed directly: + `include/nwlog_simple.h`, `src/nwlog_simple.c`. It is a simple + stderr/stdout/file/callback basis and is a good default for systemd/journald. +- `nwlog_syslog` may later be derived/cloned from the simple backend for classic + `syslog(3)` explicitly: `src/nwlog_syslog.c`. +- `zlog` is the preferred optional advanced routing backend behind the facade: + `src/nwlog_zlog.c`. It may live as a `third_party/zlog` submodule. +- Never route raw decoded NCP/handoff/auth payloads to remote loggers. Only + redacted structured events should leave the host. + +Third-party/fork policy: + +- Fixed third-party libraries live under `third_party/`, such as existing + `yyjson`, planned `wolfssl`, planned `libflaim`, and optional `zlog`. +- `wolfSSL` is the fixed bundled TLS implementation, similar in spirit to + `yyjson`. Do not design a first-pass OpenSSL/LibreSSL backend matrix. +- `libflaim` should live under `third_party/libflaim` as a mars-nwe-maintained + import/fork/mirror. Source may come from SourceForge/SVN and/or a distro + source package such as openSUSE `libflaim-4.9.1046`. Document exact import, + revision/version, license files, distro patches, and local patches in + `third_party/libflaim/README.mars-nwe.md`. +- FLAIM r1112 has Autotools (`configure.ac`, `Makefile.am`, libtool, `config.h`, + subprojects `ftk`, `flaim`, `sql`, `xflaim`). Do not wrap Autotools from + CMake; replace it with a real CMake build. First required targets are + `FLAIM::ftk` and `FLAIM::flaim`; SQL/XFLAIM/tools/tests/docs can come later. +- FLAIM source license observed by the user: library sources LGPL-2.1; helper + files like `svn2cl.xsl` may have separate licenses such as BSD-3-Clause. + Keep these separated in import docs. +- Forked/integrated mars components that become project services live in the + repository root, matching existing style such as `mail`, `admin`, and + `dosutils`. `mars-tinyldap` belongs in the root, not `third_party`, because it + will be heavily adapted into `nwdirectory`. +- tinyldap currently has a hand-written Makefile and flat-file/mmap storage. + It needs a real CMake build, not a Makefile wrapper. Standalone remains + `tinyldap`; mars-nwe integration builds `nwdirectory`. +- For tinyldap/nwdirectory, first CMake split can expose internal targets such as + `tinyldap::asn1`, `tinyldap::ldap`, `tinyldap::ldif`, `tinyldap::auth`, + `tinyldap::storage`, and `tinyldap::server`. Replace flat-file storage with + `libdirectory -> libflaim` later. +- Old tinyldap TLS code can remain reference/legacy/standalone-only; mars-nwe + `nwdirectory` TLS should go through `nwtls`/wolfSSL. + +Schema/import direction: + +- Do not invent NetWare 4.11 schema by hand if a real source can be obtained. + The user expects the complete schema to be hidden in NetWare 4.11 installation + material such as `install.dat`; a real 4.11 install may be needed to extract + it. +- `.SCH` files such as uploaded `NLS.SCH` are useful format examples/fragments. + They contain readable ASN.1-like `ATTRIBUTE` and `OBJECT-CLASS` blocks, but + are not the full schema truth. +- `nwsetup` should eventually support native NetWare 4.11 schema import, `.SCH` + fragment import, and LDIF import/export. LDIF remains human-readable, + diffable, and testable, but the canonical runtime representation is + `libdirectory` schema objects stored in `libflaim`. +- tinyldap has useful ASN.1 BER/DER and LDIF code (`scan_asn1*`, `fmt_asn1*`, + `asn1dump`, `ldif_parse.c`), but it does not appear to be an NDS `.SCH` or + NetWare schema importer. Reuse ideas/code carefully through the + `nwdirectory` fork, but plan a dedicated schema import layer. +- Samba `source4/dsdb/schema` and setup schema conversion code are useful + references for OID/prefixMap/schema-loading ideas, but Samba is GPL-family; do + not blindly copy code into mars-nwe. Use as a reference and implement a + mars-nwe-native importer/OID module. ## Patch workflow