Release 0.4.0a4

.github/workflows/build-tests.yml

@@ -2,14 +2,14 @@ name: Build Tests
 
 on:
   pull_request:
-    branches: [dev, master, main]
+    branches: [dev, master]
   workflow_dispatch:
 
 jobs:
   build:
     uses: OpenVoiceOS/gh-automations/.github/workflows/build-tests.yml@dev
-    secrets: inherit
     with:
       python_versions: '["3.10", "3.11", "3.12", "3.13", "3.14"]'
-      install_extras: ''
+      install_extras: 'test'
       test_path: 'tests'
+      pr_comment: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}

.github/workflows/cipher-tests.yml

@@ -0,0 +1,29 @@
+name: Cipher Tests
+
+# Dedicated workflow for the [cipher] extra (sqlcipher3 + libsqlcipher-dev).
+# The shared build-tests.yml covers the unencrypted path on Python 3.10-3.14;
+# this one adds a single Python 3.11 run with sqlcipher installed so the
+# encrypted backend is exercised on every PR.
+
+on:
+  pull_request:
+    branches: [dev, master, main]
+  workflow_dispatch:
+
+jobs:
+  test-cipher:
+    name: "SQLite + SQLCipher"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install sqlcipher system library
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libsqlcipher-dev
+      - run: pip install -e ".[cipher]"
+      # schema-v2 features (migrate, refresh, _check_forward_compat) ship in the 0.6.0a1 prerelease
+      - run: pip install "hivemind-plugin-manager==0.6.0a1" pytest
+      - run: pytest tests/test_sqlitedb.py -q -p no:ovoscope

.github/workflows/coverage.yml

@@ -8,10 +8,11 @@ on:
 jobs:
   coverage:
     uses: OpenVoiceOS/gh-automations/.github/workflows/coverage.yml@dev
-    secrets: inherit
     with:
       python_version: '3.11'
       coverage_source: 'hivemind_sqlite_database'
-      test_path: 'tests/'
+      pre_install_pip: '"hivemind-plugin-manager==0.6.0a1"'
+      test_path: 'tests/ --ignore=tests/e2e'
       install_extras: ''
       min_coverage: 0
+      pr_comment: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}

.github/workflows/license_check.yml

@@ -8,4 +8,5 @@ on:
 jobs:
   license_check:
     uses: OpenVoiceOS/gh-automations/.github/workflows/license-check.yml@dev
-    secrets: inherit
+    with:
+      pr_comment: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}

.github/workflows/lint.yml

@@ -2,13 +2,13 @@ name: Lint
 
 on:
   pull_request:
-    branches: [dev, master, main]
+    branches: [dev, master]
   workflow_dispatch:
 
 jobs:
   lint:
     uses: OpenVoiceOS/gh-automations/.github/workflows/lint.yml@dev
-    secrets: inherit
     with:
       ruff: true
       pre_commit: false   # set true if .pre-commit-config.yaml exists
+      pr_comment: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}

.github/workflows/pip_audit.yml

@@ -8,4 +8,5 @@ on:
 jobs:
   pip_audit:
     uses: OpenVoiceOS/gh-automations/.github/workflows/pip-audit.yml@dev
-    secrets: inherit
+    with:
+      pr_comment: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository }}

.github/workflows/policy-e2e.yml

@@ -0,0 +1,24 @@
+name: Policy Migration E2E
+
+on:
+  pull_request:
+    branches: [dev, master]
+  workflow_dispatch:
+
+jobs:
+  policy_e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+      - run: pip install -e ".[test]"
+      # Cross-repo policy stack (published prereleases) + hivescope with db= injection
+      - run: >-
+          pip install
+          "hivescope==0.4.0a2"
+          "hivemind-core==4.3.0a2"
+          "hivemind-ovos-agent-plugin==0.2.0a1"
+          "hivemind-plugin-manager==0.6.0a1"
+      - run: pytest tests/e2e/test_policy_migration_e2e.py -q -p no:cacheprovider

.github/workflows/publish_stable.yml

@@ -7,7 +7,8 @@ on:
 jobs:
   publish_stable:
     uses: OpenVoiceOS/gh-automations/.github/workflows/publish-stable.yml@dev
-    secrets: inherit
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
     with:
       branch: 'master'
       version_file: 'hivemind_sqlite_database/version.py'

.github/workflows/release-preview.yml

