@opengroundplan/core 0.1.1

package/templates/layers/ci-github-actions/files/.github/workflows/ci-node.yml

@@ -0,0 +1,111 @@
+name: CI
+
+on:
+  push:
+    branches: [{{ ciDefaultBranch }}]
+  pull_request:
+    branches: [{{ ciDefaultBranch }}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# A newer commit on the same pull request makes the in-flight run obsolete.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# The only place commands and script names are written. Jobs read from here.
+env:
+  PACKAGE_MANAGER: {{ packageManager }}
+  INSTALL_COMMAND: {{ packageManager }} install
+  # Candidate package.json scripts, first match wins; none present skips the step.
+  BUILD_SCRIPTS: build
+  TEST_SCRIPTS: test
+  LINT_SCRIPTS: lint
+  TYPECHECK_SCRIPTS: typecheck check-types
+
+# Windows runners default to pwsh; the steps below are POSIX shell.
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/node-setup
+        with:
+          node-version: '{{ ciNodeVersion }}'
+          package-manager: ${{ env.PACKAGE_MANAGER }}
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - run: bash .github/scripts/run-package-script.sh $LINT_SCRIPTS
+
+  typecheck:
+    name: Typecheck
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/node-setup
+        with:
+          node-version: '{{ ciNodeVersion }}'
+          package-manager: ${{ env.PACKAGE_MANAGER }}
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - run: bash .github/scripts/run-package-script.sh $TYPECHECK_SCRIPTS
+
+  build:
+    name: Build (node ${{ matrix.node }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      # One red cell should not hide the state of the others.
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+        node: {{ ciNodeVersions }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/node-setup
+        with:
+          node-version: ${{ matrix.node }}
+          package-manager: ${{ env.PACKAGE_MANAGER }}
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - run: bash .github/scripts/run-package-script.sh $BUILD_SCRIPTS
+
+  test:
+    name: Test (node ${{ matrix.node }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+        node: {{ ciNodeVersions }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/node-setup
+        with:
+          node-version: ${{ matrix.node }}
+          package-manager: ${{ env.PACKAGE_MANAGER }}
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - run: bash .github/scripts/run-package-script.sh $TEST_SCRIPTS
+
+  # The one check to mark required in branch protection: matrix cells come and go
+  # as the version list changes, but this job's name never does.
+  gate:
+    name: CI gate
+    if: always()
+    needs: [lint, typecheck, build, test]
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - name: Verify every required job succeeded
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}; then
+            echo "::error::a required job did not succeed"
+            exit 1
+          fi

package/templates/layers/ci-github-actions/files/.github/workflows/ci-python.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [{{ ciDefaultBranch }}]
+  pull_request:
+    branches: [{{ ciDefaultBranch }}]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+# The only place commands and paths are written. Jobs read from here.
+env:
+  INSTALL_COMMAND: uv sync --all-extras --dev
+  LINT_COMMAND: uv run ruff check --output-format=github .
+  FORMAT_CHECK_COMMAND: uv run ruff format --check .
+  # --explicit-package-bases + MYPYPATH resolve relative imports under a src/ layout
+  # that has no __init__.py, which is how the Python bases are laid out.
+  TYPECHECK_COMMAND: uv run --with mypy mypy --ignore-missing-imports --explicit-package-bases --namespace-packages src
+  MYPYPATH: src
+  BUILD_COMMAND: uv build
+  TEST_COMMAND: uv run --with pytest pytest -q
+  SOURCE_DIR: src
+  TEST_DIR: tests
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/python-setup
+        with:
+          python-version: '{{ ciPythonVersion }}'
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - name: Ruff lint
+        run: $LINT_COMMAND
+      - name: Ruff format check
+        run: $FORMAT_CHECK_COMMAND
+
+  typecheck:
+    name: Typecheck
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/python-setup
+        with:
+          python-version: '{{ ciPythonVersion }}'
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - name: Mypy
+        run: |
+          if [ ! -d "$SOURCE_DIR" ]; then
+            echo "::notice::no $SOURCE_DIR directory — skipped"
+            exit 0
+          fi
+          $TYPECHECK_COMMAND
+
+  build:
+    name: Build
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/python-setup
+        with:
+          python-version: '{{ ciPythonVersion }}'
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - name: Build the distribution
+        run: $BUILD_COMMAND
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  test:
+    name: Test (python ${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    strategy:
+      # One red cell should not hide the state of the others.
+      fail-fast: false
+      matrix:
+        os: {{ ciMatrixOs }}
+        python: {{ ciPythonVersions }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ matrix.python }}
+          install-command: ${{ env.INSTALL_COMMAND }}
+      - name: Pytest
+        run: |
+          if [ ! -d "$TEST_DIR" ]; then
+            echo "::notice::no $TEST_DIR directory — skipped"
+            exit 0
+          fi
+          $TEST_COMMAND
+
+  # The one check to mark required in branch protection: matrix cells come and go
+  # as the version list changes, but this job's name never does.
+  gate:
+    name: CI gate
+    if: always()
+    needs: [lint, typecheck, build, test]
+    runs-on: {{ ciRunner }}
+    timeout-minutes: {{ ciTimeoutMinutes }}
+    steps:
+      - name: Verify every required job succeeded
+        run: |
+          if ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped') }}; then
+            echo "::error::a required job did not succeed"
+            exit 1
+          fi

package/templates/layers/ci-github-actions/files/docs/ci-github-actions.md

@@ -0,0 +1,106 @@
+# CI — GitHub Actions
+
+One workflow, `.github/workflows/ci-*.yml`, runs on every push to `{{ ciDefaultBranch }}`
+and on every pull request targeting it. It is also available from the Actions tab
+(`workflow_dispatch`).
+
+## Jobs
+
+| Job | What it does |
+|---|---|
+| `Lint` | style and static analysis, single runner |
+| `Typecheck` | type checking, single runner (Node and Python only — see below) |
+| `Build` | compiles/packages the project, across the matrix |
+| `Test` | runs the test suite, across the matrix |
+| `CI gate` | fails unless every job above succeeded |
+
+.NET and Go have no separate `Typecheck` job on purpose. The .NET build treats warnings
+as errors and enforces code style (`Directory.Build.props`), and the Go compiler is the
+type checker — in both cases `Build` already is the type gate, and a second job running
+the same compiler would only cost minutes.
+
+`Test` is green before you write any tests: the Node runner skips a missing `test`
+script, Python skips a missing `tests/` directory, `dotnet test` exits 0 with no test
+project, and `go test` exits 0 with no `_test.go` files.
+
+## Where the configuration lives
+
+Every command the workflow runs is defined once, in the `env:` block at the top of the
+workflow file, and referenced from the steps as a shell variable. Change a command
+there and every job picks it up. Nothing is inlined in a step.
+
+Values that GitHub does not allow an expression for — `runs-on`, `branches`, matrix
+entries, `timeout-minutes` — were baked in at generation time from the answers you gave.
+They live at the top of the file too.
+
+The setup sequence (toolchain install, cache restore, dependency install) is a local
+composite action under `.github/actions/`. Every job calls it, so the cache key and the
+install command exist in exactly one place.
+
+## Matrix
+
+`Build` and `Test` fan out over the runner OS list, and over the language version list
+for Node and Python. Widen either by editing the `matrix:` block:
+
+```yaml
+    strategy:
+      matrix:
+        os: ["ubuntu-latest", "windows-latest", "macos-latest"]
+```
+
+`fail-fast: false` is set deliberately — one red cell should not cancel the others and
+hide whether the failure is version-specific.
+
+## Caching
+
+The dependency cache is keyed on the lockfile hash and falls back to a partial
+`restore-keys` match, so a lockfile change costs one cold install rather than every run.
+
+- **Node** — the package manager's store, keyed on any lockfile shape present.
+- **Python** — `setup-uv`'s built-in cache of `~/.cache/uv`.
+- **.NET** — NuGet packages, redirected to a workspace-local folder so the path is the
+  same on every runner OS.
+- **Go** — `GOCACHE` and `GOMODCACHE`, resolved with `go env` rather than hardcoded.
+
+Nothing is cached that a build produces; only downloaded dependencies.
+
+## Required checks
+
+Mark **`CI gate`** required, and nothing else. Matrix cells appear and disappear as you
+edit the version list, and a required check whose name no longer exists blocks every
+pull request forever. `CI gate` fails when any job it needs failed, was cancelled, or
+was skipped, so requiring it requires all of them.
+
+Repository → Settings → Branches → add a rule for `{{ ciDefaultBranch }}` → *Require
+status checks to pass* → select `CI gate`. Or:
+
+```bash
+gh api --method PUT "repos/{owner}/{repo}/branches/{{ ciDefaultBranch }}/protection" \
+  --input - <<'JSON'
+{
+  "required_status_checks": { "strict": true, "contexts": ["CI gate"] },
+  "enforce_admins": false,
+  "required_pull_request_reviews": null,
+  "restrictions": null
+}
+JSON
+```
+
+## Permissions
+
+The workflow requests `contents: read` and nothing else. A job that needs to write
+(publish a package, comment on a PR, push a tag) should declare the extra scope on that
+job alone, never at the workflow level.
+
+## Notes
+
+- **npm users**: `INSTALL_COMMAND` is `npm install`. Switch it to `npm ci` once
+  `package-lock.json` is committed — it is faster and refuses to silently update the
+  lockfile. pnpm, Yarn, and Bun already enforce a frozen lockfile when `CI` is set.
+- **Corepack** provides the pnpm/Yarn version pinned in `package.json#packageManager`.
+  It is bundled with the Node versions in the default matrix; if you move to a Node
+  release that has dropped it, replace the Corepack step with `pnpm/action-setup`.
+- **Go linting** is `gofmt` plus `go vet`, which need no configuration and no third-party
+  action. Add `golangci-lint` when you are ready to own a `.golangci.yml`.
+- Dependabot (`.github/dependabot.yml`) keeps the pinned action majors current. Add your
+  language ecosystem to it when you want dependency PRs for the application too.

package/templates/layers/db-core/blueprint.yaml

@@ -0,0 +1,98 @@
+id: db-core
+kind: layer
+name: Database core
+description: >
+  The persistence seam: repository + unit-of-work ports, an engine-neutral error
+  taxonomy, one typed config surface, and an in-memory adapter so the repo runs
+  before any engine is chosen. Every db-* layer implements these ports.
+
+tags: [db, persistence, repository, unit-of-work, ports-and-adapters, foundation]
+
+# Root of the db-* family: depends on nothing, so it can be pulled in transitively by any
+# engine layer. `db-none` declares the conflict from its own side — naming it here would
+# make the whole catalog fail to load until that blueprint exists (loader.assertReferencesResolve).
+requires: []
+conflicts: []
+provides: [db-abstraction, repository-pattern, unit-of-work, db-config, db-errors]
+
+# The seam is a port/adapter boundary, so it slots into anything with a persistence edge.
+supportsArchitectures:
+  - clean
+  - hexagonal
+  - onion
+  - layered
+  - ddd-tactical
+  - vertical-slice
+  - modular-monolith
+  - monolith
+  - microservices
+  - cqrs
+  - event-driven
+
+variables:
+  - name: dbEnvPrefix
+    prompt: Environment-variable prefix for database settings
+    type: string
+    default: DB
+    required: false
+
+  - name: dotnetTargetFramework
+    prompt: Target framework for the data project
+    type: string
+    default: net10.0
+    required: false
+    when: "stack == 'dotnet'"
+
+files:
+  # How to consume the seam and which env vars drive it — layer-owned, never contested.
+  - from: files/docs/persistence.md
+    to: .
+
+  # The base usually ships its own; ours only lands when nothing else claimed the path.
+  - from: files/.env.example
+    to: .
+    onConflict: skip
+
+  # TypeScript and Node share one implementation — ESM, Promise-based, no runtime deps.
+  - from: files/src/db/**
+    to: .
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # `def __init__` and `__all__` parse as path tokens, so plan-time token checking would
+  # reject these files. None of the three carries a groundplan token, so raw loses nothing.
+  - from: files/src/__solutionName.snake__/db/{api,errors,memory}.py
+    to: .
+    raw: true
+    when: "stack == 'python'"
+
+  - from: files/src/__solutionName.snake__/db/{config,ports,retry}.py
+    to: .
+    when: "stack == 'python'"
+
+  - from: files/tests/**
+    to: .
+    when: "stack == 'python'"
+
+  - from: files/src/__solutionName.dot__.Data/**
+    to: .
+    when: "stack == 'dotnet'"
+
+  - from: files/internal/db/**
+    to: .
+    when: "stack == 'go'"
+
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply: []

package/templates/layers/db-core/files/.env.example

@@ -0,0 +1,18 @@
+# Persistence (db-core). Every value here has a typed default in the db config module,
+# so the app runs with this file absent — it falls back to the in-memory adapter.
+
+# Connection string. Empty or unset = no engine layer installed.
+# An engine layer (db-postgres, db-mysql, db-mongo, ...) documents the exact format.
+{{ dbEnvPrefix }}_URL=
+
+{{ dbEnvPrefix }}_POOL_MIN=1
+{{ dbEnvPrefix }}_POOL_MAX=10
+{{ dbEnvPrefix }}_CONNECT_TIMEOUT_MS=10000
+{{ dbEnvPrefix }}_STATEMENT_TIMEOUT_MS=30000
+
+# Retries apply only to errors the taxonomy marks retryable (timeout/transient/unavailable).
+{{ dbEnvPrefix }}_MAX_TX_RETRIES=3
+{{ dbEnvPrefix }}_RETRY_BASE_DELAY_MS=50
+
+# Never enable in production: query logs can carry personal data.
+{{ dbEnvPrefix }}_LOG_QUERIES=false

package/templates/layers/db-core/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.Data/{{ solutionName | dot }}.Data.csproj" />
+  </Folder>
+</Solution>

package/templates/layers/db-core/files/docs/persistence.md

@@ -0,0 +1,91 @@
+# Persistence
+
+`db-core` is the seam between application code and whatever database this project ends up
+using. It ships **ports only** — repository, unit of work, an error taxonomy, one config
+surface — plus an in-memory adapter so the repo builds, tests and runs before any engine
+layer is installed.
+
+## The rule
+
+Application code imports the seam. It never imports a driver.
+
+```
+application  ──▶  db (ports)  ◀──  db-postgres / db-mongo / db-sqlite (engine layers)
+```
+
+If you find yourself importing a driver type outside the engine layer, the abstraction has
+leaked and the next database swap will be a rewrite.
+
+## Configuration
+
+Every setting is read in exactly one module and has a typed default there. The app starts
+with no environment set at all — it just runs on the in-memory adapter.
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `{{ dbEnvPrefix }}_URL` | *(empty)* | Connection string. Empty means no engine installed. |
+| `{{ dbEnvPrefix }}_POOL_MIN` | `1` | Minimum pooled connections. |
+| `{{ dbEnvPrefix }}_POOL_MAX` | `10` | Maximum pooled connections. |
+| `{{ dbEnvPrefix }}_CONNECT_TIMEOUT_MS` | `10000` | Connect timeout. |
+| `{{ dbEnvPrefix }}_STATEMENT_TIMEOUT_MS` | `30000` | Per-statement timeout. |
+| `{{ dbEnvPrefix }}_MAX_TX_RETRIES` | `3` | Retries for *retryable* failures only. |
+| `{{ dbEnvPrefix }}_RETRY_BASE_DELAY_MS` | `50` | Base for exponential backoff. |
+| `{{ dbEnvPrefix }}_LOG_QUERIES` | `false` | Query logging. Leave off in production. |
+
+Do not read these variables anywhere else. Add new settings to the same config module so
+there stays exactly one place to audit.
+
+## Error taxonomy
+
+Engine layers translate vendor error codes into one set of kinds, so callers branch on
+intent instead of on a Postgres SQLSTATE:
+
+`not-found` · `conflict` · `integrity` · `timeout` · `transient` · `unavailable` · `unknown`
+
+Only `timeout`, `transient` and `unavailable` are retryable, and the retry helper is the
+only thing that should act on that — never retry a `conflict` in a loop of your own.
+
+## Transactions
+
+The unit of work is the *only* way to obtain a repository. That is deliberate: it makes
+"which transaction is this write in?" answerable by reading one line of code.
+
+## Where the code lives
+
+| Stack | Location |
+|---|---|
+| TypeScript / Node | `src/db/` |
+| Python | `src/{{ solutionName | snake }}/db/` |
+| .NET | `src/{{ solutionName | dot }}.Data/` |
+| Go | `internal/db/` |
+
+## Installing an engine layer
+
+An engine layer implements the same ports and registers itself once at startup — the
+registration function in the seam's entry point (`useDatabase`, `use_database`, or the
+container registration for .NET). Nothing else in the codebase changes.
+
+## Per-stack notes
+
+- **TypeScript / Node** — the test file uses Vitest. If this base runs Jest instead, change
+  the one import in `src/db/memory.test.ts`; nothing else is runner-specific.
+- **Python** — requires 3.10+. The public surface is `{{ solutionName | snake }}.db.api` rather
+  than a package-init module: Groundplan's path-token grammar consumes double-underscore path
+  segments, so a template cannot ship a dunder filename. `db/` therefore works as an implicit
+  namespace package. If your build backend uses `find_packages` rather than
+  `find_namespace_packages`, add an empty package-init file to `src/{{ solutionName | snake }}/db/`
+  by hand. Tests drive the async ports with `asyncio.run`, so no async pytest plugin is needed;
+  imports assume the src-layout package.
+- **.NET** — `{{ solutionName | dot }}.Data` is a dependency-free class library, already in
+  the solution. Reference it from the host project that owns the connection.
+
+  `DatabaseOptions.FromEnvironment()` keeps the library free of a hosting dependency; an
+  ASP.NET host may bind its own `IConfiguration` section onto the same record instead.
+- **Go** — Go has no generic methods, so a repository is built from a unit of work with
+  `NewRepository[T, K](name, uow.Collection(name))`. Entities implement `Field(name)` to be
+  queryable by criteria, which keeps the seam free of reflection.
+
+## The in-memory adapter is not a database
+
+It serializes transactions behind a single lock and loses everything on exit. It exists to
+keep the repo runnable and unit tests fast. Install an engine layer before shipping.

package/templates/layers/db-core/files/internal/db/config.go

@@ -0,0 +1,108 @@
+// Package db is the persistence seam: repository and unit-of-work ports, one error
+// taxonomy, and an in-memory adapter. Engine packages implement these interfaces.
+package db
+
+import (
+	"fmt"
+	"os"
+	"strconv"
+	"strings"
+)
+
+const envPrefix = "{{ dbEnvPrefix }}"
+
+// Config is the only place database settings are read.
+type Config struct {
+	// URL empty means no engine layer is installed; the in-memory adapter takes over.
+	URL                string
+	PoolMin            int
+	PoolMax            int
+	ConnectTimeoutMS   int
+	StatementTimeoutMS int
+	MaxTxRetries       int
+	RetryBaseDelayMS   int
+	LogQueries         bool
+}
+
+// Typed defaults. The single place a literal database value may appear.
+func defaults() Config {
+	return Config{
+		URL:                "",
+		PoolMin:            1,
+		PoolMax:            10,
+		ConnectTimeoutMS:   10_000,
+		StatementTimeoutMS: 30_000,
+		MaxTxRetries:       3,
+		RetryBaseDelayMS:   50,
+		LogQueries:         false,
+	}
+}
+
+// LoadConfig reads DB_* and fails fast on a malformed value rather than passing it to a driver.
+func LoadConfig() (Config, error) {
+	cfg := defaults()
+	var err error
+
+	cfg.URL = str("URL", cfg.URL)
+	if cfg.PoolMin, err = integer("POOL_MIN", cfg.PoolMin); err != nil {
+		return cfg, err
+	}
+	if cfg.PoolMax, err = integer("POOL_MAX", cfg.PoolMax); err != nil {
+		return cfg, err
+	}
+	if cfg.ConnectTimeoutMS, err = integer("CONNECT_TIMEOUT_MS", cfg.ConnectTimeoutMS); err != nil {
+		return cfg, err
+	}
+	if cfg.StatementTimeoutMS, err = integer("STATEMENT_TIMEOUT_MS", cfg.StatementTimeoutMS); err != nil {
+		return cfg, err
+	}
+	if cfg.MaxTxRetries, err = integer("MAX_TX_RETRIES", cfg.MaxTxRetries); err != nil {
+		return cfg, err
+	}
+	if cfg.RetryBaseDelayMS, err = integer("RETRY_BASE_DELAY_MS", cfg.RetryBaseDelayMS); err != nil {
+		return cfg, err
+	}
+	cfg.LogQueries = boolean("LOG_QUERIES", cfg.LogQueries)
+
+	return cfg, nil
+}
+
+// HasEngine reports whether an engine layer supplied a connection URL.
+func (c Config) HasEngine() bool { return c.URL != "" }
+
+func raw(key string) (string, bool) {
+	value := os.Getenv(envPrefix + "_" + key)
+	return value, value != ""
+}
+
+func str(key, fallback string) string {
+	if value, ok := raw(key); ok {
+		return value
+	}
+	return fallback
+}
+
+func integer(key string, fallback int) (int, error) {
+	value, ok := raw(key)
+	if !ok {
+		return fallback, nil
+	}
+	parsed, err := strconv.Atoi(value)
+	if err != nil {
+		return fallback, fmt.Errorf("%s_%s must be an integer, got %q", envPrefix, key, value)
+	}
+	return parsed, nil
+}
+
+func boolean(key string, fallback bool) bool {
+	value, ok := raw(key)
+	if !ok {
+		return fallback
+	}
+	switch strings.ToLower(value) {
+	case "1", "true", "yes":
+		return true
+	default:
+		return false
+	}
+}