0444 docs: record provider handoff audit and enum vocabulary

AI.md

@@ -14,6 +14,7 @@ Keep it short enough to read before touching code.
    - `doc/NSS_NAMESPACE_AUDIT.md`
    - `doc/NSS_PUBLIC_CORE_AUDIT.md`
    - `doc/NWFS_SALVAGE_COMPRESSION_TOOLS.md`
+   - `doc/HANDOFF_AUDIT.md`
 3. Do not assume an older bundle is current.  Use the latest applied user state
    or the latest bundle/patch explicitly accepted by the user.
 4. Default language with the user is German; repository documentation remains
@@ -72,6 +73,12 @@ and no INI option may enable it.  `nwlog`/zlog remains a facade/backend plan,
 not a reason to call zlog directly.
 See `doc/LOG_LEVEL_AUDIT.md`.
 
+Before namespace code changes, use the handoff audit rules in `doc/HANDOFF_AUDIT.md`.
+New namespace/NWFS work must not add new magic `return(-1)` / `return(-2)` paths.
+Use the provider names in `include/ncp_endpoint.h` for audits and future endpoint
+tables, but do not wire the enum into runtime dispatch until the current
+`nwconn` to `nwbind` handoff sites are annotated.
+
 Then begin the namespace track:
 
 1. Start with DOS namespace compatibility for NetWare 1.x/2.x/3.x clients.

ENDPOINTS.md

@@ -1,5 +1,11 @@
 # NCP endpoint audit
 
+
+Provider and status vocabulary for future endpoint table work is declared in
+`include/ncp_endpoint.h`.  The current tables remain documentation/audit data;
+the enum header must not be treated as runtime dispatch until the `nwconn` to
+`nwbind` magic-return paths are fully annotated.
+
 This file is the detailed endpoint audit for MARS-NWE.  It is deliberately more
 mechanical than `TODO.md`: it records the NetWare SDK/NDK endpoint numbers, the
 wire/code selectors used by MARS-NWE, the implementation state, and the source

REDESIGN.md

@@ -323,6 +323,12 @@ This table would help with the ongoing endpoint audit:
 The first version should not drive runtime dispatch.  It should only make review
 and missing-endpoint checks less error-prone.
 
+The initial shared vocabulary for this audit now lives in
+`include/ncp_endpoint.h`.  That header is intentionally declarative: it names
+logical providers, endpoint flags, current compatibility dispatch results, and
+future handoff reply kinds without changing runtime dispatch.  Keep it as a
+review aid until the active `nwconn.c` magic handoff sites are annotated.
+
 The table should be able to represent a selector path rather than only a single
 subfunction.  This matters for later NetWare 4.x families and for extension
 mechanisms.  The first selector element is usually the documented subfunction
@@ -629,6 +635,28 @@ This would also make the endpoint documentation pass easier: each audited
 endpoint can identify the provider, the request layout, the logical reply kind,
 the reply payload layout, and any caller-side post-processing.
 
+### NSS message-layer references
+
+The imported NSS sources contain several useful references for handoff design,
+but they should not be treated as a drop-in MARS IPC runtime.  The relevant
+patterns are:
+
+- `include/nwfs/nss/sdk/include/msg.h` and related `msg*.h` files define an
+  object/key/method/message vocabulary with `MSG_Call`, `MSG_Send`,
+  `MSG_SendKey`, `mpkMSG_Call` and `zMSG_Call`.  This is useful precedent for
+  method-based provider calls, but the NSS Door/Object runtime is too large and
+  too NSS-specific for the MARS provider boundary.
+- `src/nwfs/nss/common/fsmsg.c` and `fsmsg.h` show NSS filesystem method tables.
+  These are useful for future libnwfs object methods, not for replacing the NCP
+  endpoint dispatcher.
+- `include/nwfs/nss/sdk/include/nsskr.h` and the `NSSKR_REQUEST` handling in
+  `src/nwfs/nss/lsaSuper.c` show a simple signature/version/opcode request
+  header with typed payloads.  That is a good reference for a future native
+  MARS handoff header.
+
+`doc/HANDOFF_AUDIT.md` records the current MARS magic-return sites and the NSS
+references in one focused place.
+
 ### Migration order for handoff normalization
 
 The safe order is:

TODO.md

@@ -17,6 +17,7 @@ why it matters, and where the work belongs.
 | Logging level cleanup | P0 | Pre-namespace audit done / cleanup pending | Keep new code at levels `1..5`; review touched legacy call sites while namespace code moves. |
 | Salvage metadata / backup-tool compatibility | P0 | Planned next / unfinished | Keep `.recycle` payloads; make `netware.metadata` authoritative for deleted entries; deprecate `.salvage` JSON. |
 | NetWare 3.x NCP endpoint completion | P1 | Active audit + implementation | `ENDPOINTS.md` is the detailed decimal/hex audit table; keep this TODO as the short implementation queue. |
