# corestack go

Shared Go building blocks. Includes `docs`, a checker for architecture decision records (ADRs) and implementation plans, and `lifecycle`, a service and worker coordinator.

## docs

Install:

```sh
go install go.auvem.com/corestack/cmd/docs@latest
```

Use, from a repository root:

```sh
docs new adr "Use Example Queue for background jobs"   # creates docs/adr/<id>.md
docs new plan "Adopt Example Queue"                    # creates docs/plans/<id>.md
docs check [--root DIR]                                # prints path:line: message; exit 1 on problems
```

The format is specified in [docs/docs-format.md](docs/docs-format.md); that document is the complete rule set. Exit status is `0` when every record is valid, `1` when problems are reported and `2` for usage errors.

## lifecycle

`go.auvem.com/corestack/lifecycle` sets up modules in registration order, runs
services concurrently, and tears down successful setups in reverse order.
Construct an `App` with a required `*slog.Logger`, register `Module` callbacks,
and call `Run(ctx)` once. See the [two-service example](lifecycle/example_test.go).

Launch background work with `app.Go(ctx, name, fn)` using the callback's lifecycle
context or a descendant, and handle admission errors. Run waits for every service
and admitted worker; raw goroutines remain your responsibility. First failure or
an injected signal cancels work before teardown. One shared shutdown deadline
(default 30 seconds) covers hooks and callback completion; a second signal
abandons shutdown. Callbacks must cooperate: abandonment cannot kill goroutines,
and the caller owns process exit and any unreleased resources.

During App-initiated shutdown, callback errors containing only the callback's
context cancellation are omitted. Mixed cancellation and independent failures
are retained intact to preserve wrapper types, identity and custom matching;
these errors may still match cancellation through `errors.Is`.

The caller owns signal subscription, SIGINT/SIGTERM filtering, a channel buffered
for at least two signals, and subscription cleanup. Nil signals disable reception.
There are no signal subscriptions, process exits, external dependencies or CLI
integration in this package.

## Status

No support is guaranteed. Breaking changes, including to the format rules, may happen before 1.0 and are listed in the release notes.

## License

BSD-3-Clause, see [LICENSE](LICENSE).