ThothII/docs/superpowers/specs/2026-08-22-workspace-postgres-diagnostic-alignment-design.md

Workspace PostgreSQL diagnostic alignment

Context

The psd-clinical runtime reaches PostgreSQL successfully with the configured postgres_direct transport and operates in the declared datawarehouse schema. The workspace diagnostic reports connector_unavailable because its Node pg probe differs from the runtime contract in two ways:

• it always enables strict TLS, even when the installation declares no TLS CA or server name;
• it compares current_schema() with the workspace schema without first applying or otherwise validating that declared schema.

This is a diagnostic false negative. Qdrant and embedding diagnostics already match the workspace descriptor.

Decision

Align the direct PostgreSQL diagnostic with the effective runtime connection:

1. Use a plain PostgreSQL connection when no TLS configuration is declared.
2. Enable strict TLS only when a TLS CA and/or server name is explicitly bound.
3. Verify the connected database and that the authenticated role can use the schema declared by the workspace, without interpolating an untrusted SQL identifier.
4. Retain the existing sanitized connector_unavailable public error boundary; credentials, database errors, and server details must not reach the API.

The runtime connection, workspace descriptor, secrets, and deployment topology remain unchanged.

Alternatives rejected

• Switching the test installation to rest_api would test a different transport from the one used by sessions and require another credential path.
• Disabling or weakening the connector diagnostic would hide real connection, authentication, database, and schema failures.

Verification

Test-first coverage will prove:

• a direct connection without TLS bindings is created without SSL;
• explicit TLS bindings still produce strict certificate verification;
• the declared schema is checked through parameterized SQL and an inaccessible or missing schema fails closed;
• existing wrong-database, authentication, Qdrant, embedding, timeout, and secret redaction tests remain green.

After rebuilding only the test core, the live checks must show:

• workspace diagnostic activatable: true with no connector error;
• the selected model remains available;
• session creation through Django/Nginx/core returns 200, followed by deletion of the diagnostic session.

No production cutover is part of this change.