feat: core/go v0.8.0 — full AX migration

CLAUDE.md

@@ -4,16 +4,15 @@ Guidance for Claude Code and Codex when working with this repository.
 
 ## Module
 
-`dappco.re/go/core` — dependency injection, service lifecycle, command routing, and message-passing for Go.
+`dappco.re/go/core` — dependency injection, service lifecycle, permission, and message-passing for Go.
 
-Source files live at the module root (not `pkg/core/`). Tests live in `tests/`.
+Source files and tests live at the module root. No `pkg/` nesting.
 
 ## Build & Test
 
 ```bash
-go test ./tests/...          # run all tests
-go build .                   # verify compilation
-GOWORK=off go test ./tests/  # test without workspace
+go test ./... -count=1       # run all tests (483 tests, 84.7% coverage)
+go build ./...               # verify compilation
 ```
 
 Or via the Core CLI:
@@ -25,55 +24,61 @@ core go qa                   # fmt + vet + lint + test
 
 ## API Shape
 
-CoreGO uses the DTO/Options/Result pattern, not functional options:
-
 ```go
-c := core.New(core.Options{
-    {Key: "name", Value: "myapp"},
-})
-
-c.Service("cache", core.Service{
-    OnStart: func() core.Result { return core.Result{OK: true} },
-    OnStop:  func() core.Result { return core.Result{OK: true} },
-})
-
-c.Command("deploy/to/homelab", core.Command{
-    Action: func(opts core.Options) core.Result {
-        return core.Result{Value: "deployed", OK: true}
-    },
-})
-
-r := c.Cli().Run("deploy", "to", "homelab")
+c := core.New(
+    core.WithOption("name", "myapp"),
+    core.WithService(mypackage.Register),
+    core.WithServiceLock(),
+)
+c.Run()    // or: if err := c.RunE(); err != nil { ... }
 ```
 
-**Do not use:** `WithService`, `WithName`, `WithApp`, `WithServiceLock`, `Must*`, `ServiceFor[T]` — these no longer exist.
+Service factory:
+
+```go
+func Register(c *core.Core) core.Result {
+    svc := &MyService{ServiceRuntime: core.NewServiceRuntime(c, MyOpts{})}
+    return core.Result{Value: svc, OK: true}
+}
+```
 
 ## Subsystems
 
 | Accessor | Returns | Purpose |
 |----------|---------|---------|
 | `c.Options()` | `*Options` | Input configuration |
 | `c.App()` | `*App` | Application identity |
-| `c.Data()` | `*Data` | Embedded filesystem mounts |
-| `c.Drive()` | `*Drive` | Named transport handles |
-| `c.Fs()` | `*Fs` | Local filesystem I/O |
-| `c.Config()` | `*Config` | Runtime settings |
-| `c.Cli()` | `*Cli` | CLI surface |
-| `c.Command("path")` | `Result` | Command tree |
-| `c.Service("name")` | `Result` | Service registry |
-| `c.Lock("name")` | `*Lock` | Named mutexes |
-| `c.IPC()` | `*Ipc` | Message bus |
-| `c.I18n()` | `*I18n` | Locale + translation |
+| `c.Config()` | `*Config` | Runtime settings, feature flags |
+| `c.Data()` | `*Data` | Embedded assets (Registry[*Embed]) |
+| `c.Drive()` | `*Drive` | Transport handles (Registry[*DriveHandle]) |
+| `c.Fs()` | `*Fs` | Filesystem I/O (sandboxable) |
+| `c.Cli()` | `*Cli` | CLI command framework |
+| `c.IPC()` | `*Ipc` | Message bus internals |
+| `c.Process()` | `*Process` | Managed execution (Action sugar) |
+| `c.API()` | `*API` | Remote streams (protocol handlers) |
+| `c.Action(name)` | `*Action` | Named callable (register/invoke) |
+| `c.Task(name)` | `*Task` | Composed Action sequence |
+| `c.Entitled(name)` | `Entitlement` | Permission check |
+| `c.RegistryOf(n)` | `*Registry` | Cross-cutting queries |
+| `c.I18n()` | `*I18n` | Internationalisation |
 
 ## Messaging
 
 | Method | Pattern |
 |--------|---------|
-| `c.ACTION(msg)` | Broadcast to all handlers |
+| `c.ACTION(msg)` | Broadcast to all handlers (panic recovery per handler) |
 | `c.QUERY(q)` | First responder wins |
 | `c.QUERYALL(q)` | Collect all responses |
-| `c.PERFORM(task)` | First executor wins |
-| `c.PerformAsync(task)` | Background goroutine |
+| `c.PerformAsync(action, opts)` | Background goroutine with progress |
+
+## Lifecycle
+
+```go
+type Startable interface { OnStartup(ctx context.Context) Result }
+type Stoppable interface { OnShutdown(ctx context.Context) Result }
+```
+
+`RunE()` always calls `defer ServiceShutdown` — even on startup failure or panic.
 
 ## Error Handling
 