+| NCP provider handoff cleanup | P0 | Pre-namespace audit started | Use `doc/HANDOFF_AUDIT.md` and `include/ncp_endpoint.h`; annotate real `nwconn` magic handoffs before changing control flow. |
 | NetWare 4.x endpoint compatibility | P2 | Partial / guarded | `ENDPOINTS.md` tracks active compatibility vs guarded 4.x selectors. |
 | Admin, queues, printing and TTS | P2 | Ongoing | Console-operator model, queue path case handling, print/TTS compatibility cleanup. |
 | Test infrastructure | P1 | Ongoing | CTest where offline, live all-smokes where server/client state is required, DOS tool smokes. |
@@ -25,6 +26,22 @@ why it matters, and where the work belongs.
 | Transport split and IPX/TCP config | P2 | Documented plan | Keep TCP/IP and IPX under `nwtransport`; make IPX kernel setup internal later, with `ipx-utils` as fallback/debug tooling. |
 | External file reconciliation | P1 | Planned next | Add libnwfs watcher/scanner support so Samba, rsync and host-created files receive `netware.metadata` and namespace records. |
 
+## NCP provider handoff cleanup
+
+Before namespace implementation grows new provider paths, finish the first
+handoff audit pass:
+
+- keep `include/ncp_endpoint.h` declarative until endpoint rows and magic-return
+  sites are annotated;
+- do not bulk-rewrite every `return(-1)` in the tree, because most are ordinary
+  local error returns;
+- start with the active `nwconn.c` dispatcher clusters listed in
+  `doc/HANDOFF_AUDIT.md`;
+- add provider/result flags to endpoint-table work before replacing existing
+  `return(-1)` / `return(-2)` handoff behaviour;
+- new namespace/NWFS code may use provider vocabulary, but must not create new
+  process-specific magic return conventions.
+
 ## NetWare 3.x endpoint implementation queue
 
 Default runtime work should finish documented NetWare 1.x/2.x/3.x behaviour

doc/HANDOFF_AUDIT.md

