docs(rag): checkout 및 주입 세션 계약을 명시

Author: HyungminYoon1

docs/features/knowledge/component_spec.md

@@ -1,7 +1,7 @@
 # Knowledge Component Spec
 
 Status: Draft
-Verified Against: feature/mba-354 @ 6eb2e6d37e139b1f2c299326db336433e394cf30
+Verified Against: feature/mba-354 @ c3bfc3ba581d5fa0946152977d0e8d8653d21bf9
 MBA-105 구현 baseline, 운영 기본값, permission helper output, active version finalization, resource hiding matrix는 [implementation_baseline.md](implementation_baseline.md)를 따른다. Workflow RAG에서 `execution_subject`가 없는 MVP public-only runtime은 [ADR-0018](../../decisions/ADR-0018-workflow-rag-anonymous-public-only-runtime.md)을 따른다. MCP/API source connector와 incremental sync 경계는 [ADR-0020](../../decisions/ADR-0020-knowledge-mcp-incremental-sync-boundary.md)을 따른다. Direct KB와 명시 selected Collection의 Workflow runtime candidate 해석은 [ADR-0036](../../decisions/ADR-0036-knowledge-runtime-candidate-resolution.md)을 따른다. KC lifecycle, item 순서와 권한 운영 경계는 [ADR-0044](../../decisions/ADR-0044-knowledge-collection-operational-management-boundary.md)을 따른다.
 KC sync의 Gateway application, durable repository, Workflow executor와 Client polling 경계는 [ADR-0048](../../decisions/ADR-0048-knowledge-collection-sync-execution-boundary.md)을 따른다.
 Organization Detector Provider와 embedding 전 local masking Target은 [ADR-0070](../../decisions/ADR-0070-organization-detector-provider-and-pre-embedding-local-masking-boundary.md)을 따른다. 현재 component/runtime 구현 완료를 뜻하지 않는다.
@@ -762,7 +762,7 @@ tombstone cleanup은 구현 전에 별도 retention policy, audit action/reason
 - Candidate cap, fanout concurrency, timeout, partial failure behavior는 [implementation_baseline.md](implementation_baseline.md)의 baseline을 시작점으로 삼고, operations policy로 조정 가능해야 하며 운영 배포 전에 load test를 거쳐야 한다.
 - 가능한 경우 KB/version filter를 포함한 단일 vector/keyword query를 우선한다. Backend가 지원하지 못하면 concurrency와 timeout cap이 있는 bounded per-KB fanout을 사용한다.
 - Workflow의 bounded per-KB fanout은 authorized candidate와 사전 계산 query vector만 받는 application scheduler가 소유한다. 현재 baseline은 invocation당 동시 검색 최대 5개이면서 Workflow Engine 프로세스 전체 native blocking-I/O data worker도 최대 5개다. KB별 최대 10초, 최초 task 제출 전부터 시작하는 caller aggregate 30초이며 마지막 1초는 cancellation과 transaction 정리를 기다리는 데 예약한다. Queue 대기와 cleanup 대기를 aggregate deadline에 포함하고 deadline 뒤 새 KB search를 시작하지 않는다.