@@ -7,8 +7,8 @@ on:
 
 jobs:
   release_preview:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
     uses: OpenVoiceOS/gh-automations/.github/workflows/release-preview.yml@dev
-    secrets: inherit
     with:
       package_name: 'hivemind_sqlite_database'
       version_file: 'hivemind_sqlite_database/version.py'

.github/workflows/release_workflow.yml

@@ -4,11 +4,13 @@ on:
   pull_request:
     types: [closed]
     branches: [dev]
+  workflow_dispatch:
 
 jobs:
   publish_alpha:
     uses: OpenVoiceOS/gh-automations/.github/workflows/publish-alpha.yml@dev
-    secrets: inherit
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
     with:
       branch: 'dev'
       base_branch: 'master'

.github/workflows/repo-health.yml

@@ -2,12 +2,12 @@ name: Repo Health
 
 on:
   pull_request:
-    branches: [dev, master, main]
+    branches: [dev, master]
   workflow_dispatch:
 
 jobs:
   repo_health:
+    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
     uses: OpenVoiceOS/gh-automations/.github/workflows/repo-health.yml@dev
-    secrets: inherit
     with:
       version_file: 'hivemind_sqlite_database/version.py'

AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+SQLite (and optional SQLCipher-encrypted) `AbstractDB` backend plugin for hivemind-core, storing HiveMind client records (API keys, crypto keys, ACLs).
+
+## Setup
+
+```bash
+pip install -e .
+# encrypted-database support (SQLCipher / AES-256):
+pip install -e ".[cipher]"   # needs libsqlcipher system lib (apt install libsqlcipher-dev)
+```
+
+## Test
+
+```bash
+pytest tests/
+```
+
+Single suite lives in `tests/test_sqlitedb.py`. The repo's own `tests.yml` runs it with `-p no:ovoscope` and exercises both the plain and the SQLCipher path. Cipher tests need `libsqlcipher-dev` installed.
+
+## Lint/Typecheck
+
+Ruff, via the shared `lint.yml` workflow (`ruff: true`, no pre-commit config present). No typecheck configured.
+
+## Layout
+
+- `hivemind_sqlite_database/__init__.py` — the entire plugin: `SQLiteDB` dataclass extending `AbstractDB`. Schema creation, `PRAGMA user_version` migration (v1→v2 folds legacy `intent_blacklist`/`skill_blacklist` columns into `Client.metadata`), and CRUD (`add_item`, `search_by_value`, `get_client_by_id`, `__iter__`, `__len__`, `commit`).
+- `hivemind_sqlite_database/version.py` — version constants (do not edit).
+- `tests/test_sqlitedb.py` — full behavioural suite.
+
+Entry-point group: `hivemind.database` → `hivemind-sqlite-db-plugin = hivemind_sqlite_database:SQLiteDB`. Discovered by `hivemind-plugin-manager`; selected in hivemind-core config under `database.module`.
+
+## Conventions
+
+- Branches: `dev` (work) and `master` (stable). NEVER `main`.
+- Never edit `version.py`; gh-automations bumps semver from conventional-commit prefixes (`feat:`/`fix:`/`feat!:`).
+- New repos private by default.
+- Commit identity: JarbasAi <jarbasai@mailfence.com>.
+- Reference `OpenVoiceOS/gh-automations` reusable workflows at `@dev`.
+- No Neon / `neon-*` references.
+- No meta-commentary (no history, no dates) in code, docs, commits, or PRs — describe current state only.
+- CI is provided by OpenVoiceOS/gh-automations.
+
+## Gotchas
+
+- `_VALID_COLUMNS` allowlist gates `search_by_value` keys; SQL column name is interpolated only after passing that frozenset (issue #1 tracks an SQL-security review).
+- Legacy `intent_blacklist`/`skill_blacklist`/`message_blacklist` columns remain in the table but are NULLed on write; canonical data lives in `metadata` JSON. `message_blacklist` is purged entirely (not part of `Client`).
+- `migrate()` guards on `getattr(AbstractDB, "SCHEMA_VERSION", 1)` so it tolerates older hivemind-plugin-manager that predates the constant — do not assume the attribute exists.
+- WAL journal mode is enabled for both plain and encrypted DBs; `check_same_thread=False` with a `threading.Lock` guarding writes.
+- Encrypted and plaintext databases are not interchangeable and there is no migration between them; lost passphrase = unrecoverable data.
+- `tests.yml` is a repo-local workflow separate from the shared build-tests; both run the same suite.

CHANGELOG.md

@@ -1,57 +1,72 @@
 # Changelog
 
-## [0.2.1a4](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.2.1a4) (2026-04-15)
+## [0.4.0a4](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.4.0a4) (2026-07-04)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.2.1a3...0.2.1a4)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.4.0a3...0.4.0a4)
 
 **Merged pull requests:**
 
-- ci: sync publish workflows from shared templates [\#22](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/22) ([JarbasAl](https://github.com/JarbasAl))
+- Update actions/checkout action to v7 [\#40](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/40) ([renovate[bot]](https://github.com/apps/renovate))
 
-## [0.2.1a3](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.2.1a3) (2026-04-15)
+## [0.4.0a3](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.4.0a3) (2026-07-04)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.2.1a2...0.2.1a3)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.4.0a2...0.4.0a3)
 
-## [0.2.1a2](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.2.1a2) (2026-04-15)
+**Merged pull requests:**
+
+- test: hivescope e2e + CI [\#41](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/41) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.4.0a2](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.4.0a2) (2026-06-05)
+
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.4.0a1...0.4.0a2)
+
+**Merged pull requests:**
+
+- docs: zero-to-hero README and /docs coverage [\#38](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/38) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.4.0a1](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.4.0a1) (2026-06-05)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.2.1a1...0.2.1a2)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.3.0a4...0.4.0a1)
 
 **Merged pull requests:**
 
-- Update actions/setup-python action to v6 [\#15](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/15) ([renovate[bot]](https://github.com/apps/renovate))
-- Update actions/checkout action to v6 [\#9](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/9) ([renovate[bot]](https://github.com/apps/renovate))
+- feat\(db\): schema v2 migration — fold legacy blacklist columns into metadata [\#32](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/32) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.2.1a1](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.2.1a1) (2026-04-15)
+## [0.3.0a4](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.3.0a4) (2026-06-05)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.2.0a1...0.2.1a1)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.3.0a3...0.3.0a4)
 
 **Merged pull requests:**
 
-- fix: move pytest\_plugins to top-level conftest for pytest 9 compatibility [\#18](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/18) ([JarbasAl](https://github.com/JarbasAl))
+- ci: dedupe tests.yml — drop test-plain, rename to cipher-tests.yml [\#34](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/34) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.2.0a1](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.2.0a1) (2026-04-15)
+## [0.3.0a3](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.3.0a3) (2026-05-20)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.0.4a2...0.2.0a1)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.3.0a2...0.3.0a3)
 
 **Merged pull requests:**
 
-- feat: release 0.1.0 — tests, thread-safety, SQL injection fix [\#14](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/14) ([JarbasAl](https://github.com/JarbasAl))
+- ci: pass PYPI\_TOKEN explicitly, drop secrets:inherit elsewhere [\#33](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/33) ([JarbasAl](https://github.com/JarbasAl))
+
+## [0.3.0a2](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.3.0a2) (2026-05-18)
+
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.3.0a1...0.3.0a2)
 
-## [0.0.4a2](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.0.4a2) (2025-12-19)
+**Closed issues:**
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.0.4a1...0.0.4a2)
+- security: encrypted db [\#2](https://github.com/JarbasHiveMind/hivemind-sqlite-database/issues/2)
 
 **Merged pull requests:**
 
-- chore\(deps\): update actions/setup-python action to v6 [\#12](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/12) ([renovate[bot]](https://github.com/apps/renovate))
+- Preserve client metadata \(supersedes \#29\) [\#30](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/30) ([JarbasAl](https://github.com/JarbasAl))
 
-## [0.0.4a1](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.0.4a1) (2025-12-18)
+## [0.3.0a1](https://github.com/JarbasHiveMind/hivemind-sqlite-database/tree/0.3.0a1) (2026-04-15)
 
-[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.0.3...0.0.4a1)
+[Full Changelog](https://github.com/JarbasHiveMind/hivemind-sqlite-database/compare/0.2.1...0.3.0a1)
 
 **Merged pull requests:**
 
-- chore: Configure Renovate [\#7](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/7) ([renovate[bot]](https://github.com/apps/renovate))
+- feat: add SQLCipher encryption support \(password kwarg\) [\#24](https://github.com/JarbasHiveMind/hivemind-sqlite-database/pull/24) ([JarbasAl](https://github.com/JarbasAl))