From 5bf65f4483801b870502859ea98e9f701927eb23 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Tue, 2 Jun 2026 20:51:01 +0000 Subject: [PATCH] docs: document source subtree layout rules --- AI.md | 23 +++++++++++- REDESIGN.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++ TODO.md | 26 +++++++++++++ 3 files changed, 153 insertions(+), 1 deletion(-) diff --git a/AI.md b/AI.md index 5fd1f9f..03da527 100644 --- a/AI.md +++ b/AI.md @@ -1279,4 +1279,25 @@ Next patch number should be `0253`. instead keep shared parser/handler branches shared and place the appropriate `Request:`/`Response:` notes next to the relevant case labels. -Next patch number should be `0261`. +## 2026-06-02 - Patch 0261 source/header subtree layout rules + +- Documented the planned large-source-file split as a module-subtree layout, + not a semantic provider change. Source files should move under + `src//` while headers mirror the same hierarchy under + `include//`. +- Keep ownership names explicit: `nwconn` code stays under `src/nwconn/`, + `nwbind` code under `src/nwbind/`, `nwqueue` code under `src/nwqueue/`, + `nwnds` code under `src/nwnds/`, and directory code under + `src/nwdirectory/`. +- Flat headers remain umbrella headers. For example, `include/nwbind.h` should + include public headers from `include/nwbind/*.h`; do the same later for + `nwconn.h`, `nwqueue.h`, `nwnds.h`, and `nwdirectory.h`. +- Private implementation headers should be named `include//internal.h` + and may only be included by files in the matching `src//` subtree. +- Mechanical move/split patches must not change runtime behavior and must not be + combined with endpoint semantics, provider IPC changes, or switch cleanup. +- Start with build-system support for `src//*.c` plus + `include//*.h`, then move smaller modules such as `nwdirectory` before + splitting very large files such as `nwconn.c` and `nwbind.c`. + +Next patch number should be `0262`. diff --git a/REDESIGN.md b/REDESIGN.md index f2e7d6c..c24bda0 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -729,6 +729,111 @@ part is that future code should avoid making `nwbind` a catch-all sink for unrelated NCPs just because it already has an IPC path. +## Source and header subtree layout + +Large-file cleanup should preserve the same logical ownership names used by the +provider design. Split large modules into matching source and header subtrees +instead of creating unrelated flat files: + +```text +src/ + nwconn/ + nwconn.c + broadcast.c + sync.c + files.c + serverinfo.c + timesync.c + rpc.c + extension.c + + nwbind/ + nwbind.c + objects.c + properties.c + sets.c + auth.c + monitor.c + + nwqueue/ + nwqueue.c + jobs.c + print.c + + nwnds/ + nwnds.c + objects.c + schema.c + + nwdirectory/ + nwdirectory.c + path.c + namespace.c + volume.c + trustees.c + +include/ + nwconn/ + nwconn.h + broadcast.h + sync.h + files.h + serverinfo.h + timesync.h + rpc.h + extension.h + internal.h + + nwbind/ + nwbind.h + objects.h + properties.h + sets.h + auth.h + monitor.h + internal.h + + nwqueue/ + nwqueue.h + jobs.h + print.h + internal.h + + nwnds/ + nwnds.h + objects.h + schema.h + internal.h + + nwdirectory/ + nwdirectory.h + path.h + namespace.h + volume.h + trustees.h + internal.h +``` + +The old flat module headers remain as compatibility and convenience umbrella +headers. For example, `include/nwbind.h` should include the public headers +under `include/nwbind/*.h`; callers that need all public bindery declarations +can keep including `nwbind.h`, while split implementation files may include +narrower headers such as `nwbind/monitor.h` or `nwbind/properties.h`. Use the +same umbrella pattern for `nwconn.h`, `nwqueue.h`, `nwnds.h`, and +`nwdirectory.h` as those modules move. + +`include//internal.h` is a private module header. It may only be +included by files in the matching `src//` subtree. If another module +needs a declaration, that declaration belongs in an explicit public header under +`include//` and can be re-exported by the flat umbrella header. + +This layout is compatible with the later provider split, but it is not the same +thing as a process split. A mechanical move from `src/nwconn.c` to +`src/nwconn/sync.c`, or from `src/nwbind.c` to `src/nwbind/monitor.c`, must not +change runtime behavior. Build-list changes and include-path changes belong in +the same mechanical move patch; endpoint semantics, provider IPC, and switch +cleanup belong in later semantic patches. + ## Provider boundary versus process boundary A provider boundary is not the same thing as a Unix process boundary. This is diff --git a/TODO.md b/TODO.md index af6bb08..4aed987 100644 --- a/TODO.md +++ b/TODO.md @@ -173,6 +173,32 @@ Current status: follow-up. For example, SDK group `0x2222/23` is the top-level wire `case 0x17`; SDK group `0x2222/123` is top-level wire `case 0x7b`. + +#### Source/header subtree layout migration + +Current status: + +- Patch `0261` documents the target source/header subtree layout in `AI.md` and + `REDESIGN.md`. Large modules should move into `src//` and their + headers should mirror that under `include//`. +- Flat headers such as `include/nwbind.h` remain umbrella headers that include + the public headers from `include/nwbind/*.h`; the same pattern should be used + for `nwconn.h`, `nwqueue.h`, `nwnds.h`, and `nwdirectory.h`. +- Private module headers use `include//internal.h` and may only be + included by files in the matching `src//` subtree. +- This is a mechanical layout rule only. Move/split patches must not change + runtime behavior, endpoint semantics, provider IPC, or active switch/fall- + through structure. + +Follow-up: + +- Add build-system support for `src//*.c` and module-qualified include + paths. +- Move `nwdirectory` into `src/nwdirectory/` and `include/nwdirectory/` first as + a smaller layout proof. +- Then move `nwconn`, `nwbind`, `nwqueue`, and `nwnds` shells into matching + subtrees before splitting their large files by topic. + Endpoint coverage index: - SDK `0x2222/23` / wire `0x17` File Server Environment: the audit has covered