feat: graceful shutdown core implementation (#195)

## Type

<!-- Check ALL that apply -->
- [x] `feat` — New feature
- [ ] `fix` — Bug fix
- [ ] `refactor` — Code restructure (no behavior change)
- [ ] `docs` — Documentation only
- [x] `test` — Test coverage
- [ ] `chore` — Build, CI, tooling
- [ ] `perf` — Performance improvement

## Summary

Implements core graceful shutdown support by tracking provider build
order, detecting `io.Closer` providers, adding `App.Close()` (reverse
order), and adding unit tests (including error behavior).

## Changes

- Record provider build order and `io.Closer` build order in container
- Add `App.Close()` and keep `App.Closers()` compatibility
- Add close ordering tests including dependency-driven order and error
continuation

## Breaking Changes

None

## Validation

```bash
make fmt && make lint && make test
```

## Checklist

- [x] Code follows project style (`make fmt` passes)
- [x] Linter passes (`make lint`)
- [x] Tests pass (`make test`)
- [x] Tests added/updated for new functionality
- [x] Documentation updated (if applicable)
- [x] Commit messages follow [Conventional
Commits](https://www.conventionalcommits.org/)

## Resolves

Resolves #137
Resolves #143
Resolves #144
Resolves #145

## Notes

N/A


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Implemented graceful shutdown support; registered resources are closed
in reverse initialization (LIFO) order.
* Shutdown captures and returns the first error encountered while
continuing to close remaining resources.
* **Tests**
* Added unit tests verifying closer registration order, reverse-close
sequencing, dependency-aware shutdown, and error-handling during close.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: aryeko

modkit/kernel/bootstrap.go

@@ -2,6 +2,7 @@ package kernel
 
 import (
 	"context"
+	"io"
 
 	"github.com/go-modkit/modkit/modkit/module"
 )
@@ -73,3 +74,19 @@ func (a *App) Get(token module.Token) (any, error) {
 func (a *App) CleanupHooks() []func(context.Context) error {
 	return a.container.cleanupHooksLIFO()
 }
+
+// Closers returns provider closers in build order.
+func (a *App) Closers() []io.Closer {
+	return a.container.closersInBuildOrder()
+}
+
+// Close calls Close on all io.Closer providers in reverse build order.
+func (a *App) Close() error {
+	var firstErr error
+	for _, closer := range a.container.closersLIFO() {
+		if err := closer.Close(); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
+}

modkit/kernel/container.go

@@ -2,6 +2,7 @@ package kernel
 
 import (
 	"context"
+	"io"
 	"sync"
 
 	"github.com/go-modkit/modkit/modkit/module"
@@ -20,6 +21,8 @@ type Container struct {
 	locks        map[module.Token]*sync.Mutex
 	waitingOn    map[module.Token]module.Token
 	cleanupHooks []func(context.Context) error
+	closers      []io.Closer
+	buildOrder   []module.Token
 	mu           sync.Mutex
 }
 
@@ -48,6 +51,8 @@ func newContainer(graph *Graph, visibility Visibility) (*Container, error) {
 		locks:        make(map[module.Token]*sync.Mutex),
 		waitingOn:    make(map[module.Token]module.Token),
 		cleanupHooks: make([]func(context.Context) error, 0),
+		closers:      make([]io.Closer, 0),
+		buildOrder:   make([]module.Token, 0),
 	}, nil
 }
 
@@ -110,6 +115,10 @@ func (c *Container) getWithStack(token module.Token, requester string, stack []m
 	if entry.cleanup != nil {
 		c.cleanupHooks = append(c.cleanupHooks, entry.cleanup)
 	}
+	if closer, ok := instance.(io.Closer); ok {
+		c.closers = append(c.closers, closer)
+	}
+	c.buildOrder = append(c.buildOrder, token)
 	c.mu.Unlock()
 	return instance, nil
 }
@@ -125,6 +134,35 @@ func (c *Container) cleanupHooksLIFO() []func(context.Context) error {
 	return hooks
 }
 
+func (c *Container) closersLIFO() []io.Closer {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	closers := make([]io.Closer, len(c.closers))
+	for i, closer := range c.closers {
+		closers[len(c.closers)-1-i] = closer
+	}
+	return closers
+}
+
+func (c *Container) closersInBuildOrder() []io.Closer {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	closers := make([]io.Closer, len(c.closers))
+	copy(closers, c.closers)
+	return closers
+}
+
+func (c *Container) providerBuildOrder() []module.Token {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	order := make([]module.Token, len(c.buildOrder))
+	copy(order, c.buildOrder)
+	return order
+}
+
 type moduleResolver struct {
 	container    *Container
 	moduleName   string

modkit/kernel/container_internal_test.go

@@ -0,0 +1,132 @@
+package kernel
+
+import (
+	"testing"
+
+	"github.com/go-modkit/modkit/modkit/module"
+)
+
+type modHelperInternal struct {
+	def module.ModuleDef
+}
+
+func (m *modHelperInternal) Definition() module.ModuleDef {
+	return m.def
+}
+
+func modInternal(
+	name string,
+	imports []module.Module,
+	providers []module.ProviderDef,
+	controllers []module.ControllerDef,
+	exports []module.Token,
+) module.Module {
+	return &modHelperInternal{
+		def: module.ModuleDef{
+			Name:        name,
+			Imports:     imports,
+			Providers:   providers,
+			Controllers: controllers,
+			Exports:     exports,
+		},
+	}
+}
+
+func TestContainerRecordsProviderBuildOrder(t *testing.T) {
+	first := module.Token("provider.first")
+	second := module.Token("provider.second")
+
+	modA := modInternal("A", nil,
+		[]module.ProviderDef{{
+			Token: first,
+			Build: func(r module.Resolver) (any, error) {
+				return "first", nil
+			},
+		}, {
+			Token: second,
+			Build: func(r module.Resolver) (any, error) {
+				return "second", nil
+			},
+		}},
+		nil,
+		nil,
+	)
+
+	app, err := Bootstrap(modA)
+	if err != nil {
+		t.Fatalf("Bootstrap failed: %v", err)
+	}
+
+	if _, err := app.Get(second); err != nil {
+		t.Fatalf("Get second failed: %v", err)
+	}
+	if _, err := app.Get(first); err != nil {
+		t.Fatalf("Get first failed: %v", err)
+	}
+
+	order := app.container.providerBuildOrder()
+	if len(order) != 2 {
+		t.Fatalf("expected 2 providers, got %d", len(order))
+	}
+	if order[0] != second || order[1] != first {
+		t.Fatalf("unexpected order: %v", order)
+	}
+}
+
+func TestContainerRecordsClosersInBuildOrder(t *testing.T) {
+	closerA := module.Token("closer.a")
+	closerB := module.Token("closer.b")
+
+	modA := modInternal("A", nil,
+		[]module.ProviderDef{{
+			Token: closerA,
+			Build: func(r module.Resolver) (any, error) {
+				return &testCloser{name: "a"}, nil
+			},
+		}, {
+			Token: closerB,
+			Build: func(r module.Resolver) (any, error) {
+				return &testCloser{name: "b"}, nil
+			},
+		}},
+		nil,
+		nil,
+	)
+
+	app, err := Bootstrap(modA)
+	if err != nil {
+		t.Fatalf("Bootstrap failed: %v", err)
+	}
+
+	_, _ = app.Get(closerA)
+	_, _ = app.Get(closerB)
+
+	closers := app.container.closersInBuildOrder()
+	if len(closers) != 2 {
+		t.Fatalf("expected 2 closers, got %d", len(closers))
+	}
+
+	first, ok := closers[0].(*testCloser)
+	if !ok {
+		t.Fatalf("expected *testCloser, got %T", closers[0])
+	}
+	second, ok := closers[1].(*testCloser)
+	if !ok {
+		t.Fatalf("expected *testCloser, got %T", closers[1])
+	}
+	if first.Name() != "a" || second.Name() != "b" {
+		t.Fatalf("unexpected order: %v", closers)
+	}
+}
+
+type testCloser struct {
+	name string
+}
+
+func (c *testCloser) Close() error {
+	return nil
+}
+
+func (c *testCloser) Name() string {
+	return c.name
+}