Merge main into feat/migrate

README.md

@@ -1,6 +1,6 @@
 # corestack go
 
-Shared Go building blocks. The first one is `docs`, a checker for architecture decision records (ADRs) and implementation plans.
+Shared Go building blocks. Includes `docs`, a checker for architecture decision records (ADRs) and implementation plans; `page`, Bob keyset pagination; and `lifecycle`, a service and worker coordinator.
 
 ## migrate
 
@@ -25,6 +25,44 @@ docs check [--root DIR]                                # prints path:line: messa
 
 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.
 
+## page
+
+[`page`](page/page.go) provides transport-neutral Bob keyset pagination with typed
+items, mixed-direction sorts, opaque typed cursors, and a separate opt-in count.
+Pass a trusted Sort and a typed row key in the same column order; sort columns
+must be non-null and end in a unique column. See the [runnable example](page/example_test.go)
+and [cursor decision](docs/adr/20261027T184351001Z-preserve-typed-sort-values-in-versioned-page-cursors.md).
+
+SQLite runs in-process in the normal test suite (requires CGO). PostgreSQL runs in
+CI; locally set `PAGE_POSTGRES_DSN` to an isolated test database to run the same
+flow. Set `PAGE_REQUIRE_POSTGRES=1` to fail rather than skip when the DSN is absent.
+MySQL mod composition compiles; its runtime behavior has not been verified.
+
+## 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.