feat: per-file example tests — action, registry, fs, api, string, path, service, error, array

33 new examples across 8 dedicated files. Removed phantom CleanPath
(in RFC spec but never implemented — spec drift caught by examples).

545 tests total, 84.8% coverage. Every major primitive has compilable
examples that serve as test, documentation seed, and godoc content.

Co-Authored-By: Virgil <virgil@lethean.io>

action_example_test.go

@@ -0,0 +1,60 @@
+package core_test
+
+import (
+	"context"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleAction_Run() {
+	c := New()
+	c.Action("double", func(_ context.Context, opts Options) Result {
+		return Result{Value: opts.Int("n") * 2, OK: true}
+	})
+
+	r := c.Action("double").Run(context.Background(), NewOptions(
+		Option{Key: "n", Value: 21},
+	))
+	fmt.Println(r.Value)
+	// Output: 42
+}
+
+func ExampleAction_Exists() {
+	c := New()
+	fmt.Println(c.Action("missing").Exists())
+
+	c.Action("present", func(_ context.Context, _ Options) Result { return Result{OK: true} })
+	fmt.Println(c.Action("present").Exists())
+	// Output:
+	// false
+	// true
+}
+
+func ExampleAction_Run_panicRecovery() {
+	c := New()
+	c.Action("boom", func(_ context.Context, _ Options) Result {
+		panic("explosion")
+	})
+
+	r := c.Action("boom").Run(context.Background(), NewOptions())
+	fmt.Println(r.OK)
+	// Output: false
+}
+
+func ExampleAction_Run_entitlementDenied() {
+	c := New()
+	c.Action("premium", func(_ context.Context, _ Options) Result {
+		return Result{Value: "secret", OK: true}
+	})
+	c.SetEntitlementChecker(func(action string, _ int, _ context.Context) Entitlement {
+		if action == "premium" {
+			return Entitlement{Allowed: false, Reason: "upgrade"}
+		}
+		return Entitlement{Allowed: true, Unlimited: true}
+	})
+
+	r := c.Action("premium").Run(context.Background(), NewOptions())
+	fmt.Println(r.OK)
+	// Output: false
+}

api_example_test.go

@@ -0,0 +1,50 @@
+package core_test
+
+import (
+	"context"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleAPI_RegisterProtocol() {
+	c := New()
+	c.API().RegisterProtocol("http", func(h *DriveHandle) (Stream, error) {
+		return &mockStream{response: []byte("pong")}, nil
+	})
+	fmt.Println(c.API().Protocols())
+	// Output: [http]
+}
+
+func ExampleAPI_Stream() {
+	c := New()
+	c.API().RegisterProtocol("http", func(h *DriveHandle) (Stream, error) {
+		return &mockStream{response: []byte("connected to " + h.Name)}, nil
+	})
+	c.Drive().New(NewOptions(
+		Option{Key: "name", Value: "charon"},
+		Option{Key: "transport", Value: "http://10.69.69.165:9101"},
+	))
+
+	r := c.API().Stream("charon")
+	if r.OK {
+		stream := r.Value.(Stream)
+		resp, _ := stream.Receive()
+		fmt.Println(string(resp))
+		stream.Close()
+	}
+	// Output: connected to charon
+}
+
+func ExampleCore_RemoteAction() {
+	c := New()
+	// Local action
+	c.Action("status", func(_ context.Context, _ Options) Result {
+		return Result{Value: "running", OK: true}
+	})
+
+	// No colon — resolves locally
+	r := c.RemoteAction("status", context.Background(), NewOptions())
+	fmt.Println(r.Value)
+	// Output: running
+}

array_example_test.go

@@ -0,0 +1,42 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleNewArray() {
+	a := NewArray[string]()
+	a.Add("alpha")
+	a.Add("bravo")
+	a.Add("charlie")
+
+	fmt.Println(a.Len())
+	fmt.Println(a.Contains("bravo"))
+	// Output:
+	// 3
+	// true
+}
+
+func ExampleArray_AddUnique() {
+	a := NewArray[string]()
+	a.AddUnique("alpha")
+	a.AddUnique("alpha") // no duplicate
+	a.AddUnique("bravo")
+
+	fmt.Println(a.Len())
+	// Output: 2
+}
+
+func ExampleArray_Filter() {
+	a := NewArray[int]()
+	a.Add(1)
+	a.Add(2)
+	a.Add(3)
+	a.Add(4)
+
+	r := a.Filter(func(n int) bool { return n%2 == 0 })
+	fmt.Println(r.OK)
+	// Output: true
+}

error_example_test.go

@@ -0,0 +1,35 @@
+package core_test
+
+import (
+	"errors"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleE() {
+	err := E("cache.Get", "key not found", nil)
+	fmt.Println(Operation(err))
+	fmt.Println(ErrorMessage(err))
+	// Output:
+	// cache.Get
+	// key not found
+}
+
+func ExampleWrap() {
+	cause := errors.New("connection refused")
+	err := Wrap(cause, "database.Connect", "failed to reach host")
+	fmt.Println(Operation(err))
+	fmt.Println(errors.Is(err, cause))
+	// Output:
+	// database.Connect
+	// true
+}
+
+func ExampleRoot() {
+	cause := errors.New("original")
+	wrapped := Wrap(cause, "op1", "first wrap")
+	double := Wrap(wrapped, "op2", "second wrap")
+	fmt.Println(Root(double))
+	// Output: original
+}

example_test.go

@@ -312,13 +312,4 @@ func ExampleConfig() {
 	// true
 }
 
-// --- Error ---
-
-func ExampleE() {
-	err := E("service.Start", "database connection failed", nil)
-	fmt.Println(Operation(err))
-	fmt.Println(ErrorMessage(err))
-	// Output:
-	// service.Start
-	// database connection failed
-}
+// Error examples in error_example_test.go

fs_example_test.go

@@ -0,0 +1,44 @@
+package core_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleFs_WriteAtomic() {
+	dir, _ := os.MkdirTemp("", "example")
+	defer os.RemoveAll(dir)
+
+	f := (&Fs{}).New("/")
+	path := filepath.Join(dir, "status.json")
+	f.WriteAtomic(path, `{"status":"completed"}`)
+
+	r := f.Read(path)
+	fmt.Println(r.Value)
+	// Output: {"status":"completed"}
+}
+
+func ExampleFs_NewUnrestricted() {
+	dir, _ := os.MkdirTemp("", "example")
+	defer os.RemoveAll(dir)
+
+	// Write outside sandbox
+	outside := filepath.Join(dir, "outside.txt")
+	os.WriteFile(outside, []byte("hello"), 0644)
+
+	sandbox := (&Fs{}).New(filepath.Join(dir, "sandbox"))
+	unrestricted := sandbox.NewUnrestricted()
+
+	r := unrestricted.Read(outside)
+	fmt.Println(r.Value)
+	// Output: hello
+}
+
+func ExampleFs_Root() {
+	f := (&Fs{}).New("/srv/workspaces")
+	fmt.Println(f.Root())
+	// Output: /srv/workspaces
+}

path_example_test.go

@@ -0,0 +1,28 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleJoinPath() {
+	fmt.Println(JoinPath("deploy", "to", "homelab"))
+	// Output: deploy/to/homelab
+}
+
+func ExamplePathBase() {
+	fmt.Println(PathBase("/srv/workspaces/alpha"))
+	// Output: alpha
+}
+
+func ExamplePathDir() {
+	fmt.Println(PathDir("/srv/workspaces/alpha"))
+	// Output: /srv/workspaces
+}
+
+func ExamplePathExt() {
+	fmt.Println(PathExt("report.pdf"))
+	// Output: .pdf
+}
+

registry_example_test.go

@@ -0,0 +1,71 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleRegistry_Set() {
+	r := NewRegistry[string]()
+	r.Set("alpha", "first")
+	r.Set("bravo", "second")
+	fmt.Println(r.Get("alpha").Value)
+	// Output: first
+}
+
+func ExampleRegistry_Names() {
+	r := NewRegistry[int]()
+	r.Set("charlie", 3)
+	r.Set("alpha", 1)
+	r.Set("bravo", 2)
+	fmt.Println(r.Names())
+	// Output: [charlie alpha bravo]
+}
+
+func ExampleRegistry_List() {
+	r := NewRegistry[string]()
+	r.Set("process.run", "run")
+	r.Set("process.kill", "kill")
+	r.Set("brain.recall", "recall")
+
+	items := r.List("process.*")
+	fmt.Println(len(items))
+	// Output: 2
+}
+
+func ExampleRegistry_Each() {
+	r := NewRegistry[int]()
+	r.Set("a", 1)
+	r.Set("b", 2)
+	r.Set("c", 3)
+
+	sum := 0
+	r.Each(func(_ string, v int) { sum += v })
+	fmt.Println(sum)
+	// Output: 6
+}
+
+func ExampleRegistry_Disable() {
+	r := NewRegistry[string]()
+	r.Set("alpha", "first")
+	r.Set("bravo", "second")
+	r.Disable("alpha")
+
+	var names []string
+	r.Each(func(name string, _ string) { names = append(names, name) })
+	fmt.Println(names)
+	// Output: [bravo]
+}
+
+func ExampleRegistry_Delete() {
+	r := NewRegistry[string]()
+	r.Set("temp", "value")
+	fmt.Println(r.Has("temp"))
+
+	r.Delete("temp")
+	fmt.Println(r.Has("temp"))
+	// Output:
+	// true
+	// false
+}

service_example_test.go

@@ -0,0 +1,51 @@
+package core_test
+
+import (
+	"context"
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleServiceFor() {
+	c := New(
+		WithService(func(c *Core) Result {
+			return c.Service("cache", Service{
+				OnStart: func() Result { return Result{OK: true} },
+			})
+		}),
+	)
+
+	svc := c.Service("cache")
+	fmt.Println(svc.OK)
+	// Output: true
+}
+
+func ExampleWithService() {
+	started := false
+	c := New(
+		WithService(func(c *Core) Result {
+			return c.Service("worker", Service{
+				OnStart: func() Result { started = true; return Result{OK: true} },
+			})
+		}),
+	)
+	c.ServiceStartup(context.Background(), nil)
+	fmt.Println(started)
+	c.ServiceShutdown(context.Background())
+	// Output: true
+}
+
+func ExampleWithServiceLock() {
+	c := New(
+		WithService(func(c *Core) Result {
+			return c.Service("allowed", Service{})
+		}),
+		WithServiceLock(),
+	)
+
+	// Can't register after lock
+	r := c.Service("blocked", Service{})
+	fmt.Println(r.OK)
+	// Output: false
+}

string_example_test.go

@@ -0,0 +1,36 @@
+package core_test
+
+import (
+	"fmt"
+
+	. "dappco.re/go/core"
+)
+
+func ExampleContains() {
+	fmt.Println(Contains("hello world", "world"))
+	fmt.Println(Contains("hello world", "mars"))
+	// Output:
+	// true
+	// false
+}
+
+func ExampleSplit() {
+	parts := Split("deploy/to/homelab", "/")
+	fmt.Println(parts)
+	// Output: [deploy to homelab]
+}
+
+func ExampleJoin() {
+	fmt.Println(Join("/", "deploy", "to", "homelab"))
+	// Output: deploy/to/homelab
+}
+
+func ExampleConcat() {
+	fmt.Println(Concat("hello", " ", "world"))
+	// Output: hello world
+}
+
+func ExampleTrim() {
+	fmt.Println(Trim("  spaced  "))
+	// Output: spaced
+}