docs: retrofit endpoint stub scope notes
This commit is contained in:
Mario Fetka
27
AI.md
27
AI.md
@@ -11,18 +11,18 @@ 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 0205
|
||||
## Current handoff status after patch 0206
|
||||
|
||||
The current accepted patch line in this chat is expected to include:
|
||||
|
||||
- endpoint-audit/documentation patches through `0176-docs-audit-direct-lifecycle-buffer-endpoints.patch`;
|
||||
- redesign documentation patches `0177` through `0198`;
|
||||
- endpoint-audit/documentation patches `0199` through `0205`;
|
||||
- latest expected patch name: `0205-docs-clarify-missing-endpoint-stub-scope.patch`.
|
||||
- endpoint-audit/documentation patches `0199` through `0206`;
|
||||
- latest expected patch name: `0206-docs-retrofit-stub-scope-notes.patch`.
|
||||
|
||||
When continuing in a new chat, first ask the user which patch was actually last
|
||||
applied. If they confirm `0205`, build the next patch as `0206-...` against a
|
||||
tree that already contains `0205`. If any patch failed or was skipped, rebuild
|
||||
applied. If they confirm `0206`, build the next patch as `0207-...` against a
|
||||
tree that already contains `0206`. If any patch failed or was skipped, rebuild
|
||||
against the last confirmed applied patch instead of assuming the file in
|
||||
`/mnt/data` was accepted.
|
||||
|
||||
@@ -213,8 +213,8 @@ Schema/import direction:
|
||||
|
||||
## Current protocol audit scope
|
||||
|
||||
- The current endpoint documentation/audit pass is scoped to compatibility NCPs through NetWare 3.x by default, including NetWare 1.x/2.x legacy calls where they are documented. Bucket endpoints by the oldest NetWare generation that documents them: put 1.x/2.x legacy calls in their own sections, keep the remaining through-3.x compatibility calls in the 3.x/default section, and put endpoints introduced in NetWare 4.x or later in a separate planning/stub section.
|
||||
- NetWare 4.x/OES/MOAB-only endpoints are not part of the default implementation target. Already implemented compatibility code must not be removed or wrapped just because it is 4.x-era; only new, not-yet-implemented 4.x stubs should be placed behind `#if MARS_NWE_4`. `MARS_NWE_4` is currently hard-disabled in `include/config.h.cmake` and should stay `0` unless the user explicitly asks to start that work.
|
||||
- The current endpoint documentation/audit pass is scoped to compatibility NCPs through NetWare 3.x by default, including NetWare 1.x/2.x legacy calls where they are documented. Bucket endpoints by the oldest NetWare generation that documents them: put 1.x/2.x legacy calls in their own sections, keep the remaining through-3.x compatibility calls in the 3.x/default section, and put endpoints introduced in NetWare 4.x in a separate planning/stub section. Do not create stub work merely for NetWare 5.x/OES/MOAB/newer endpoints.
|
||||
- NetWare 4.x-only endpoints are not part of the default implementation target yet, but they are the current forward-planning target. Already implemented compatibility code must not be removed or wrapped just because it is 4.x-era; only new, not-yet-implemented 4.x stubs should be placed behind `#if MARS_NWE_4`. Do not add disabled stubs for 5.x/OES/MOAB/newer calls unless the user explicitly changes the target scope later. `MARS_NWE_4` is currently hard-disabled in `include/config.h.cmake` and should stay `0` unless the user explicitly asks to start that work.
|
||||
- When a `0x2222` group or subfunction is forwarded out of `nwconn.c`, follow the handoff before declaring the endpoint documented. `nwconn.c` should document the handoff and the exact header/payload bytes that are preserved or rewritten before forwarding; the destination file (for example `nwbind.c`) must document the concrete subfunction request/reply layout at the real handler. Do not stop at a comment such as `nwbind must do prehandling`, `nwbind must do the rest`, or `handled by nwbind`.
|
||||
- For forwarded paths, document any nwconn-side payload mutation as part of the audit. Examples in the current tree include queue create path expansion, queue job file-handle insertion, quota bindery prehandling, and semaphore/message group forwarding. If a forwarded subfunction is not audited yet, record it as a target-file follow-up rather than only documenting the nwconn dispatcher.
|
||||
- For documentation-only endpoint patches, do not change parser offsets, byte order, reply layout, or completion behavior. Always compare the code parser/reply layout against the applicable SDK/WebSDK/PDF request format and, when available, the uploaded SDK include prototypes. If the code differs from the SDK layout, document the concrete difference inline and mirror it in `TODO.md` for later testing. If it matches, say so in the patch summary so the audit trail is clear.
|
||||
@@ -436,10 +436,15 @@ user.org.mars-nwe.afp.prodos-info=0x010203040506
|
||||
|
||||
## Latest endpoint audit checkpoint
|
||||
|
||||
As of patch `0204-docs-split-old-file-io-endpoint-notes.patch`, the latest
|
||||
audited block is still the old direct file-I/O group in `src/nwconn.c`.
|
||||
As of patch `0206-docs-retrofit-stub-scope-notes.patch`, the latest
|
||||
audited endpoint block is still the old direct file-I/O group in `src/nwconn.c`.
|
||||
Patch 0204 is a style follow-up to 0203: it splits the request/reply/coverage
|
||||
notes so each endpoint documents its own audit directly at its `case` label:
|
||||
notes so each endpoint documents its own audit directly at its `case` label.
|
||||
Patches 0205 and 0206 only clarify the missing-endpoint stub scope: source
|
||||
stubs are for 1.x/2.x/3.x compatibility gaps and planned 4.x gaps, not for
|
||||
NetWare 5.x/OES/MOAB/newer endpoints during the current audit.
|
||||
|
||||
The last audited endpoint block contains:
|
||||
|
||||
- `0x2222/65` / wire `0x41` Open File (old);
|
||||
- `0x2222/66` / wire `0x42` Close File;
|
||||
@@ -460,7 +465,7 @@ for example AFP `0x2222/35`, EA `0x2222/86`, namespace `0x2222/87`, packet
|
||||
burst `0x2222/97`/`101`, or resume deeper `0x2222/23` bindery/property/admin
|
||||
subfunction coverage, unless the user requests a specific family first.
|
||||
|
||||
The next patch number should be `0206` if `0205` was applied.
|
||||
The next patch number should be `0207` if `0206` was applied.
|
||||
|
||||
Remember: for every new endpoint-audit patch, also update this AI handoff file
|
||||
with the latest audited block and expected next patch number. Put detailed
|
||||
|
||||
@@ -202,8 +202,9 @@ This table would help with the ongoing endpoint audit:
|
||||
- SDK/PDF/WebSDK listed and forwarded;
|
||||
- SDK/PDF/WebSDK listed but disabled as a future stub;
|
||||
- SDK/PDF/WebSDK listed but absent from the current compatibility target;
|
||||
- later NetWare 4.x/OES/MOAB endpoint, not part of the default NetWare 3.x
|
||||
compatibility target.
|
||||
- planned NetWare 4.x endpoint, not part of the default NetWare 3.x
|
||||
compatibility target, or later 5.x/OES/MOAB/newer endpoint recorded as
|
||||
prose-only/out-of-scope with no disabled source stub.
|
||||
|
||||
The first version should not drive runtime dispatch. It should only make review
|
||||
and missing-endpoint checks less error-prone.
|
||||
@@ -2193,7 +2194,7 @@ This redesign should not:
|
||||
|
||||
- change protocol behavior merely to match a cleaner abstraction;
|
||||
- remove NetWare 1.x/2.x/3.x compatibility paths;
|
||||
- enable NetWare 4.x/OES/MOAB-only endpoints by default;
|
||||
- enable NetWare 4.x endpoints by default, or create stubs for NetWare 5.x/OES/MOAB/newer endpoints during the current planning scope;
|
||||
- replace existing mars-nwe path, bindery, queue, AFP, trustee, or salvage
|
||||
backends with parallel databases;
|
||||
- add a large external message bus dependency;
|
||||
|
||||
20
TODO.md
20
TODO.md
@@ -151,9 +151,10 @@ NetWare 4.x planning/stub bucket:
|
||||
leave that code in place. Track them in the 4.x bucket for future cleanup,
|
||||
tests, and field mapping rather than moving them into the default 3.x TODO
|
||||
list or hiding them behind `MARS_NWE_4`.
|
||||
- Any additional not-yet-implemented 4.x/OES/MOAB endpoint discovered later
|
||||
- Any additional not-yet-implemented NetWare 4.x endpoint discovered later
|
||||
should be documented as a plan and, if a source stub is useful, guarded with
|
||||
`#if MARS_NWE_4` while the macro remains `0`.
|
||||
`#if MARS_NWE_4` while the macro remains `0`. Do not add source stubs
|
||||
merely for NetWare 5.x/OES/MOAB/newer endpoints during the current audit.
|
||||
|
||||
#### SDK-listed 0x2222 blocks not yet endpoint-audited
|
||||
|
||||
@@ -214,17 +215,20 @@ SDK-listed blocks that do not currently show a top-level handler in
|
||||
SDK `0x2222/131` / wire `0x83` RPC/NLM-control style calls appear in the
|
||||
PDF/WebSDK index but do not currently show top-level handlers in
|
||||
`src/nwconn.c`. These are likely later-generation buckets, but each must be
|
||||
confirmed against the includes/WebSDK before adding guarded stubs.
|
||||
confirmed against the includes/WebSDK before adding guarded stubs. Only
|
||||
endpoints bucketed as 1.x/2.x/3.x compatibility or planned 4.x work should
|
||||
receive disabled source stubs.
|
||||
|
||||
Follow-up:
|
||||
|
||||
- When auditing one of these blocks, first check whether an existing handler is
|
||||
reached through `nwconn.c`, `nwbind.c`, or a queue/salvage/helper prehandler.
|
||||
Only add a missing-endpoint TODO or guarded stub after that handoff search.
|
||||
- Do not add every SDK-listed 4.x/OES endpoint to the active TODO list. Put it
|
||||
in the NetWare 4.x planning bucket, and only add a disabled `#if MARS_NWE_4`
|
||||
stub when the user asks for that planning marker and no existing implementation
|
||||
is present.
|
||||
- Do not add every later SDK-listed endpoint to the active TODO list. Put
|
||||
NetWare 4.x items in the NetWare 4.x planning bucket, and only add a disabled
|
||||
`#if MARS_NWE_4` stub when that 4.x planning marker is useful and no existing
|
||||
implementation is present. NetWare 5.x/OES/MOAB/newer items should remain
|
||||
prose-only/out-of-scope unless the target scope changes.
|
||||
|
||||
#### Old direct file/logical/physical synchronization calls
|
||||
|
||||
@@ -511,7 +515,7 @@ Follow-up:
|
||||
- The NetWare 1.x/2.x/3.x-compatible `0x2222/22` endpoint layout pass is
|
||||
covered through the documented SDK `22/48` namespace call, with the newly
|
||||
found SDK `22/12`, `22/35`, and `22/36` gaps tracked as disabled stubs/TODO
|
||||
items. Continue with the next non-4.x/OES-only group after this block.
|
||||
items. Continue with the next compatibility group after this block; 5.x/OES-only groups are not current stub targets.
|
||||
|
||||
|
||||
#### Semaphore group 0x2222/32
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
/* serial number (4 byte) */
|
||||
#define NETWORK_APPL_NMBR 0x2222 /* application number (2 byte) */
|
||||
|
||||
#define MARS_NWE_4 0 /* NetWare 4.x/OES-only endpoint stubs: disabled by default */
|
||||
#define MARS_NWE_4 0 /* NetWare 4.x endpoint stubs: disabled by default */
|
||||
|
||||
#define MAX_CONNECTIONS @MAX_CONNECTIONS@
|
||||
/* max. number of simultaneous */
|
||||
|
||||
Reference in New Issue
Block a user