Make the semantic runtime legible and CI-ready for first review

Names the public flow by its actual lazy-review behavior and applies the repository-pinned formatter so the consolidated branch passes its existing all-files hook.

Constraint: Keep internal governed_* contracts stable while making the user-facing feature and handoff intuitive.
Rejected: Rename internal APIs and symbols | compatibility risk without user-facing benefit.
Confidence: high
Scope-risk: narrow
Directive: Keep public copy aligned with candidate-before-review behavior and verified dialect limits.
Tested: 355 pytest cases; Ruff; mypy 97 files; Black 129 files; offline quickstart; Markdown links; formatting AST equality.
Not-tested: Live Discord transport and unverified remote dialect execution.

Author: o2mandoo

README.md

@@ -21,9 +21,9 @@
 > *separate* set of definitions per team → it answers questions over an
 > incomplete database → it remembers every definition and conversation.
 
-연결된 DB에 **governed semantic mode**가 활성화되면 모델은 SQL을 작성하지 않는다.
-모델은 사람이 검토한 지표·분류·필터 후보만 고르고, 결정론적 코드가 검증된 SQL을
-컴파일한다.
+연결된 DB에 **업무 의미 검토형 질의**가 활성화되면 모델은 SQL을 작성하지 않는다.
+모델은 서버가 질문별로 제한한 후보만 고르고, 실행에 필요한 불확실한 업무 의미를
+사람이 확인한 뒤 결정론적 코드가 검증된 SQL을 컴파일한다.
 
 👉 **프로젝트 전체 그림(단일 SSOT)**: [`docs/PROJECT.md`](docs/PROJECT.md) · **컨트리뷰터 한눈 가이드**: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)
 
@@ -41,7 +41,7 @@ interface, not the identity** — Slack/Web are adapters on the same core.
 | **Candidate** | 모델이나 UI가 고를 수 있도록 서버가 질문별로 제한한 지표·분류·필터·기간 후보 |
 | **Human review** | 불확실한 업무 의미나 데이터 공개 범위를 사람이 명시적으로 승인·거절하는 단계 |
 | **Typed plan** | SQL 문자열 대신 metric, aggregate, group-by, filter, date 범위를 구조화한 검증 대상 |
-| **Governed mode** | semantic catalog가 활성화되어 모델의 `run_sql` 접근을 제거하고 `semantic_query`만 허용하는 모드 |
+| **업무 의미 검토형 질의** | 서버가 질문별 후보를 제한하고, 불확실한 업무 의미는 실행 전에 사람이 확인하며, 모델 대신 서버의 `semantic_query`가 SQL을 만드는 질의 방식 |
 | **Fail-closed** | 의미·권한·join·dialect를 확신할 수 없을 때 추측하거나 raw SQL로 우회하지 않고 질문 또는 차단으로 끝내는 동작 |
 
 ---
@@ -130,12 +130,12 @@ does not provide a meaningful semantic-query experience.
 The bot exits loudly if `DISCORD_BOT_TOKEN` is unset. Full setup and hosting:
 [`docs/DEPLOY.md`](docs/DEPLOY.md). Copy [`.env.example`](.env.example) to start.
 
-### 앱에 내장하기: SQL 없는 공개 API
+### 앱에 내장하기: 모델이 SQL을 작성하지 않는 공개 API
 
 Discord 외의 앱은 `Lang2SQLRuntime` 공개 API를 사용할 수 있다. 흐름은
 `connect → candidates → human feedback → typed plan → execute`다. 호스트와 모델은
 SQL 문자열을 만들거나 받지 않으며, 사람의 검토 선택과 서버가 검증한 typed plan만
-실행 경계로 넘는다. 현재 governed 실행은 **기존 파일을 read-only로 연 SQLite와
+실행 경계로 넘는다. 현재 검토 기반 실행은 **기존 파일을 read-only로 연 SQLite와
 DuckDB**에 한정한다. 정확한 DTO, 검토 루프, bound `EQ`/`IN` 필터와 native `DATE`
 `[start, end)` 기간창 예제는 [`docs/LIBRARY_API.md`](docs/LIBRARY_API.md)를 따른다.
 DB 준비부터 결과 출력까지 한 번에 확인하려면 다음 예제를 실행한다.