-- 각 시작된 KB search는 독립 SQLAlchemy session과 PostgreSQL read-only transaction을 사용하고 `organization_id + knowledge_base_id`로 KB를 조회한다. Adapter는 task 시작 시 단조시계 기준 절대 deadline을 고정하고 operation이 발생시키는 모든 SQL 직전에 cancellation과 남은 budget을 재검증한다. PostgreSQL transaction-local `statement_timeout`은 각 SQL마다 남은 정수 millisecond 이하로 축소하므로 여러 statement가 각각 최초 timeout을 새로 사용할 수 없다. Guard는 operation 뒤 connection에서 제거한 다음 transaction을 rollback하고 session을 close한다. Timeout/cancel의 DBAPI query cancel은 data worker와 분리된 프로세스 전체 최대 2개의 native control worker에서 실행해 gevent hub를 막지 않는다. 등록 해제된 callback은 실행하지 않고, 이미 실행 중인 callback은 완료된 뒤에만 해당 session을 rollback/close하여 pool로 반환된 연결에 늦은 cancel이 도달하지 않게 한다. Outer Workflow session은 native worker와 공유하지 않는다. Scheduler는 cleanup reserve 동안 종료를 기다리되 협조하지 않는 non-DB 작업 때문에 caller hard deadline을 연장하지 않는다. Hard deadline 뒤 완료된 task는 evidence를 게시할 수 없다.
+- 각 시작된 KB search는 candidate resolution과 query embedding runtime에 사용한 것과 동일한 주입 `db_session_factory`에서 독립 SQLAlchemy session을 만들고 PostgreSQL read-only transaction에서 `organization_id + knowledge_base_id`로 KB를 조회한다. 명시적으로 주입된 factory가 유효하지 않으면 전역 `SessionLocal`로 바꾸지 않고 fail-closed한다. Session factory 실행과 connection checkout은 프로세스 전체 최대 5개의 bounded native acquisition worker가 소유한다. Task cancellation/deadline 또는 acquisition slot 포화는 caller와 RAG data worker를 즉시 typed timeout으로 반환하고, 늦게 획득된 session은 acquisition worker가 rollback/close한다. 강제 thread 종료나 공용 engine의 `pool_timeout` mutation은 하지 않는다. Adapter는 task 시작 시 단조시계 기준 절대 deadline을 고정하고 operation이 발생시키는 모든 SQL 직전에 cancellation과 남은 budget을 재검증한다. PostgreSQL transaction-local `statement_timeout`은 각 SQL마다 남은 정수 millisecond 이하로 축소하므로 여러 statement가 각각 최초 timeout을 새로 사용할 수 없다. Guard는 operation 뒤 connection에서 제거한 다음 transaction을 rollback하고 session을 close한다. Timeout/cancel의 DBAPI query cancel은 data worker와 분리된 프로세스 전체 최대 2개의 native control worker에서 실행해 gevent hub를 막지 않는다. 등록 해제된 callback은 실행하지 않고, 이미 실행 중인 callback은 완료된 뒤에만 해당 session을 rollback/close하여 pool로 반환된 연결에 늦은 cancel이 도달하지 않게 한다. Outer Workflow session은 native worker와 공유하지 않는다. Scheduler는 cleanup reserve 동안 종료를 기다리되 협조하지 않는 non-DB 작업 때문에 caller hard deadline을 연장하지 않는다. Hard deadline 뒤 완료된 task는 evidence를 게시할 수 없다.
 - Fanout completion 순서는 evidence 결과를 바꾸지 않는다. Scheduler는 candidate ordinal 기준으로 결과를 반환하고, 기존 global score/source-tier 정렬, dedupe, top-k, final evidence policy와 citation projection이 최종 순서를 결정한다. `safe_no_result`는 성공 evidence를 유지할 수 있지만 `fail_node`는 남은 task를 취소하고 partial evidence를 사용하지 않는다.
 - Authorized RAG retrieval trace는 `candidate_resolution_latency_ms`, `query_embedding_latency_ms`, `retrieval_fanout_latency_ms`, `slowest_search_latency_ms`, `evidence_policy_latency_ms`만 aggregate stage latency로 허용한다. 값은 0~300,000 범위의 finite non-negative integer millisecond이며 실행하지 않은 stage는 생략한다. Candidate 0건, empty query 등 hidden/resource-hidden 상태와 구분하지 않는 `safe_no_result` 경로는 exact stage latency를 모두 생략한다. Per-KB timing, raw query/vector, hidden resource identity와 provider/DB raw error는 저장하지 않고 이 다섯 필드는 일반 Workflow result metadata, chatbot/SSE와 citation projection에 포함하지 않는다.
 - Workflow LLM node는 `context_variable`이 지정된 경우 해당 referenced variable의 정제된 값만 ephemeral retrieval query로 사용한다. 설정이 없는 legacy graph만 렌더링된 user prompt 전체를 사용하며 raw query는 durable trace, audit, log 또는 cache key에 저장하지 않는다.

docs/features/knowledge/implementation_baseline.md

@@ -46,7 +46,7 @@ MBA-105에서 구현하지 않는 범위:
 | Chunk size / overlap | child chunk 800-1,200 tokens, overlap 10-20% |
 | Parent/child hierarchy | parent 2,000-4,000 tokens, child 500-1,000 tokens |
 | Candidate caps | `max_candidate_kbs=5000`, `max_route_collections=20`, `max_retrieval_kbs=20`, `max_chunks_per_kb=8`, `max_total_chunks=50`. Collection/KB candidate cap은 임의 row를 먼저 자른 뒤 authorization하는 방식이 아니라, route/use/source ACL helper를 통과한 authorized subset에 적용한다 |
