fix: QA P1 findings on auto-schema-upgrade (v4.4.3)

Addresses the three P1 findings from QA baseline review of a8a0ce2:

1. uninstall.php: delete psa_db_version option on plugin removal so no
   orphaned data is left behind — satisfies AGENT-OPERATING-STANDARD
   teardown/uninstall DoD.

2. Extract psa_upgrade_needed( $stored, $current ) as a pure function and
   add tests/unit/UpgradeTest.php covering fresh-install, same-version,
   future-version, and older-version scenarios. The impure wrapper
   psa_maybe_run_upgrades() now delegates the decision to the pure helper.

3. Document the psa_db_version option and the admin_init-triggered
   upgrade mechanism in ARCHITECTURE.md (Options section), including
   why admin_init, downgrade behavior, cleanup, and testability.

No behavioral change for end users — same upgrade semantics, just
testable and documented, with proper teardown.

Agent-Session: cowork-qa-p1-fixes-20260414

peptide-search-ai.php

@@ -52,6 +52,19 @@ function psa_admin_init() {
 }
 add_action( 'admin_init', 'psa_admin_init' );
 
+/**
+ * Decide whether a schema upgrade is needed given a stored version and the
+ * currently-installed code version. Pure function — no side effects, testable
+ * in isolation.
+ *
+ * @param string $stored_version  Version string recorded in psa_db_version.
+ * @param string $current_version Version string of the running code.
+ * @return bool True if an upgrade must run; false otherwise.
+ */
+function psa_upgrade_needed( $stored_version, $current_version ) {
+	return version_compare( $stored_version, $current_version, '<' );
+}
+
 /**
  * Run database upgrades when the installed code version is newer than the
  * stored `psa_db_version` option. Keeps users from needing to
@@ -60,11 +73,14 @@ add_action( 'admin_init', 'psa_admin_init' );
  * Triggered on admin_init so dbDelta runs once per upgrade, not on every
  * frontend page load.
  *
+ * Side effects: reads psa_db_version option; on upgrade, calls
+ * PSA_Cost_Tracker::create_table() and writes psa_db_version.
+ *
  * @return void
  */
 function psa_maybe_run_upgrades() {
 	$stored = get_option( 'psa_db_version', '0.0.0' );
-	if ( version_compare( $stored, PSA_VERSION, '>=' ) ) {
+	if ( ! psa_upgrade_needed( $stored, PSA_VERSION ) ) {
 		return;
 	}