@@ -144,18 +144,18 @@ DB 준비부터 결과 출력까지 한 번에 확인하려면 다음 예제를
 uv run python examples/semantic_runtime_quickstart.py
 ```
 
-### Governed semantic mode (semantic first-connect)
+### 업무 의미 검토형 질의
 
 `/setup` now performs a PII-safe catalog scan immediately after connecting.
 Physical PK/FK facts are accepted automatically, while numeric business metrics
-are reviewed only when a real question needs them. In governed mode the model
-cannot call `run_sql`; it selects allowlisted IDs, copies the relevant question
-phrases, declares the requested aggregate and unresolved obligations, then a
-deterministic compiler builds SQL. Phrase-to-column-to-aggregate bindings are
-persisted after review, so SUM and AVG over one physical column do not overwrite
-each other.
-
-`/setup`이 catalog를 정상 활성화하면 해당 연결은 governed mode로 전환된다.
+are reviewed only when a real question needs them. In this reviewed-query mode,
+the model cannot call `run_sql`; it selects allowlisted IDs and copies relevant
+phrases from the question, declares the requested aggregate and unresolved
+obligations, then a deterministic compiler builds SQL.
+Phrase-to-column-to-aggregate bindings are persisted after review, so SUM and
+AVG over one physical column do not overwrite each other.
+
+`/setup`이 catalog를 정상 활성화하면 해당 연결은 업무 의미 검토형 질의 모드로 전환된다.
 이 모드에서는 `run_sql`이 모델 도구 목록에서 제거되고 `semantic_query`만 서버 검증을
 거쳐 SQL을 컴파일한다. catalog가 손상되더라도 legacy raw SQL 경로로 되돌아가지 않고
 연결을 차단한다.
@@ -173,7 +173,7 @@ dimension phrase when requested → the immutable original question resumes
 without a second LLM parse. Destructive or disclosure actions use warning and
 confirmation steps; metric/dimension mapping and dimension release bind the confirmation
 to the same administrator and exact payload. See
-[`docs/SEMANTIC_FIRST_CONNECT.md`](docs/SEMANTIC_FIRST_CONNECT.md) for the exact
+[`docs/REVIEWED_SEMANTIC_QUERY.md`](docs/REVIEWED_SEMANTIC_QUERY.md) for the exact
 supported scope and fail-closed boundaries.
 
 Guild queries are admin-only by default. Non-admin members can query only in
@@ -191,12 +191,13 @@ suppression rules are not a substitute for database row/column authorization.
 - Safety pipeline with the V1 layers (whitelist + timeout), gating every query.
 - Legacy raw mode includes `run_sql`, schema exploration/enrichment, semantic
   term, ingestion, memory, and clarification tools.
-- Governed mode replaces the raw query/exploration surface with
-  `semantic_query`, blocks sample-based enrichment, and keeps SQL in audit only.
+- 업무 의미 검토형 질의 모드는 raw query/exploration surface를
+  `semantic_query`로 교체하고, sample-based enrichment를 차단하며, SQL은
+  audit에만 남긴다.
 - Memory service (in-memory store + inject-all recall + manual `/remember`).
 - Discord frontend (bot, commands, session router, render).
 - Encrypted-at-rest secrets (Fernet) and SQLite-backed persistence.
-- PII-safe first-connect catalog, lazy metric review, and a typed semantic query
+- PII-safe initial catalog, lazy metric review, and a typed semantic query
   path for aggregate/group-by queries over declared many-to-one FK paths.
 - Private-by-default aggregate disclosure: fewer than five contributing rows
   blocks `SUM`/`AVG`/source-record `COUNT`, while `MIN`/`MAX` require an explicit
@@ -219,9 +220,9 @@ suppression rules are not a substitute for database row/column authorization.
   match, free search), timestamp/relative/fiscal/cohort time, unit conversion,
   derived formulas, composite joins, and fan-out joins fail closed rather than
   being guessed or dropped.
-- Claim universal dialect parity: current public governed-execution evidence
+- Claim universal dialect parity: current public reviewed-execution evidence
   covers existing file-backed SQLite and DuckDB only. Connector availability and
-  verified governed execution are reported separately; unverified remote
+  verified reviewed execution are reported separately; unverified remote
   dialects fail closed.
 
 The cross-domain benchmark currently contains 28 cases over 21 public SQLite

docs/ARCHITECTURE.md

@@ -4,8 +4,8 @@
 
 > **두 질의 모드를 구분해서 읽어 주세요.** semantic catalog가 없는 연결은 아래의
 > legacy `run_sql` 경로를 사용한다. `/setup`으로 catalog가 활성화된 연결은 모델에서
-> `run_sql`을 제거하고, [`SEMANTIC_FIRST_CONNECT.md`](./SEMANTIC_FIRST_CONNECT.md)의
-> governed 경로를 사용한다. 임베딩 애플리케이션은 SQL 없는
+> `run_sql`을 제거하고, [`업무 의미 검토형 질의`](./REVIEWED_SEMANTIC_QUERY.md)의
+> 검토 기반 경로를 사용한다. 임베딩 애플리케이션은 모델이 SQL을 작성하지 않는
 > [`Lang2SQLRuntime`](./LIBRARY_API.md)을 사용할 수 있다.
 
 ---
@@ -46,7 +46,7 @@
 
 핵심 원칙: **로직은 포트(추상)에만 의존, 어댑터(구체)는 가장자리에만**. 그래서 새 LLM·새 DB·새 frontend를 *기존 코드 안 건드리고* 끼울 수 있습니다.
 
-### Governed semantic 질의 경로
+### 업무 의미 검토형 질의 경로
 
 ```text
 Discord 또는 공개 API
