feat(fs): ForkContainers capability + §10d rename/shortname coordination (phase 3)

Make the fork adapter the owner of its metadata containers and let a same-host-path
peer follow them, so an AFP+EtherDFS/SMB pair sharing one host path stays
metadata-consistent across a rename/delete.

- New optional fs.ForkContainers{ MetadataPaths(storePath) []string }: the
  AppleDouble base returns its single sidecar path (whatever layout placed it);
  ads/xattr/nofork keep metadata with the file and return nil (don't implement it).
  shareFS forwards the capability. shareFS.Rename/Remove already delegate the
  container move/delete to the adapter (MoveMetadata/DeleteMetadata) — the adapter
  owns what its containers are; docs clarified.
- share.Reactor coordination: NamedPath gains an optional FS fs.ForkFS field (AFP/
  SMB/NCP set it from v.FS()/sh.FS()). On a foreign OpRename under a shared root,
  Reactor.coordinate re-derives the new name's shortname via fs.Named so the peer's
  NameEngine mapping is fresh and stable; MetadataPathsFor(np, hostPath) surfaces the
  sidecars the peer must re-stat (host->store conversion + ForkContainers) for the
  deferred wire-push slice.

Wire push (AFP attention / SMB CHANGE_NOTIFY) stays DEFERRED — this lands the
in-memory metadata + shortname consistency and the seam the push will consume.

Tests: fork_containers_test.go (capability present on appledouble per layout,
absent/nil for ride-with-file adapters, forwarded through shareFS);
reactor_coord_test.go (MetadataPathsFor host->store + outside/no-FS nil; coordinate
re-derives a stable 8.3 shortname on foreign rename; nil-FS no-op).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: pgodwin

core/fs/fork.go

@@ -284,6 +284,15 @@ func (e *appleDoubleForkEngine) DeleteMetadata(path string) error {
 	return err
 }
 
+// MetadataPaths reports the AppleDouble sidecar store path for a data path (the
+// fs.ForkContainers capability): the separate container the §10d coordination must
+// follow when a peer service renames/removes the same host file. Exactly one path —
+// this adapter keeps all its metadata in a single sidecar (whatever layout the variant
+// places it at).
+func (e *appleDoubleForkEngine) MetadataPaths(storePath string) []string {
+	return []string{e.sidecar(storePath)}
+}
+
 // --- resourceForkFile (File) ---
 
 func (f *resourceForkFile) ReadAt(p []byte, off int64) (int, error) {

core/fs/fork_containers_test.go

@@ -0,0 +1,74 @@
+package fs
+
+import "testing"
+
+// TestForkContainers_AppleDoubleReportsSidecar proves each AppleDouble-family adapter
+// implements fs.ForkContainers and reports exactly its sidecar path (per layout).
+func TestForkContainers_AppleDoubleReportsSidecar(t *testing.T) {
+	cases := []struct {
+		sidecar func(string) string
+		want    string
+	}{
+		{netatalkSidecarPath, "dir/._file"},
+		{osxZipSidecarPath, "__MACOSX/dir/._file"},
+		{appleDoubleDirSidecarPath, "dir/.AppleDouble/file"},
+	}
+	for _, c := range cases {
+		var eng ForkEngine = newAppleDoubleForkEngine(newMemFS(ShareSpec{}), c.sidecar)
+		fc, ok := eng.(ForkContainers)
+		if !ok {
+			t.Fatalf("appledouble engine does not implement ForkContainers")
+		}
+		got := fc.MetadataPaths("dir/file")
+		if len(got) != 1 || got[0] != c.want {
+			t.Fatalf("MetadataPaths = %v, want [%q]", got, c.want)
+		}
+	}
+}
+
+// TestForkContainers_RideWithFileAdaptersReturnNil proves the adapters whose metadata
+// rides with the data file expose no separate container: nofork implements
+// ForkContainers returning nil OR does not implement it (both mean "no containers"),
+// and ads/xattr likewise. shareFS.MetadataPaths must yield nil for them.
+func TestForkContainers_RideWithFileAdaptersReturnNil(t *testing.T) {
+	for _, name := range []string{"nofork", "ads", "xattr"} {
+		eng, err := forkAdapterByName(name, ShareSpec{}, newMemFS(ShareSpec{}))
+		if err != nil {
+			t.Fatalf("forkAdapterByName(%q): %v", name, err)
+		}
+		if fc, ok := eng.(ForkContainers); ok {
+			if got := fc.MetadataPaths("dir/file"); got != nil {
+				t.Fatalf("%s MetadataPaths = %v, want nil (metadata rides with the file)", name, got)
+			}
+		}
+	}
+}
+
+// TestShareFS_MetadataPathsForwards proves the assembled share stack forwards the
+// optional ForkContainers capability to the fork adapter, and returns nil when the
+// adapter does not provide it.
+func TestShareFS_MetadataPathsForwards(t *testing.T) {
+	// AppleDouble share: the sidecar path is reported through shareFS.
+	ad, err := BuildShare(ShareSpec{FSType: "memfs", ForkBackend: ForkAppleDoubleOSXZip}, nil)
+	if err != nil {
+		t.Fatalf("BuildShare appledouble: %v", err)
+	}
+	fc, ok := ad.(ForkContainers)
+	if !ok {
+		t.Fatal("appledouble share does not expose ForkContainers")
+	}
+	if got := fc.MetadataPaths("dir/a"); len(got) != 1 || got[0] != "__MACOSX/dir/._a" {
+		t.Fatalf("shareFS.MetadataPaths = %v, want [__MACOSX/dir/._a]", got)
+	}
+
+	// nofork share: no separate container.
+	nf, err := BuildShare(ShareSpec{FSType: "memfs", ForkBackend: "nofork"}, nil)
+	if err != nil {
+		t.Fatalf("BuildShare nofork: %v", err)
+	}
+	if fc, ok := nf.(ForkContainers); ok {
+		if got := fc.MetadataPaths("dir/a"); got != nil {
+			t.Fatalf("nofork shareFS.MetadataPaths = %v, want nil", got)
+		}
+	}
+}

core/fs/fs.go

@@ -61,6 +61,23 @@ type ForkEngine interface {
 	DeleteMetadata(path string) error
 }
 
+// ForkContainers is an OPTIONAL capability a fork adapter implements to report the
+// store-relative paths whose rename/remove must accompany the data fork's — i.e. its
+// SEPARATE metadata containers (AppleDouble sidecars, an AppleSingle file). It is the
+// seam the §10d same-host-path coordination uses: when one service renames/removes a
+// file on a host path another service also shares, the peer consults MetadataPaths to
+// know which container files moved alongside the data (so it can re-stat them and
+// re-derive shortnames) without reaching into the other adapter's layout knowledge.
+//
+// An adapter whose metadata RIDES WITH the file — ads (NTFS streams), xattr (extended
+// attributes), nofork (none), native (host fork) — returns nil: there is no separate
+// container path to coordinate. The AppleDouble family returns its sidecar path. The
+// share stack (shareFS) forwards this through to the fork adapter; a fork adapter that
+// does not implement it is treated as "no separate containers" (nil).
+type ForkContainers interface {
+	MetadataPaths(storePath string) []string
+}
+
 // ForkFS is a base FileSystem paired with its mandatory fork adapter (ForkEngine).
 // BuildShare always assembles exactly one fork adapter over the fork-unaware base —
 // resolved by name through the fork-adapter registry (fork_registry.go), defaulting to
@@ -552,8 +569,10 @@ type shareFS struct {
 }
 
 // Rename moves a path and carries its metadata container in one call: the data
-// fork via the FileSystem, then the sidecar/ADS/xattr via the ForkEngine. Callers
-// above the FS therefore never pair Rename with MoveMetadata by hand (§9).
+// fork via the FileSystem, then the container (sidecar/ADS/xattr) via the ForkEngine,
+// which OWNS what its containers are and where they live. Callers above the FS
+// therefore never pair Rename with MoveMetadata by hand (§9). Data-fork-first so a
+// metadata failure leaves the renamed data with a stale-but-present container to retry.
 func (s *shareFS) Rename(old, new string) error {
 	if err := s.FileSystem.Rename(old, new); err != nil {
 		return err
@@ -562,14 +581,26 @@ func (s *shareFS) Rename(old, new string) error {
 }
 
 // Remove deletes a path and its metadata container in one call, metadata first so
-// a failure leaves the data fork in place to retry against (§9).
+// a failure leaves the data fork in place to retry against (§9). The ForkEngine owns
+// which container(s) to drop.
 func (s *shareFS) Remove(path string) error {
 	if err := s.ForkEngine.DeleteMetadata(path); err != nil {
 		return err
 	}
 	return s.FileSystem.Remove(path)
 }
 
+// MetadataPaths forwards the optional fs.ForkContainers capability to the fork adapter:
+// the store-relative container paths (sidecars) that accompany a data path, for §10d
+// same-host-path coordination. A fork adapter whose metadata rides with the file
+// (ads/xattr/nofork) — or that does not implement the capability — yields nil.
+func (s *shareFS) MetadataPaths(storePath string) []string {
+	if fc, ok := s.ForkEngine.(ForkContainers); ok {
+		return fc.MetadataPaths(storePath)
+	}
+	return nil
+}
+
 // ShortName and MediumName derive a per-directory short/medium name for the
 // final path element via the share's NameEngine.
 func (s *shareFS) ShortName(path string) (string, error) {

core/service/afp/afp.go

@@ -173,7 +173,7 @@ func (s *Service) volumeRoots() []share.NamedPath {
 	defer s.mu.Unlock()
 	out := make([]share.NamedPath, 0, len(s.volumes))
 	for _, v := range s.volumes {
-		out = append(out, share.NamedPath{Name: v.Name(), Root: v.sh.Config().Path})
+		out = append(out, share.NamedPath{Name: v.Name(), Root: v.sh.Config().Path, FS: v.FS()})
 	}
 	return out
 }

core/service/ncp/ncp.go

@@ -142,7 +142,7 @@ func (s *Service) volumeRoots() []share.NamedPath {
 	defer s.mu.Unlock()
 	out := make([]share.NamedPath, 0, len(s.vols))
 	for _, v := range s.vols {
-		out = append(out, share.NamedPath{Name: v.Name(), Root: v.sh.Config().Path})
+		out = append(out, share.NamedPath{Name: v.Name(), Root: v.sh.Config().Path, FS: v.FS()})
 	}
 	return out
 }

core/service/smb/smb.go

@@ -168,7 +168,7 @@ func (s *Service) shareRoots() []share.NamedPath {
 	defer s.mu.Unlock()
 	out := make([]share.NamedPath, 0, len(s.shares))
 	for _, sh := range s.shares {
-		out = append(out, share.NamedPath{Name: sh.Name(), Root: sh.sh.Config().Path})
+		out = append(out, share.NamedPath{Name: sh.Name(), Root: sh.sh.Config().Path, FS: sh.FS()})
 	}
 	return out
 }

core/share/reactor.go

@@ -37,10 +37,16 @@ type Reactor struct {
 	count  uint64 // foreign events delivered to the sink (diagnostics / tests)
 }
 
-// NamedPath pairs a share's name with its configured host root, for path matching.
+// NamedPath pairs a share's name with its configured host root, for path matching. FS
+// is the share's bound filesystem (optional): when set, the reactor uses it on a foreign
+// rename/delete to follow the fork adapter's metadata containers (fs.ForkContainers) and
+// re-derive shortnames (fs.Named), so a same-host-path peer stays metadata-consistent.
+// A nil FS still matches paths and notifies — it just skips the container/shortname
+// coordination.
 type NamedPath struct {
 	Name string
 	Root string
+	FS   fs.ForkFS
 }
 
 // NewReactor builds a Reactor for the owning service. origin is the owner's Origin
@@ -81,6 +87,7 @@ func (r *Reactor) loop(ch <-chan bus.Event) {
 		}
 		for _, np := range r.roots() {
 			if underRoot(fe.HostPath, np.Root) || (fe.OldPath != "" && underRoot(fe.OldPath, np.Root)) {
+				r.coordinate(np, fe)
 				r.mu.Lock()
 				r.count++
 				r.mu.Unlock()
@@ -90,6 +97,83 @@ func (r *Reactor) loop(ch <-chan bus.Event) {
 	}
 }
 
+// coordinate keeps a same-host-path peer metadata-consistent with a foreign mutation,
+// using the share's fork adapter and name engine (when the NamedPath carries an FS). On
+// a rename it re-derives the new name's shortname so a later lookup is stable; the
+// metadata containers (fs.ForkContainers) the peer must re-stat are surfaced via
+// MetadataPathsFor for the (deferred) wire-push slice. A nil FS or an adapter without
+// the optional capabilities is a no-op. The data + container MOVE itself is the
+// originating service's adapter's job (atomic on its side); this only refreshes the
+// observing peer's derived state.
+func (r *Reactor) coordinate(np NamedPath, fe fs.Event) {
+	if np.FS == nil {
+		return
+	}
+	// Re-derive the new name's shortname on a rename so the peer's NameEngine has a
+	// fresh, consistent mapping. The stale old-name mapping is harmless (it points at a
+	// name that no longer exists; reverse lookups for the new short name are fresh).
+	if fe.Op == fs.OpRename && fe.HostPath != "" {
+		if store, ok := storeRel(fe.HostPath, np.Root); ok {
+			if named, ok := np.FS.(fs.Named); ok {
+				if ne := named.Names(); ne != nil {
+					dir, base := splitStorePath(store)
+					ne.Bind(dir, base, fs.ShortName)
+					ne.Bind(dir, base, fs.MediumName)
+				}
+			}
+		}
+	}
+}
+
+// MetadataPathsFor returns the store-relative metadata-container paths a share's fork
+// adapter keeps for the host path a foreign event touched — the sidecars a peer must
+// follow on a rename/delete. Empty when the path is outside the share, the share has no
+// FS, or the adapter keeps its metadata with the file (ads/xattr/nofork). The
+// (deferred) wire-push slice consumes this; exposed now so the seam is testable.
+func MetadataPathsFor(np NamedPath, hostPath string) []string {
+	if np.FS == nil || hostPath == "" {
+		return nil
+	}
+	fc, ok := np.FS.(fs.ForkContainers)
+	if !ok {
+		return nil
+	}
+	store, ok := storeRel(hostPath, np.Root)
+	if !ok {
+		return nil
+	}
+	return fc.MetadataPaths(store)
+}
+
+// storeRel converts a host path under root to its share-relative ('/'-separated) store
+// path. ok is false when hostPath is not under root. Comparison is case-folded to match
+// underRoot / the broker's case-insensitive host-path keys.
+func storeRel(hostPath, root string) (string, bool) {
+	if root == "" || hostPath == "" {
+		return "", false
+	}
+	h := strings.TrimRight(hostPath, `/\`)
+	r := strings.TrimRight(root, `/\`)
+	hl := strings.ToLower(h)
+	rl := strings.ToLower(r)
+	if hl == rl {
+		return "", true // the root itself
+	}
+	if !strings.HasPrefix(hl, rl+"/") && !strings.HasPrefix(hl, rl+`\`) {
+		return "", false
+	}
+	rel := h[len(r)+1:]
+	return strings.ReplaceAll(rel, `\`, "/"), true
+}
+
+// splitStorePath splits a '/'-store path into its directory and final element.
+func splitStorePath(p string) (dir, base string) {
+	if i := strings.LastIndexByte(p, '/'); i >= 0 {
+		return p[:i], p[i+1:]
+	}
+	return "", p
+}
+
 // Stop cancels every subscription, ending the reactor goroutines. Idempotent.
 func (r *Reactor) Stop() {
 	r.mu.Lock()

core/share/reactor_coord_test.go

@@ -0,0 +1,93 @@
+package share
+
+import (
+	"testing"
+
+	"github.com/ObsoleteMadness/ClassicStack/core/fs"
+)
+
+// buildCoordShare assembles a real appledouble+memfs ForkFS with a deriving name engine,
+// so the reactor's coordination (shortname re-derive + container paths) has something to
+// act on.
+func buildCoordShare(t *testing.T) fs.ForkFS {
+	t.Helper()
+	ffs, err := fs.BuildShare(fs.ShareSpec{
+		FSType:      "memfs",
+		ForkBackend: fs.ForkAppleDoubleDefault,
+		NameEngine:  "short",
+	}, nil)
+	if err != nil {
+		t.Fatalf("BuildShare: %v", err)
+	}
+	return ffs
+}
+
+// TestMetadataPathsFor proves the reactor surfaces the fork adapter's sidecar container
+// for a host path under the share root (host→store conversion + ForkContainers), and
+// nil for a path outside the share or a share without an FS.
+func TestMetadataPathsFor(t *testing.T) {
+	ffs := buildCoordShare(t)
+	np := NamedPath{Name: "Vol", Root: "/srv/vol", FS: ffs}
+
+	got := MetadataPathsFor(np, "/srv/vol/dir/report")
+	if len(got) != 1 || got[0] != "dir/._report" {
+		t.Fatalf("MetadataPathsFor = %v, want [dir/._report]", got)
+	}
+
+	// Path outside the share root -> nil.
+	if got := MetadataPathsFor(np, "/other/place/file"); got != nil {
+		t.Fatalf("MetadataPathsFor(outside) = %v, want nil", got)
+	}
+
+	// No FS -> nil (still safe).
+	if got := MetadataPathsFor(NamedPath{Name: "Vol", Root: "/srv/vol"}, "/srv/vol/x"); got != nil {
+		t.Fatalf("MetadataPathsFor(no FS) = %v, want nil", got)
+	}
+}
+
+// TestReactorCoordinate_ReDerivesShortnameOnForeignRename proves a foreign rename under a
+// shared root makes the peer's NameEngine produce a stable shortname for the NEW name —
+// the coordination the §10d reactor performs (wire push still deferred). It calls
+// coordinate directly (deterministic) rather than racing the async loop.
+func TestReactorCoordinate_ReDerivesShortnameOnForeignRename(t *testing.T) {
+	ffs := buildCoordShare(t)
+	np := NamedPath{Name: "Vol", Root: "/srv/vol", FS: ffs}
+	r := NewReactor("afp", func() []NamedPath { return []NamedPath{np} }, nil)
+
+	// A long name with no prior mapping: before coordination the engine has not bound it.
+	named, ok := ffs.(fs.Named)
+	if !ok {
+		t.Fatal("share FS is not fs.Named")
+	}
+	ne := named.Names()
+
+	// Simulate SMB renaming "dir/old.txt" -> "dir/a-very-long-new-name.txt" on the shared
+	// host path; the AFP reactor coordinates.
+	ev := fs.Event{
+		Op:       fs.OpRename,
+		OldPath:  "/srv/vol/dir/old.txt",
+		HostPath: "/srv/vol/dir/a-very-long-new-name.txt",
+		Origin:   "smb",
+	}
+	r.coordinate(np, ev)
+
+	// The new name now has a derived shortname bound (idempotent + stable on re-lookup).
+	first := ne.Bind("dir", "a-very-long-new-name.txt", fs.ShortName)
+	second := ne.Bind("dir", "a-very-long-new-name.txt", fs.ShortName)
+	if first == "" || first != second {
+		t.Fatalf("shortname not stable after coordinate: %q vs %q", first, second)
+	}
+	// A DOS 8.3 shortname is at most 12 chars (8 + dot + 3) — proving it derived, not
+	// passed the long name through.
+	if len(first) > 12 {
+		t.Fatalf("shortname %q not 8.3-derived (len %d)", first, len(first))
+	}
+}
+
+// TestReactorCoordinate_NilFSIsNoOp proves coordination is safe when a NamedPath carries
+// no FS (path-only matching still works elsewhere).
+func TestReactorCoordinate_NilFSIsNoOp(t *testing.T) {
+	r := NewReactor("afp", func() []NamedPath { return nil }, nil)
+	// Must not panic.
+	r.coordinate(NamedPath{Name: "Vol", Root: "/srv/vol"}, fs.Event{Op: fs.OpRename, HostPath: "/srv/vol/x"})
+}