# corestack go

Shared Go building blocks. The first one is `docs`, a checker for architecture decision records (ADRs) and implementation plans.

## 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.

## 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.

## 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).