@@ -0,0 +1,119 @@
+# NCP handoff and provider audit
+
+This note records the current `nwconn` to `nwbind` handoff model and the NSS
+message-layer references that can guide a later cleanup.  It is an audit and
+vocabulary document first; it does not change runtime dispatch.
+
+## Current MARS behaviour
+
+The active MARS server path still uses the historical two-process split:
+
+```text
+client transport -> nwconn -> local handler or nwbind handoff -> client reply
+```
+
+`nwconn.c` owns the client-facing connection, task, sequence and final network
+reply path for most requests.  `nwbind.c` owns bindery state and also handles
+message, semaphore, queue, accounting and several server-management selectors.
+
+The important problem is that the active `nwconn.c` dispatcher uses magic integer
+returns for process handoff:
+
+| Result | Current dispatcher meaning |
+| ---: | --- |
+| `0` | request handled locally; send the local reply path |
+| `-1` | forward to `nwbind`; `nwbind` handles the remaining operation/reply |
+| `-2` | forward to `nwbind` after `nwconn` saved or rewrote request state; `nwconn` may do post-processing |
+
+This meaning is scoped.  A random `return(-1)` in helper code, salvage code,
+SSL compatibility, or even inside `nwbind.c` is usually just a local error or an
+unsupported selector.  It is not automatically an inter-process handoff marker.
+
+`include/ncp_endpoint.h` now records the shared names that future cleanup patches
+should use for audits and endpoint tables:
+
+- `NcpProvider` for logical owner/provider names;
+- `NcpDispatchResult` for current `nwconn` dispatcher compatibility results;
+- `NcpEndpointFlag` for endpoint table/audit annotations;
+- `NwHandoffReplyKind` for the future normalized provider reply contract.
+
+## Active magic-return sites to audit first
+
+The relevant initial search is not "all `return(-1)` in the tree".  That finds
+ordinary local error returns too.  Start with the active `nwconn.c` dispatcher
+handoff sites and annotate them endpoint-by-endpoint.
+
+Known active `nwconn.c` handoff clusters in the current tree include:
+
+| Area | Current return | Notes |
+| --- | --- | --- |
+| decimal 21 / wire `0x15` Message group | `-1` | Entire group is forwarded to `nwbind` with the NCP 21 group header intact. |
+| decimal 22/33, 22/34 / wire `0x16/0x21`, `0x16/0x22` quota/user restriction prehandling | `-2` | `nwbind` maps bindery object IDs before quota handling. |
+| decimal 22/41 / wire `0x16/0x29` object disk usage/restriction with quota support | `-2` | QUOTA builds forward for ObjectID-to-uid mapping. |
+| decimal 23/20, 23/24 / wire `0x17/0x14`, `0x17/0x18` login paths | `-2` | Bindery authentication prehandling. |
+| decimal 23 queue selectors / wire `0x17/0x68`, `0x17/0x79`, `0x17/0x69`, `0x17/0x7f`, `0x17/0x71`, `0x17/0x7c` | `-2` | Queue job file/prehandling paths. |
+| decimal 23 queue read/change/service selectors / wire `0x17/0x6c`, `0x17/0x7a`, `0x17/0x72`, `0x17/0x73`, `0x17/0x83`, `0x17/0x84` | `-1` or `-2` | Some requests are rewritten with handles before the `nwbind` side completes them. |
+| decimal 23 unknown/default selectors / wire `0x17/*` | `-1` | Catch-all delegation to `nwbind`; must be split from truly unsupported endpoints later. |
+| decimal 24 End of Job / wire `0x18` | `-1` | `nwconn` frees task-local state, then `nwbind` closes remaining print jobs and replies. |
+| decimal 25 Logout / wire `0x19` | `-1` | `nwconn` clears connection-local state, then `nwbind` finishes bindery/print cleanup. |
+| decimal 32 Semaphore / wire `0x20` | `-1` | Group is handled by `nwbind` with a one-byte semaphore subfunction. |
+
+The first functional cleanup should replace comments and endpoint-table metadata
+around these sites before changing control flow.  Do not bulk-rewrite unrelated
+`return(-1)` helper errors.
+
+## Desired provider contract
+
+The later normalized shape is:
+
+```text
+nwconn -> provider request -> provider reply -> nwconn final NCP envelope
+```
+
+Providers should return logical completion plus reply payload, not send raw
+client packets directly.  `nwconn` remains the final owner of the client-visible
+NCP response envelope.  Legacy paths may keep provider-built replies while being
+converted, but new namespace/NWFS work should not introduce new magic return
+values or hidden process-specific reply conventions.
+
+The conceptual reply kinds are the names in `NwHandoffReplyKind`:
+
+| Kind | Meaning |
+| --- | --- |
+| `NW_HANDOFF_REPLY` | provider produced a client NCP completion/payload |
+| `NW_HANDOFF_NO_REPLY` | provider handled the request but no client reply is allowed |
+| `NW_HANDOFF_DEFERRED` | provider accepted the request and will complete later |
+| `NW_HANDOFF_FORWARD` | provider asks the caller to forward to another provider |
+| `NW_HANDOFF_ERROR` | internal provider/handoff failure, mapped centrally |
+
+## NSS references
+
+The imported NSS reference tree contains useful concepts but not a direct MARS
+IPC implementation:
+
+| NSS area | Files | Useful idea | MARS policy |
+| --- | --- | --- | --- |
+| NSS message layer | `include/nwfs/nss/sdk/include/msg.h`, `msgGen.h`, `msgIO.h`; calls in `src/nwfs/nss/common/*.c` | key/object/method/message calls such as `MSG_Call`, `MSG_Send`, `MSG_SendKey`, `mpkMSG_Call`, `zMSG_Call` | Reference only.  Do not import NSS Door/Object runtime as the MARS provider IPC. |
+| NSS filesystem method layer | `src/nwfs/nss/common/fsmsg.c`, `include/nwfs/nss/sdk/include/fsmsg.h` | method tables for NSS file/volume operations | Useful model for future libnwfs object methods, not a replacement for NCP endpoint dispatch. |
+| NSSKR ioctl layer | `include/nwfs/nss/sdk/include/nsskr.h`, `src/nwfs/nss/lsaSuper.c` | signature/version/opcode header plus typed request payloads | Good reference for a simple handoff header shape.  Do not copy the ioctl protocol directly. |
+| `ipc2ncp` headers | `include/nwfs/nss/ipc2ncp.h`, `include/nwfs/nss/sdk/public/ipc2ncp.h` | NCP-to-internal-request boundary vocabulary | Reference while auditing, not a ready-to-use MARS ABI. |
+
+NSS confirms that method/opcode/message boundaries are normal for this problem
+space.  MARS should still use a small, native provider contract rather than a
+large NSS runtime subsystem.
+
+## Migration order
+
+1. Keep `include/ncp_endpoint.h` as vocabulary only.
+2. Add endpoint table rows with provider/result flags before changing switch
+   logic.
+3. Annotate each active `nwconn` magic handoff site with the exact endpoint and
+   provider owner.
+4. Add a small wrapper such as `ncp_handoff_to_provider()` that initially calls
+   the existing `nwbind` path.
+5. Replace magic `return(-1)` / `return(-2)` in the active dispatcher with named
+   `NcpDispatchResult` values only after the audit table can prove which sites
+   are real handoffs.
+6. Convert provider replies to `NwHandoffReplyKind` behind the wrapper.
+7. Only then add new provider processes.  New namespace/NWFS code may start as an
+   in-process provider module without becoming a process.

