[Developer] #567 add VPD SQL execution evidence

docs/design/567-ords-vpd-sql-trace/README.md

@@ -135,3 +135,19 @@
 
 - custom VPD Filter까지 정책 함수별로 자동 trace할지는 별도 이슈로 남긴다.
 - 운영 DB에서 `ADMIN` 이외의 VPD 소유자 구조를 지원하려면 함수 owner 설정을 명시적으로 추가해야 한다.
+
+## 13. SQL_ID 실행 증적 확장 — 2026-07-01
+
+재현 SQL만으로는 “이 조건이 실제 DB cursor에 적용됐는가”를 충분히 설명하지 못한다. `/probe` 성공·0행 결과 뒤에 백오피스는 `V$SQL`에서 최근 2분 내 같은 보호 객체를 조회한 cursor를 찾아 SQL_ID와 실행 통계를 표시한다. 이어 `DBMS_XPLAN.DISPLAY_CURSOR(SQL_ID, CHILD_NUMBER, 'ALLSTATS LAST +PREDICATE +ALIAS')`의 Predicate Information을 함께 표시한다.
+
+| 화면 증적 | DB 출처 | 의미 |
+|---|---|---|
+| DB가 기록한 원문 SQL | `V$SQL.SQL_FULLTEXT` | ORDS가 DB에 제출한 VPD 주입 전 SQL과 SQL_ID |
+| DBMS_XPLAN Predicate Information | 해당 SQL_ID/child cursor 실행계획 | DB cursor에 적용된 Access/Filter predicate |
+| 권한 조건 재현 SQL | Handler trace 또는 동일 context 정책 함수 | 사람이 WHERE 결합 형태를 읽기 위한 설명용 표현 |
+
+Oracle은 VPD의 내부 rewrite 결과를 별도 최종 SQL 문자열로 `V$SQL`에 보관하지 않는다. 따라서 원문 SQL과 실행계획 predicate를 함께 제시하는 것이 실제 실행에 대한 DB 증적이다. `executions`, `rows_processed`, `elapsed_time`, `buffer_gets`는 cursor 누적값이며 단일 HTTP 요청만의 계측값은 아니다.
+
+최근 SQL 매칭은 대상 객체와 최근 2분 실행 시각으로 고르므로, 같은 객체를 동시에 호출하는 운영 환경에서는 다른 요청 cursor가 선택될 가능성이 있다. 현재 UI는 이를 “최근 실행 증적”으로 명시한다. 요청별 완전 상관이 필요해지면 ORDS Handler에 검증 요청 ID를 주입해 고유 SQL comment/module-action으로 cursor를 추적하는 후속 작업으로 확장한다.
+
+실행 증적 연결에는 최소한 `V$SQL`과 `DBMS_XPLAN.DISPLAY_CURSOR`를 조회할 수 있는 catalog 권한이 필요하다. 해당 권한은 ORDS parsing schema 연결에서 먼저 조회하고, 사용할 수 없으면 백오피스 연결로 한 번 더 시도한다. Autonomous의 일반 `ADMIN` 계정은 `SYS.V_$SQL` 권한을 다른 계정에 위임하지 못할 수 있으므로, 이 경우에는 DBA가 [34_agent_ords_execution_evidence_grant.sql](../../sql/adb/34_agent_ords_execution_evidence_grant.sql)을 실행해야 한다. 권한이나 shared pool 보존 시간이 부족하면 권한 검증 결과를 실패시키지 않고 증적 미수집 안내만 표시한다.