-| Fanout | 단일 filtered vector/keyword query 우선. Workflow의 per-KB fallback은 invocation당 동시 검색과 프로세스 전체 native blocking-I/O data worker를 각각 최대 5개로 제한하고 authorized candidate ordinal을 보존한다. DB cancel은 별도 bounded native control worker에서 처리한다 |
+| Fanout | 단일 filtered vector/keyword query 우선. Workflow의 per-KB fallback은 invocation당 동시 검색과 프로세스 전체 native blocking-I/O data worker를 각각 최대 5개로 제한하고 authorized candidate ordinal을 보존한다. Session factory/connection checkout도 별도 프로세스 전체 최대 5개의 bounded native acquisition worker로 제한하며 deadline 뒤 늦은 session은 획득 thread가 정리한다. DB cancel은 별도 bounded native control worker에서 처리한다 |
 | Retrieval timeout | Workflow per-KB fallback은 호출당 10s, 최초 제출 전부터 caller aggregate 30s, 마지막 1s cleanup reserve. Queue 대기와 cleanup 대기를 aggregate에 포함한다. 각 DB worker는 모든 SQL 직전에 동일한 task 절대 deadline과 cancellation을 재검증하고 statement timeout을 남은 budget으로 축소한다. Non-DB 작업이 cancellation에 협조하지 않아도 caller deadline을 연장하지 않고 late result를 폐기한다 |
 | Runtime authorization batch | `check_access_batch` 50-200 source item 후보. Batch 미지원 source는 bounded single check fallback만 허용 |
 | Runtime authorization fallback | per-source concurrency 3-5, per-call timeout 3-5s, aggregate timeout 10-20s 후보. Timeout/unknown은 private evidence fail-closed |

docs/features/knowledge/test_cases.md

@@ -1,7 +1,7 @@
 # Knowledge Test Cases
 
 Status: Draft
-Verified Against: feature/mba-354 @ 6eb2e6d37e139b1f2c299326db336433e394cf30
+Verified Against: feature/mba-354 @ c3bfc3ba581d5fa0946152977d0e8d8653d21bf9
 이 문서는 현재 RAG 동작과 목표 KB 통합 모델에 필요한 테스트 범위를 함께 기록한다. MBA-105 목표 모델 테스트는 [ADR-0017](../../decisions/ADR-0017-knowledge-integration-provisional-implementation-baseline.md)과 [implementation_baseline.md](implementation_baseline.md)의 임시 baseline을 기준으로 구현 blocker가 된다.
 KC sync의 실행·복구·snapshot·versioned finalization 검증은 [ADR-0048](../../decisions/ADR-0048-knowledge-collection-sync-execution-boundary.md)을 따른다.
 Organization Detector Provider와 embedding 전 local masking Target 테스트는 [ADR-0070](../../decisions/ADR-0070-organization-detector-provider-and-pre-embedding-local-masking-boundary.md)을 따른다. MBA-362가 runtime/persistence/provider adapter 테스트를 TDD로 구현하기 전에는 완료 증거가 아니다.
@@ -528,7 +528,7 @@ Organization Detector Provider와 embedding 전 local masking Target 테스트
 - Authorized candidate가 0개면 query embedding, fanout scheduler, child DB session과 generation provider를 모두 호출하지 않는다. Candidate가 있으면 ADR-0071의 distinct-model capability/provider attempt와 invocation-local vector를 그대로 소비하며 KB별 embedding을 다시 만들지 않는다.
 - 사전 계산 query vector를 사용하는 2개 이상 KB search는 실제 native worker에서 겹쳐 실행된다. Invocation당 동시 검색과 여러 invocation을 합친 프로세스 전체 native data worker가 모두 5개를 넘지 않아야 한다. Barrier 기반 test로 overlap을, 두 executor 동시 제출 test로 process-wide 상한을 검증하며 우연한 wall-clock 단축만 성공 기준으로 사용하지 않는다.
 - Aggregate deadline은 executor/task 제출 전에 시작한다. Queue 대기, active search, cancellation과 cleanup 대기를 포함해 caller 기준 30초를 넘기지 않고 마지막 1초에는 새 DB search를 시작하지 않는다. Running task 없이 queued task의 start budget만 부족한 경우 busy-spin 없이 timeout으로 수렴한다. Cancellation에 협조하지 않는 worker를 기다리느라 caller deadline을 연장하지 않으며 late result를 폐기하는 test를 포함한다. `gevent.Timeout` 등 `BaseException` 계열 외부 종료도 실행 중인 모든 child cancellation을 요청하고 원래 예외를 전파해야 한다.