doc/README.md

@@ -25,6 +25,8 @@ directory small and put new material into topic subdirectories.
   recommended `1..5` policy for new code.
 - `KERNEL_REFERENCE_AUDIT.md` - Linux kernel reference imports, currently the
   disabled Linux 2.4.37.9 SPX implementation.
+- `HANDOFF_AUDIT.md` - current `nwconn`/`nwbind` magic-return audit,
+  provider vocabulary and NSS message-layer references.
 
 ## Layout rule
 

include/ncp_endpoint.h

@@ -0,0 +1,71 @@
+#ifndef _NCP_ENDPOINT_H_
+#define _NCP_ENDPOINT_H_
+
+/*
+ * Common NCP endpoint and provider vocabulary.
+ *
+ * This header is intentionally declarative first.  It gives audits, future
+ * endpoint tables, and later dispatcher cleanup patches one shared set of
+ * names without changing the current switch/return-value behaviour.
+ */
+
+typedef enum ncp_provider_e {
+  NCP_PROVIDER_UNKNOWN = 0,
+  NCP_PROVIDER_NWCONN,
+  NCP_PROVIDER_NWBIND,
+  NCP_PROVIDER_BINDERY,
+  NCP_PROVIDER_QUEUE,
+  NCP_PROVIDER_NWFS,
+  NCP_PROVIDER_NAMESPACE,
+  NCP_PROVIDER_SEMAPHORE,
+  NCP_PROVIDER_MESSAGE,
+  NCP_PROVIDER_SERVERMGMT,
+  NCP_PROVIDER_TRANSPORT,
+  NCP_PROVIDER_DIRECTORY,
+  NCP_PROVIDER_NWNDS,
+  NCP_PROVIDER_NCP_EXTENSION,
+  NCP_PROVIDER_AFP,
+  NCP_PROVIDER_ACCOUNTING,
+  NCP_PROVIDER_AUTH,
+  NCP_PROVIDER_LEGACY_STUB
+} NcpProvider;
+
+/*
+ * Current nwconn dispatcher compatibility values.
+ *
+ * Only the relevant nwconn dispatch path gives -1/-2 the handoff meaning
+ * described here.  Other functions may still return -1 as a normal local error.
+ */
+typedef enum ncp_dispatch_result_e {
+  NCP_DISPATCH_DONE = 0,
+  NCP_DISPATCH_FORWARD_NWBIND = -1,
+  NCP_DISPATCH_FORWARD_NWBIND_POST = -2,
+  NCP_DISPATCH_NOT_IMPLEMENTED = 1,
+  NCP_DISPATCH_BAD_REQUEST = 2,
+  NCP_DISPATCH_INTERNAL_ERROR = 3
+} NcpDispatchResult;
+
+typedef enum ncp_endpoint_flag_e {
+  NCP_ENDPOINT_LOCAL = 1U << 0,
+  NCP_ENDPOINT_FORWARDED = 1U << 1,
+  NCP_ENDPOINT_NEEDS_POSTPROCESS = 1U << 2,
+  NCP_ENDPOINT_PROVIDER_BUILDS_REPLY = 1U << 3,
+  NCP_ENDPOINT_NETWARE3 = 1U << 4,
+  NCP_ENDPOINT_NETWARE4_GUARDED = 1U << 5,
+  NCP_ENDPOINT_REFERENCE_ONLY = 1U << 6,
+  NCP_ENDPOINT_LEGACY_STUB = 1U << 7
+} NcpEndpointFlag;
+
+/*
+ * Future normalized provider handoff reply kind.  These are internal MARS
+ * results, not client-visible NCP completion codes.
+ */
+typedef enum nw_handoff_reply_kind_e {
+  NW_HANDOFF_REPLY = 0,
+  NW_HANDOFF_NO_REPLY,
+  NW_HANDOFF_DEFERRED,
+  NW_HANDOFF_FORWARD,
+  NW_HANDOFF_ERROR
+} NwHandoffReplyKind;
+
+#endif