docs: prepare governance docs and release notes for 0.1.0

Add CONTRIBUTING.md, SECURITY.md, and VERSIONING.md so contributors and
consumers have a public policy for how to contribute, how to report a
vulnerability, and what the API/format stability promise actually
covers pre-1.0. Update the CHANGELOG and README to describe the 0.1.0
release as shipped — the security model, the data-vs-API versioning
split, and the newly named open-parameter errors — and tidy the
options.rs budget doc comments to match current enforcement rather
than a since-landed future slice.

Wire the release workflows to gate a tag on a matching CHANGELOG
section and to build the GitHub release notes from that section
instead of auto-generated commit-subject notes, via a shared
scripts/ci/changelog_section.sh.

Author: farhan-syah

.github/workflows/release-validate.yml

@@ -18,6 +18,9 @@ on:
       is_full_release:
         description: "true when the version carries no prerelease suffix"
         value: ${{ jobs.validate.outputs.is_full_release }}
+      base_version:
+        description: "Tag version with any prerelease suffix stripped — the CHANGELOG heading"
+        value: ${{ jobs.validate.outputs.base_version }}
 
 permissions:
   contents: read
@@ -29,6 +32,7 @@ jobs:
     outputs:
       version: ${{ steps.version.outputs.version }}
       is_full_release: ${{ steps.version.outputs.is_full_release }}
+      base_version: ${{ steps.version.outputs.base_version }}
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -73,3 +77,15 @@ jobs:
           fi
 
           echo "version=$TAG_VERSION" >> "$GITHUB_OUTPUT"
+          echo "base_version=$TAG_BASE" >> "$GITHUB_OUTPUT"
+
+      # A release with no changelog entry is a release nobody can read. The gate
+      # lives here, in the shared validator, so the tag push and the dispatched
+      # publish cannot disagree about whether it was satisfied — and so it fails
+      # at the tag, before the suite runs, rather than after publishing.
+      #
+      # A prerelease is checked against its base version: `v0.1.0-beta.1` needs
+      # the `## [0.1.0]` section it is a candidate for, so the notes are written
+      # once and rehearsed by every beta.
+      - name: Require a changelog section
+        run: bash scripts/ci/changelog_section.sh "${{ steps.version.outputs.base_version }}"

.github/workflows/release.yml

@@ -163,12 +163,36 @@ jobs:
           set -euo pipefail
           bash scripts/ci/verify_release_artifacts.sh ./artifacts "$VERSION"
 
+      # The changelog is the release notes. Auto-generated notes list commit
+      # subjects, which describe what was done to the code; the changelog
+      # describes what changed for the person upgrading. `validate-version`
+      # has already proved this section exists and is non-empty.
+      - name: Build release notes from the changelog
+        env:
+          TAG: ${{ inputs.tag }}
+          BASE: ${{ needs.validate-version.outputs.base_version }}
+        run: |
+          set -euo pipefail
+          PREVIOUS_TAG=$(git tag --sort=-v:refname 'v*' | grep -v "^${TAG}$" | head -n 1 || true)
+
+          bash scripts/ci/changelog_section.sh "$BASE" /tmp/changelog-section.md
+
+          {
+            cat /tmp/changelog-section.md
+            echo
+            if [[ -n "$PREVIOUS_TAG" ]]; then
+              echo "**Full diff:** https://github.com/nodedb-lab/pagedb/compare/${PREVIOUS_TAG}...${TAG}"
+            else
+              echo "**Tree:** https://github.com/nodedb-lab/pagedb/tree/${TAG}"
+            fi
+          } > /tmp/release-notes.md
+
       - name: Create GitHub Release
         uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3.0.2
         with:
           tag_name: ${{ inputs.tag }}
           name: pagedb ${{ needs.validate-version.outputs.version }}