-- 각 worker는 별도 session에서 `organization_id + knowledge_base_id` 조건과 read-only transaction을 적용하고, 단조시계 절대 deadline을 기준으로 operation의 모든 SQL 직전에 cancellation과 남은 budget을 재검증한다. Transaction-local statement timeout은 각 SQL마다 남은 budget 이하로 축소한다. 단일 timeout 안에서는 각각 성공할 두 `pg_sleep`의 합이 절대 deadline을 넘는 경우 후속 SQL이 timeout되고, 취소 뒤 다음 SQL은 DBAPI 실행 전에 차단되어야 한다. DB cancel callback은 프로세스 전체 최대 2개의 별도 native control worker에서 실행해 gevent hub를 막지 않아야 한다. Dispatch 뒤 등록 해제된 callback은 실행하지 않고 이미 실행 중인 callback은 완료 뒤에만 statement guard를 제거하고 session을 rollback/close한다. Success, empty, DB error, per-KB timeout, aggregate cancel과 rollback error 모두 close를 시도한다. Disposable PostgreSQL test는 cumulative statement timeout, `pg_sleep` cancel 뒤 rollback, connection 재사용과 timeout/guard 비누출을 확인한다.
+- 각 worker는 candidate resolution/query embedding과 동일한 주입 `db_session_factory`에서 별도 session을 만들고 `organization_id + knowledge_base_id` 조건과 read-only transaction을 적용한다. Invalid explicit factory는 전역 DB fallback 없이 차단한다. Session factory와 connection checkout은 프로세스 전체 최대 5개의 native acquisition worker로 제한한다. Pool을 소진한 PostgreSQL test에서 per-KB deadline이 공용 `pool_timeout`보다 먼저 caller를 반환하고, 늦게 획득된 session은 획득 thread가 rollback/close하며 acquisition slot과 checked-out connection이 복구되어야 한다. 단조시계 절대 deadline을 기준으로 operation의 모든 SQL 직전에 cancellation과 남은 budget을 재검증하고 transaction-local statement timeout은 각 SQL마다 남은 budget 이하로 축소한다. 단일 timeout 안에서는 각각 성공할 두 `pg_sleep`의 합이 절대 deadline을 넘는 경우 후속 SQL이 timeout되고, 취소 뒤 다음 SQL은 DBAPI 실행 전에 차단되어야 한다. DB cancel callback은 프로세스 전체 최대 2개의 별도 native control worker에서 실행해 gevent hub를 막지 않아야 한다. Dispatch 뒤 등록 해제된 callback은 실행하지 않고 이미 실행 중인 callback은 완료 뒤에만 statement guard를 제거하고 session을 rollback/close한다. Success, empty, DB error, per-KB timeout, aggregate cancel과 rollback error 모두 close를 시도한다. Disposable PostgreSQL test는 checkout deadline, cumulative statement timeout, `pg_sleep` cancel 뒤 rollback, connection 재사용과 timeout/guard 비누출을 확인한다.
 - Reverse completion, partial timeout과 mixed success에서도 candidate ordinal을 거쳐 기존 global score/source-tier 정렬, dedupe, top-k, evidence sufficiency와 citation 결과가 순차 기준 fixture와 같아야 한다. `fail_node`는 partial evidence를 사용하지 않고 남은 task에 cancellation을 요청한다.
 - RetrievalService의 sync/async exception log와 fanout error projection에는 raw query, SQL/parameter, KB/document/chunk identity, provider payload와 raw exception 문자열이 없어야 한다. `fail_node`도 실패 정책은 유지하지만 child 원문 예외 대신 고정된 safe fanout error를 반환한다.
 - 하나 이상의 authorized candidate가 retrieval에 진입한 RAG trace에는 실행된 stage의 `candidate_resolution_latency_ms`, `query_embedding_latency_ms`, `retrieval_fanout_latency_ms`, `slowest_search_latency_ms`, `evidence_policy_latency_ms`만 0~300,000 범위 integer로 남긴다. Candidate 0건 또는 empty query의 구분 불가능한 `safe_no_result`는 exact stage latency를 모두 생략한다. Unknown/negative/non-finite/bool/per-KB timing은 제거하고 일반 Workflow result metadata, chatbot/SSE와 citation에는 이 필드가 없어야 한다.