@@ -97,7 +97,7 @@ typed blocker로 끝난다.
 
 ### `src/lang2sql/semantic/` — 업무 의미, 검토, 계획, 실행 정책 (★④)
 - [`catalog.py`](../src/lang2sql/semantic/catalog.py) — 연결별 물리 사실과 검토된 업무 의미
-- [`onboarding.py`](../src/lang2sql/semantic/onboarding.py) — PII-safe metadata-only first-connect scan
+- [`onboarding.py`](../src/lang2sql/semantic/onboarding.py) — PII-safe metadata-only 초기 연결 scan
 - [`shortlist.py`](../src/lang2sql/semantic/shortlist.py) — 질문별 bounded candidate 생성
 - [`plan.py`](../src/lang2sql/semantic/plan.py) — SQL 없는 semantic plan IR
 - [`compiler.py`](../src/lang2sql/semantic/compiler.py) — 검증된 plan의 결정론적 SQL 컴파일
@@ -125,7 +125,7 @@ typed blocker로 끝난다.
 ### `src/lang2sql/tools/` — 에이전트가 부르는 capability
 대표 도구는 모두 ctx-aware, async다. 연결 모드에 따라 질의 도구가 달라진다.
 - [`run_sql.py`](../src/lang2sql/tools/run_sql.py) — catalog가 없는 legacy 연결에서만 safety 통과 후 explorer로 실행
-- [`semantic_query.py`](../src/lang2sql/tools/semantic_query.py) — governed 연결에서 typed slots만 받고 서버가 SQL을 컴파일
+- [`semantic_query.py`](../src/lang2sql/tools/semantic_query.py) — 업무 의미 검토형 질의 연결에서 typed slots만 받고 서버가 SQL을 컴파일
 - [`explore_schema.py`](../src/lang2sql/tools/explore_schema.py) — 테이블/컬럼 introspection
 - [`enrich_schema.py`](../src/lang2sql/tools/enrich_schema.py) — LLM으로 컬럼 메타데이터 자동 보강
 - [`semantic_federation.py`](../src/lang2sql/tools/semantic_federation.py) — `term_custom`: guild/channel/member 계층 용어 사전 (KV 기반, narrow→wide lookup)
@@ -165,7 +165,7 @@ governed dialect는 기존 파일 기반 SQLite와 DuckDB뿐이며, 나머지는
 
 ## 4. 한 메시지의 lifecycle (디스코드 멘션 한 번 따라가기)
 
-### Governed mode: catalog가 있는 연결
+### 업무 의미 검토형 질의 모드: catalog가 있는 연결
 
 ```text
 1. 사용자가 자연어 질문을 보낸다.
@@ -178,7 +178,7 @@ governed dialect는 기존 파일 기반 SQLite와 DuckDB뿐이며, 나머지는
 8. safety, contributor 보호, 공개 정책, audit와 catalog stamp가 모두 통과해야 결과를 표시한다.
 ```
 
-정확한 Discord 검토 흐름은 [`SEMANTIC_FIRST_CONNECT.md`](./SEMANTIC_FIRST_CONNECT.md),
+정확한 Discord 검토 흐름은 [`REVIEWED_SEMANTIC_QUERY.md`](./REVIEWED_SEMANTIC_QUERY.md),
 다른 애플리케이션의 공개 DTO 흐름은 [`LIBRARY_API.md`](./LIBRARY_API.md)를 따른다.
 
 ### Legacy mode: catalog가 없는 연결

docs/LIBRARY_API.md

@@ -1,4 +1,4 @@
-# SQL 없는 임베딩 API
+# 모델이 SQL을 작성하지 않는 임베딩 API
 
 `Lang2SQLRuntime`은 새 애플리케이션이 내부 semantic service나 SQL 객체를 직접
 다루지 않게 하는 비동기 facade다. 공개 흐름은 다음 다섯 단계다.