-          generate_release_notes: true
+          body_path: /tmp/release-notes.md
           draft: false
           prerelease: ${{ needs.validate-version.outputs.is_full_release != 'true' }}
           files: artifacts/*

CHANGELOG.md

@@ -1,64 +1,39 @@
 # Changelog
 
-All notable changes to this project are documented here. The format is based on
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
-adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+All notable changes to this project are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.1.0] - 2026-07-28
 
-The first stable release. Pre-releases are published as `0.1.0-beta.N`; the
-entries below describe `0.1.0` as a whole rather than deltas against a shipped
-version, since none exists yet.
+The first release. Pre-releases were published as `0.1.0-beta.N`; the entries below describe `0.1.0` as a whole rather than deltas against a shipped version, since none exists yet.
 
 ### Added
 
-- **B+ tree surface** — sorted `bytes → bytes` store with copy-on-write shadow
-  paging, A/B headers, ACID transactions, range scans, monotonic append, and
-  bulk load. Reads return `Bytes` borrowed from the page cache; scans come
-  bounded (`scan_from`, `scan_prefix_from`) or materialising.
-- **Segment File API** — engine-owned, append-mostly, atomically sealed
-  encrypted files for formats that own their own layout (vectors, columnar
-  blocks, FTS postings, R-trees).
-- **Encrypted pager** — every persistent page is authenticated; AES-256-GCM and
-  ChaCha20-Poly1305 cipher dispatch with per-page `cipher_id` for cipher
-  agility. SIEVE page cache with bounded memory budgets.
-- **Key hierarchy** — KEK → MK → DEK derivation, stateful nonce generation with
-  a durable anchor (nonce reuse impossible under one key), `zeroize` on all key
-  material.
-- **Realm isolation** — `RealmId` bound into AEAD AAD on every persistent page;
-  misrouted reads fail tag verification. Per-realm quotas.
-- **Cross-platform VFS** — Linux (`io_uring`), Windows (IOCP), macOS/iOS
-  (Grand Central Dispatch), Android, WASM/OPFS, and WASI backends, plus a
-  tokio thread-pool fallback and an in-memory backend, with format-bit identity
-  across targets. Backends may complete a positional read or write in several
-  calls; PageDB finishes the caller's whole buffer before treating authenticated
-  metadata as present or durable. On Linux the backend choice is made at run
-  time: where the kernel refuses an `io_uring` ring — `RLIMIT_MEMLOCK`
-  exhausted, seccomp blocking `io_uring_setup`, a kernel older than 5.1 — the
-  open logs a warning and continues on the thread pool rather than failing.
-  Every native backend shares one advisory-lock implementation, so processes on
-  different backends still exclude each other on the same store.
-- **Snapshots** — `snapshot_to`, `restore_from`, and incremental apply, each
-  authenticated against the exact state its manifest describes. Destinations
-  must be empty; malformed or incomplete artifacts fail closed.
-- **Recovery** — open-flow GC, apply-journal replay, deep-walk `fsck`, and the
-  `pagedb-fsck` binary.
-- **Online rekey** — rekey the database under a new key with mixed-cipher and
-  mixed-epoch page coexistence (no full-file migration).
+- **B+ tree surface** — sorted `bytes → bytes` with copy-on-write shadow paging, A/B headers, ACID transactions, range scans, monotonic append, and bulk load. Reads return `Bytes` borrowed from the page cache; scans are bounded (`scan_from`, `scan_prefix_from`) or materialising.
+- **Segment File API** — engine-owned, append-mostly, atomically sealed encrypted files for formats that own their own layout (vectors, columnar blocks, FTS postings, R-trees).
+- **Encrypted pager** — every persistent page is authenticated; AES-256-GCM and ChaCha20-Poly1305 with per-page `cipher_id` for cipher agility. SIEVE page cache with bounded memory budgets.
+- **Key hierarchy** — KEK → MK → per-`(realm, file)` DEK/IK, stateful nonce generation with a durable anchor, `zeroize` on all key material.
+- **Realm isolation** — `RealmId` bound into AEAD AAD on every persistent page and recorded in the `main.db` header. Per-realm quotas.
+- **Cross-platform VFS** — Linux (`io_uring`), Windows (IOCP), macOS/iOS (Grand Central Dispatch), Android, WASM/OPFS and WASI backends, plus a tokio thread-pool fallback and an in-memory backend, with format-bit identity across targets. On Linux the backend is chosen at run time: a kernel that refuses an `io_uring` ring falls back to the thread pool with a warning instead of failing the open. All native backends share one advisory-lock implementation, so processes on different backends still exclude each other on one store.
+- **Snapshots** — `snapshot_to`, `restore_from`, and incremental apply, each authenticated against the state its manifest describes. Destinations must be empty; malformed or incomplete artifacts fail closed.
+- **Recovery** — open-flow GC, apply-journal replay, deep-walk `fsck`, and the `pagedb-fsck` binary.
+- **Online rekey** — rekey under a new key with mixed-cipher and mixed-epoch page coexistence; no full-file migration.
 - **Handle modes** — `Standalone`, `Follower`, `ReadOnly`, and `Observer`.
-- **Failures report themselves** — an unreadable free-list chain, main file, or
-  segment catalog fails `stats()` instead of reporting zero; compaction never
-  skips a catalog entry whose file it cannot open; segment open distinguishes a
-  missing file from a permission or backend error; and only genuine contention
-  is reported as contention. Persisted named-counter rows are validated at open,
-  and commit-history keys are rejected unless exactly eight bytes.
+- **Open refusals name the parameter, not the store** — `KeyMismatch`, `PageSizeMismatch`, and `RealmMismatch`, each decided before anything is read or written, and none reported as corruption.
+- **Failures report themselves** — an unreadable free-list chain, main file, or segment catalog fails `stats()` instead of reporting zero; compaction never skips a catalog entry whose file it cannot open; segment open distinguishes a missing file from a permission or backend error; and only genuine contention is reported as contention. Persisted named-counter rows are validated at open, and commit-history keys are rejected unless exactly eight bytes.
+
+### Security
+
+- Threat model documented in the README; disclosure policy in `SECURITY.md`.
+- Data keys are scoped per file, so no two files share a nonce space.
+- `io_uring`: an error mid-submission no longer frees a transfer buffer the kernel may still be writing into.
+- `pagedb-fsck` requires an explicit KEK — no all-zero default.
+- Diagnostic reports redact embedder-chosen segment names.
 
 ### Known limitations
 
-- Pre-1.0: the on-disk format may change between minor versions until 1.0.
+- Pre-1.0: the API may break in a minor bump. The on-disk format is frozen for the `0.1.x` line and any later format change ships a migrator — see `VERSIONING.md`. Stores written by a `0.1.0-beta` pre-release are not readable by `0.1.0`.
+- pagedb detects tampering, not reversion: an attacker who can write to the store files can substitute an older genuine ciphertext and it will authenticate. Freshness belongs above pagedb.
+- `main.db` cannot be reconstructed from `seg/` — back the directory up as a unit.
 - Single-writer per database; multi-writer cross-process is not supported.
-- Writes carry per-page AEAD and copy-on-write overhead; for throughput-bound
-  plaintext KV workloads a generic store may be faster.
-- Applying an incremental snapshot stages a full copy of `main.db` alongside the
-  original and commits it with a rename, so a follower needs room for two copies
-  of the database during an apply.
+- Writes carry per-page AEAD and copy-on-write overhead; for throughput-bound plaintext KV workloads a generic store may be faster.
+- Applying an incremental snapshot stages a full copy of `main.db` alongside the original, so a follower needs room for two copies during an apply.