fix(pkm): A31 — read-only commands tolerate a behind-schema DB (degraded column)

Found by real-install testing of pkm 0.2.0 on .227: A25 added the `degraded`
column with an ALTER-TABLE migration, but migrations run only on a read-WRITE
open. The read-only (immutable=1) open used by non-root readers — and by root
via a read-only subcommand — returns before migrating, so on a system upgraded
from a pre-A25 pkm every read command hitting list_installed crashed with
`sqlite3.OperationalError: no such column: degraded` until some later root
command happened to run the migration. The unit suite never caught it because it
always builds a fresh, fully-migrated DB; only a real upgrade path exposes it —
exactly what step-1 real-install testing is for.

Fix: list_installed selects schema-tolerantly. Columns are introspected once at
open (_table_columns -> self._installed_cols, on BOTH the read-only and the
read-write paths), and a new _col() helper emits `NULL AS <col>` for any column
absent on an un-migrated read-only DB instead of naming it directly — so reads
degrade gracefully (degraded -> None = healthy) regardless of migration timing.
Reuse this pattern for any future migration-added column read on the read path.

tests/pkm/test_pkm_a31_schema_tolerant.py: old-schema DB (no degraded) opened
read-only + list_installed no-crash, tier filter, and full-schema round-trip.
Full pkm suite 323 passed; audit registry 30/30 (A31 added + verified). Folded
into the unreleased pkm 0.2.0 (no version change — 0.2.0 has not shipped).

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

Author: InterGenJLU

pkm/database.py

@@ -196,6 +196,12 @@ def __init__(self, db_path=None, root="/", create_if_missing=True,
                 f"file:{self.db_path}?immutable=1", uri=True
             )
             self.conn.execute("PRAGMA foreign_keys = ON")
+            # PKM-A31: a read-only (immutable) open CANNOT run the ALTER-TABLE
+            # migrations below — so a DB created by an older pkm can be missing
+            # columns this pkm added (e.g. `degraded` from A25). Snapshot the
+            # actual columns so read queries select schema-tolerantly (via
+            # _col) instead of raising "no such column" on an un-migrated DB.
+            self._installed_cols = self._table_columns("installed")
             return
 
         if not create_if_missing and not self.db_path.exists():