docs/SEMANTIC_FIRST_CONNECT.md docs/REVIEWED_SEMANTIC_QUERY.mddocs/SEMANTIC_FIRST_CONNECT.md renamed to docs/REVIEWED_SEMANTIC_QUERY.md

@@ -1,10 +1,11 @@
-# Semantic first-connect
+# 업무 의미 검토형 질의
 
-이 브랜치는 `semantic-data-context`의 큰 Semantic Pack/Registry/UI를 Lang2SQL에
+이 기능은 `semantic-data-context`의 큰 Semantic Pack/Registry/UI를 Lang2SQL에
 그대로 복사하지 않는다. 혼탄 시스템에서 유효했던 원칙을 Lang2SQL의 기존 도구
 경계에 맞춘다.
 
-> 모델은 SQL을 쓰지 않고 검토 가능한 typed value만 고른다. SQL은 코드가 만든다.
+> 서버는 질문별 후보를 제한하고 모델은 그 후보를 조립한다. 실행에 필요한
+> 불확실한 업무 의미는 사람이 확인하며, SQL은 서버 코드가 결정론적으로 만든다.
 
 ## 사용 흐름
 
@@ -33,13 +34,13 @@
 관리자가 다른 사용자의 review를 승인하면 연결만 저장된다. 관리자 채널에서 타
 사용자의 DB 결과를 실행하거나 표시하지 않으며, 원 요청자가 다시 질문해야 한다.
 
-## 기존 first-connect와 다른 점
+## 기존 초기 연결 방식과 다른 점
 
-| 이전 방식 | 이 브랜치 |
+| 이전 방식 | 업무 의미 검토형 질의 |
 |---|---|
 | 모든 table/column/card 사전 검토 | 물리 catalog 사실은 자동 등록 |
 | 작은 DB도 수십 개 업무 결정 | 연결 시 업무 결정 0개; 질문 시 필요한 연결만 검토 |
-| `/enrich`가 distinct 샘플을 LLM에 전송 | first-connect는 raw 값을 후보 생성에 사용하지 않음 |
+| `/enrich`가 distinct 샘플을 LLM에 전송 | 초기 연결 시 raw 값을 후보 생성에 사용하지 않음 |
 | LLM이 `run_sql(sql=...)` 작성 | LLM은 typed ID·질문 표현·집계·미지원 의무만 조립 |
 | 전체 pack 승인 후 사용 | 현재 질문 dependency만 확인 |
 | 모델 SQL이 join을 자유롭게 선택 | declared FK의 유일한 child-to-parent path만 허용 |
@@ -59,7 +60,7 @@
 
 ## 공개 라이브러리 경계
 
-Discord가 아닌 호스트는 SQL 없는 `Lang2SQLRuntime`을 사용한다.
+Discord가 아닌 호스트는 모델이 SQL을 작성하지 않는 `Lang2SQLRuntime`을 사용한다.
 `connect → candidates → human feedback → typed plan → execute` 순서를 지키며,
 호스트/모델은 SQL을 주고받지 않는다. `connect`는 메타데이터만 읽고, `candidates`는
 질문에 맞춘 bounded ID와 타입만 준다. 사람이 `ReviewRequest.allowed_choices`에서
@@ -69,7 +70,7 @@ Discord가 아닌 호스트는 SQL 없는 `Lang2SQLRuntime`을 사용한다.
 typed draft의 predicate는 명시적 AND, exact `EQ` 또는 값 최대 20개의 `IN`만
 허용하며 모든 값은 bound parameter가 된다. 기간은 native `DATE` 차원의 ISO date
 `[start, end)` 창만 받는다. 기존 파일을 read-only로 연 SQLite와 DuckDB만
-governed 실행을 지원한다. 상세 DTO와 안전한 검토 루프는
+검토 기반 실행을 지원한다. 상세 DTO와 안전한 검토 루프는
 [`LIBRARY_API.md`](LIBRARY_API.md)에 있다.
 
 ## 안전 경계
@@ -135,7 +136,7 @@ privacy, row-level security 또는 사용자 권한 보장이 아니다.
 - 모든 테이블의 명시적 physical source-record `COUNT(*)` (PK 불필요)
 - categorical dimension group-by
 - declared FK를 따라가는 유일한 child → parent 1~N hop join