@@ -83,13 +88,15 @@ Use `core.E()` for structured errors:
 return core.E("service.Method", "what failed", underlyingErr)
 ```
 
-## Test Naming
+**Never** use `fmt.Errorf`, `errors.New`, `os/exec`, or `unsafe.Pointer` on Core types.
+
+## Test Naming (AX-7)
 
-`_Good` (happy path), `_Bad` (expected errors), `_Ugly` (panics/edge cases).
+`TestFile_Function_{Good,Bad,Ugly}` — 100% compliance.
 
 ## Docs
 
-Full documentation in `docs/`. Start with `docs/getting-started.md`.
+Full API contract: `docs/RFC.md` (1476 lines, 21 sections).
 
 ## Go Workspace
 

README.md

@@ -1,8 +1,6 @@
 # CoreGO
 
-Dependency injection, service lifecycle, command routing, and message-passing for Go.
-
-Import path:
+Dependency injection, service lifecycle, permission, and message-passing for Go.
 
 ```go
 import "dappco.re/go/core"
@@ -14,75 +12,24 @@ CoreGO is the foundation layer for the Core ecosystem. It gives you:
 - one input shape: `Options`
 - one output shape: `Result`
 - one command tree: `Command`
-- one message bus: `ACTION`, `QUERY`, `PERFORM`
-
-## Why It Exists
-
-Most non-trivial Go systems end up needing the same small set of infrastructure:
-
-- a place to keep runtime state and shared subsystems
-- a predictable way to start and stop managed components
-- a clean command surface for CLI-style workflows
-- decoupled communication between components without tight imports
-
-CoreGO keeps those pieces small and explicit.
+- one message bus: `ACTION`, `QUERY` + named `Action` callables
+- one permission gate: `Entitled`
+- one collection primitive: `Registry[T]`
 
 ## Quick Example
 
 ```go
 package main
 
-import (
-	"context"
-	"fmt"
-
-	"dappco.re/go/core"
-)
-
-type flushCacheTask struct {
-	Name string
-}
+import "dappco.re/go/core"
 
 func main() {
-	c := core.New(core.Options{
-		{Key: "name", Value: "agent-workbench"},
-	})
-
-	c.Service("cache", core.Service{
-		OnStart: func() core.Result {
-			core.Info("cache started", "app", c.App().Name)
-			return core.Result{OK: true}
-		},
-		OnStop: func() core.Result {
-			core.Info("cache stopped", "app", c.App().Name)
-			return core.Result{OK: true}
-		},
-	})
-
-	c.RegisterTask(func(_ *core.Core, task core.Task) core.Result {
-		switch t := task.(type) {
-		case flushCacheTask:
-			return core.Result{Value: "cache flushed for " + t.Name, OK: true}
-		}
-		return core.Result{}
-	})
-
-	c.Command("cache/flush", core.Command{
-		Action: func(opts core.Options) core.Result {
-			return c.PERFORM(flushCacheTask{
-				Name: opts.String("name"),
-			})
-		},
-	})
-
-	if !c.ServiceStartup(context.Background(), nil).OK {
-		panic("startup failed")
-	}
-
-	r := c.Cli().Run("cache", "flush", "--name=session-store")
-	fmt.Println(r.Value)
-
-	_ = c.ServiceShutdown(context.Background())
+    c := core.New(
+        core.WithOption("name", "agent-workbench"),
+        core.WithService(cache.Register),
+        core.WithServiceLock(),
+    )
+    c.Run()
 }
 ```
 
@@ -93,22 +40,16 @@ func main() {
 | `Core` | Central container and access point |
 | `Service` | Managed lifecycle component |
 | `Command` | Path-based executable operation |
-| `Cli` | CLI surface over the command tree |
+| `Action` | Named callable with panic recovery + entitlement |
+| `Task` | Composed sequence of Actions |
+| `Registry[T]` | Thread-safe named collection |
+| `Process` | Managed execution (Action sugar) |
+| `API` | Remote streams (protocol handlers) |
+| `Entitlement` | Permission check result |
 | `Data` | Embedded filesystem mounts |
 | `Drive` | Named transport handles |
-| `Fs` | Local filesystem operations |
+| `Fs` | Local filesystem (sandboxable) |
 | `Config` | Runtime settings and feature flags |
-| `I18n` | Locale collection and translation delegation |
-| `E`, `Wrap`, `ErrorLog`, `ErrorPanic` | Structured failures and panic recovery |
-
-## AX-Friendly Model
-
-CoreGO follows the same design direction as the AX spec:
-
-- predictable names over compressed names
-- paths as documentation, such as `deploy/to/homelab`
-- one repeated vocabulary across the framework
-- examples that show how to call real APIs
 
 ## Install
 
@@ -121,30 +62,12 @@ Requires Go 1.26 or later.
 ## Test
 
 ```bash
-core go test
-```
-
-Or with the standard toolchain:
-
-```bash
-go test ./...
+go test ./...    # 483 tests, 84.7% coverage
 ```
 
 ## Docs
 
-The full documentation set lives in `docs/`.
-
-| Path | Covers |
-|------|--------|
-| `docs/getting-started.md` | First runnable CoreGO app |
-| `docs/primitives.md` | `Options`, `Result`, `Service`, `Message`, `Query`, `Task` |
-| `docs/services.md` | Service registry, runtime helpers, service locks |
-| `docs/commands.md` | Path-based commands and CLI execution |
-| `docs/messaging.md` | `ACTION`, `QUERY`, `QUERYALL`, `PERFORM`, `PerformAsync` |
-| `docs/lifecycle.md` | Startup, shutdown, context, and task draining |
-| `docs/subsystems.md` | `App`, `Data`, `Drive`, `Fs`, `I18n`, `Cli` |
-| `docs/errors.md` | Structured errors, logging helpers, panic recovery |
-| `docs/testing.md` | Test naming and framework testing patterns |
+The authoritative API contract is `docs/RFC.md` (21 sections).
 
 ## License