@@ -214,6 +220,27 @@ def __init__(self, db_path=None, root="/", create_if_missing=True,
         self._migrate_supersedes_columns()
         self._migrate_q9_columns()
         self._migrate_a25_degraded_column()
+        # PKM-A31: snapshot columns AFTER migrations (read-write path is fully
+        # migrated, so this is the complete set). Keeps the read-tolerant _col
+        # helper correct on both open paths.
+        self._installed_cols = self._table_columns("installed")
+
+    def _table_columns(self, table):
+        """Set of column names present in `table`. Used so read queries tolerate
+        a behind-schema DB (a read-only open can't run the ALTER-TABLE
+        migrations, so an older DB may lack newer columns). PKM-A31."""
+        try:
+            return {row[1] for row in
+                    self.conn.execute(f"PRAGMA table_info({table})")}
+        except sqlite3.OperationalError:
+            return set()
+
+    def _col(self, name):
+        """A SELECT term for an `installed` column that yields NULL when the
+        column is absent on a behind-schema (un-migrated, read-only) DB, instead
+        of raising 'no such column'. PKM-A31."""
+        return name if name in getattr(self, "_installed_cols", ()) \
+            else f"NULL AS {name}"
 
     def _migrate_supersedes_columns(self):
         """Idempotent migration: add superseded_by + superseded_at columns
@@ -328,18 +355,20 @@ def list_installed(self, tier=None):
         can disambiguate same-version-different-release upgrades without
         an extra get_installed roundtrip per package.
         """
+        # PKM-A31: build the column list schema-tolerantly so a read-only open
+        # of a DB created by an older pkm (missing e.g. `degraded`) yields NULL
+        # for the absent column rather than crashing every read command.
+        sel = ", ".join(self._col(c) for c in (
+            "name", "version", "release", "tier", "description",
+            "install_reason", "degraded"))
         if tier:
             rows = self.conn.execute(
-                "SELECT name, version, release, tier, description, "
-                "install_reason, degraded "
-                "FROM installed WHERE tier = ? ORDER BY name",
+                f"SELECT {sel} FROM installed WHERE tier = ? ORDER BY name",
                 (tier,)
             ).fetchall()
         else:
             rows = self.conn.execute(
-                "SELECT name, version, release, tier, description, "
-                "install_reason, degraded "
-                "FROM installed ORDER BY name"
+                f"SELECT {sel} FROM installed ORDER BY name"
             ).fetchall()
         return [
             {"name": r[0], "version": r[1], "release": r[2], "tier": r[3],

tests/pkm/audit/findings.yaml

@@ -436,3 +436,18 @@ findings:
     regression_test: "tests/pkm/test_pkm_a29_a30_guidance_cosmetics.py"
     evidence: "cmd_info header version omits release + hardcoded 50-char rule; 'Required by' lines show bare reverse-dependent version (misreadable); verify --all PROBLEM line + history line overflow narrow terminals."
     fix: "cmd_info shows the full version-release identity (_vr_str) and sizes the '=' rule to the title; get_reverse_depends now carries release so 'Required by' shows version-release (no fabricated default). verify/history line lengths are bounded by existing per-list caps (... and N more) — acceptable, not changed."
+
+  # ---------------- FOUND BY REAL-INSTALL TESTING (post-audit) --------------
+  - id: PKM-A31
+    title: "Read-only commands crash on a behind-schema DB: list_installed queries `degraded` but read-only opens skip the ALTER-TABLE migration"
+    module: database.py
+    locations: ["pkm/database.py:190-199", "pkm/database.py:339-349", "pkm/database.py:252-263"]
+    lens: correctness
+    severity: high
+    tier: trust
+    status: verified
+    owner: maintainer
+    batch: 5
+    regression_test: "tests/pkm/test_pkm_a31_schema_tolerant.py"
+    evidence: "Found 2026-06-16 testing pkm 0.2.0 on .227. A25 added the `degraded` column with _migrate_a25_degraded_column (ALTER TABLE), but migrations run ONLY on a read-write open; the read-only (immutable=1) open used by non-root readers — and by root via a read-only subcommand — returns before migrating. On a system upgraded from a pre-A25 pkm, every read command hitting list_installed (list/the update-summary/etc.) crashed with `sqlite3.OperationalError: no such column: degraded` until some later root command happened to run the migration. The pkm unit suite never caught it because it always builds a fresh, fully-migrated DB — only a real upgrade path exposes it."
+    fix: "list_installed selects schema-tolerantly via a new _col() helper: columns are introspected once at open (_table_columns -> self._installed_cols, on BOTH open paths), and a column absent on an un-migrated read-only DB is emitted as `NULL AS <col>` instead of being named directly — so reads degrade gracefully (degraded -> None = healthy) regardless of migration timing. Pattern to reuse for any future migration-added column read on the read-only path. test_pkm_a31_schema_tolerant.py: old-schema DB (no degraded) read-only open + list_installed no-crash + tier filter + full-schema round-trip."

tests/pkm/test_pkm_a31_schema_tolerant.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""PKM-A31 regression: read-only commands tolerate a behind-schema DB.
+
+Found by real-install testing (2026-06-16, .227): pkm 0.2.0 added the `degraded`
+column (A25) with an ALTER-TABLE migration, but migrations only run on a
+read-WRITE open. A read-only command (`pkm list`, non-root — or root via a
+read-only subcommand) opens the DB immutable and CANNOT migrate it, so on a
+system upgraded from a pre-A25 pkm `list_installed` crashed with
+`sqlite3.OperationalError: no such column: degraded` until some later root
+command happened to run the migration. That is the ugly-crash class the audit
+targets.
+
+Fix: list_installed (and the read path generally) selects schema-tolerantly via
+_col() — a column absent on an un-migrated DB yields NULL instead of raising.
+"""
+
+import sqlite3
+import tempfile
+import unittest
+from pathlib import Path
+
+from pkm.database import PackageDB
+
+
+class SchemaTolerantReadTest(unittest.TestCase):
+    def _old_schema_db(self, path):
+        """A minimal `installed` table as an OLDER pkm would have created it —
+        WITHOUT the `degraded` column (and without other newer columns)."""
+        c = sqlite3.connect(str(path))
+        c.execute(
+            "CREATE TABLE installed ("
+            "id INTEGER PRIMARY KEY, name TEXT, version TEXT, "
+            "release INTEGER DEFAULT 1, tier TEXT, description TEXT, "
+            "install_reason TEXT DEFAULT 'manual')"
+        )
+        c.execute(
+            "INSERT INTO installed (name, version, release, tier, description) "
+            "VALUES ('foo', '1.0', 2, 'core', 'a package')"
+        )
+        c.commit()
+        c.close()
+
+    def test_list_installed_tolerates_missing_degraded(self):
+        with tempfile.TemporaryDirectory() as td:
+            dbp = Path(td) / "pkm.db"
+            self._old_schema_db(dbp)
+            # Read-only open: cannot run the migration → `degraded` stays absent.
+            db = PackageDB(dbp, read_only=True)
+            try:
+                rows = db.list_installed()          # must NOT raise
+            finally:
+                db.close()
+            self.assertEqual(len(rows), 1)
+            self.assertEqual(rows[0]["name"], "foo")
+            self.assertEqual(rows[0]["release"], 2)
+            self.assertIsNone(rows[0]["degraded"])  # absent → NULL → healthy
+
+    def test_tier_filter_also_tolerates_missing_degraded(self):
+        with tempfile.TemporaryDirectory() as td:
+            dbp = Path(td) / "pkm.db"
+            self._old_schema_db(dbp)
+            db = PackageDB(dbp, read_only=True)
+            try:
+                rows = db.list_installed(tier="core")
+            finally:
+                db.close()
+            self.assertEqual(len(rows), 1)
+            self.assertIsNone(rows[0]["degraded"])
+
+    def test_full_schema_db_still_reports_degraded(self):
+        # A normal (read-write, freshly created) DB has the full schema +
+        # migrations, so `degraded` is a real column and round-trips.
+        with tempfile.TemporaryDirectory() as td:
+            dbp = Path(td) / "pkm.db"
+            db = PackageDB(dbp, create_if_missing=True,
+                           root=str(Path(td) / "root"))
+            try:
+                db.add_installed("bar", "2.0", release=1, tier="core")
+                db.mark_degraded("bar", "hook-x failed")
+                rows = db.list_installed()
+            finally:
+                db.close()
+            row = next(r for r in rows if r["name"] == "bar")
+            self.assertEqual(row["degraded"], "hook-x failed")
+
+
+if __name__ == "__main__":
+    unittest.main()