-- 기존 file-backed SQLite와 DuckDB의 read-only governed 실행과 결과 비교
+- 기존 file-backed SQLite와 DuckDB의 read-only 검토 기반 실행과 결과 비교
 - metadata-only 문자열 공개 후보 및 수치 지표 후보
 - 모든 비차단 dimension의 metadata-only phrase mapping과 conflict 검증
 - 질문 시점의 metric/dimension review와 immutable draft 재개

docs/USAGE.md

@@ -1,6 +1,6 @@
 # Lang2SQL Discord 사용 가이드
 
-governed semantic mode에서 LLM은 SQL을 직접 쓰지 않는다. LLM은 질문을 서버가 검증할
+업무 의미 검토형 질의 모드에서 LLM은 SQL을 직접 쓰지 않는다. LLM은 질문을 서버가 검증할
 수 있는 지표·집계·분류 슬롯으로 조립하고, 서버가 확인된 값만으로 read-only SQL을
 만든다.
 
@@ -55,7 +55,7 @@ credential-bearing DSN을 채널 명령으로 직접 받는 `/connect`는 노출
 
 `/setup`이 catalog를 활성화한 뒤에는 같은 연결에서 다음 경계가 적용된다.
 
-| 기능 | Catalog 없는 legacy mode | Catalog 있는 governed mode |
+| 기능 | Catalog 없는 legacy mode | Catalog 있는 업무 의미 검토형 질의 모드 |
 |---|---|---|
 | 자연어 질의 도구 | 모델이 `run_sql`을 호출 | 모델은 `semantic_query`의 typed slot만 조립 |
 | SQL 작성 | 모델이 SQL 문자열 작성 | 서버 compiler만 검증된 SQL 작성 |
@@ -212,10 +212,11 @@ DuckDB에 한정된다. 다른 DB 커넥터는 연결 가능성과 timeout/취
 | contributor·disclosure 차단 | 결과가 너무 작거나 차원이 아직 공개되지 않음 | 데이터 공개 정책을 확인하고, 허용되는 경우에만 관리자 검토 |
 | catalog/audit 오류 | 의미 변경이나 실행을 안전하게 기록할 수 없음 | 저장소 오류를 복구한 뒤 새 plan으로 다시 시도 |
 
-차단 사유를 무시하고 `run_sql`로 우회하는 것은 governed mode의 복구 방법이 아니다.
+차단 사유를 무시하고 `run_sql`로 우회하는 것은 업무 의미 검토형 질의 모드의 복구
+방법이 아니다.
 
 ## 기타 기존 명령
 
 `/ingest`, `/confirm_ingest`, `/term_custom`, `/remember`, `/audit_me`는 기존
-기능으로 남아 있다. `/enrich`와 `/org_setup`의 raw-value sampling은 semantic
-first-connect가 활성화된 DB에서는 의도적으로 비활성화된다.
+기능으로 남아 있다. `/enrich`와 `/org_setup`의 raw-value sampling은 업무 의미
+검토형 질의가 활성화된 DB에서는 의도적으로 비활성화된다.

docs/discord_first_redesign_v4_1.md

@@ -2,7 +2,7 @@
 
 > **역사적 설계 문서**: 아래 명령 표는 2026-05 계획 당시의 walking skeleton이다.
 > 현재 실행 표면은 [`USAGE.md`](./USAGE.md)와
-> [`SEMANTIC_FIRST_CONNECT.md`](./SEMANTIC_FIRST_CONNECT.md)를 따른다. 현재
+> [`REVIEWED_SEMANTIC_QUERY.md`](./REVIEWED_SEMANTIC_QUERY.md)를 따른다. 현재
 > Discord에는 raw DSN `/connect`가 없고 `/setup`을 사용한다.
 
 > **작성일**: 2026-05-18

examples/semantic_runtime_quickstart.py

@@ -1,4 +1,4 @@
-"""Run a fully local, SQL-free Lang2SQLRuntime aggregate example.
+"""Run a local aggregate query using bounded semantic IDs and explicit review.
 
 Run from an installed package, or from this repository with:
     uv run python examples/semantic_runtime_quickstart.py

src/lang2sql/adapters/llm/openai_.py

@@ -154,9 +154,7 @@ def _decode_completion(raw: dict[str, Any]) -> Completion:
             args = (
                 decoded_args
                 if isinstance(decoded_args, dict)
-                else {
-                    "__invalid_argument_shape__": type(decoded_args).__name__
-                }
+                else {"__invalid_argument_shape__": type(decoded_args).__name__}
             )
         tool_calls.append(
             ToolCall(id=tc.get("id", ""), name=fn.get("name", ""), arguments=args)