모듈 지도 — 책임, 의존 방향, 호출 관계

이 문서가 답하는 질문

• engine/src/ 아래 모듈은 몇 개이고 각자 무엇을 책임지는가?
• 의존 방향은 어디로 흐르는가? 순환은 있는가?
• 하나의 Cypher 질의는 어떤 함수들을 거쳐 지나가는가?
• Rust 코드와 SQL 코드(bootstrap.sql, access.sql)의 경계는 어디인가?

1. 사실 — 크레이트 구성

저장소에는 두 개의 Rust 크레이트가 있다. 서로 코드를 공유하지 않는다.

근거: engine/Cargo.toml:1-30, bolt/Cargo.toml:1-14.

확장 이름은 ontological이고 requires = 'vector'이므로 CREATE EXTENSION ontological CASCADE가 pgvector를 함께 설치한다 (engine/ontological.control:1-7).

ontological-bolt는 engine을 라이브러리로 링크하지 않는다. 오직 PostgreSQL 프로토콜로 og_cypher() / og_cypher_check() / og_cypher_columns() / og_cypher_stats()를 호출한다 (bolt/src/session.rs:286,295,432,447). 이것이 "Cypher는 여기서 해석되지 않는다"는 주장의 구조적 근거다 (bolt/src/main.rs:4-5).

2. 사실 — 확장 진입점

engine/src/lib.rs:21-37:

::pgrx::pg_module_magic!(name, version);

extension_sql_file!("../sql/bootstrap.sql", name = "bootstrap", bootstrap);
extension_sql_file!("../sql/access.sql", name = "access", finalize);

설치 순서는 bootstrap SQL → Rust #[pg_extern] 함수들 → access SQL이다. access.sql이 finalize인 이유는 그 안에서 Rust 함수를 참조하기 때문이다 — 예: ALTER FUNCTION og_reach(int8, int4[], "char", int4, int4) ROWS 100; (engine/sql/access.sql:197)은 og_reach가 이미 존재해야 한다.

3. 사실 — 모듈별 책임 (실측 라인 수)

4. 사실 — 의존 방향

                    ┌──────────────┐
                    │    lib.rs    │
                    └──────┬───────┘
                           │ (선언만)
   ┌─────────┬─────────┬───┴────┬─────────┬─────────┬──────────┐
   ▼         ▼         ▼        ▼         ▼         ▼          ▼
 cypher   typeql   compat   vector   interop  adapters      agent
   │         │        │        │         │        │            │
   └────┬────┴────────┴────────┴─────────┴────────┴────────────┘
        ▼
   ┌────────────────────────┐
   │  storage/  ·  catalog/ │   ← 도메인 코어
   └────────┬───────────────┘
            ▼
      ┌───────────────┐
      │ spiu.rs · id.rs · stats.rs │   ← 무의존 유틸
      └───────────────┘

규칙: 위에서 아래로만 부른다. 실측된 예외는 아래 두 가지다.

1. catalog/labeling.rs:175 → crate::cypher::views::drop_all_views() — catalog가 cypher를 역참조한다. 스키마가 바뀌면 생성된 뷰가 무효해지기 때문.
2. catalog/types.rs:564-566 → crate::cypher::compile::sql_str(prop) — SQL 문자열 리터럴 이스케이프 유틸을 cypher 모듈에서 빌려 쓴다.

이 둘은 순환 의존이며 개선 대상이다 → 11_improvements_code.md CODE-12.

typeql은 cypher를 부르지 않는다. 반대도 마찬가지다. 두 언어는 catalog + storage 위에서만 만난다 (engine/src/typeql/mod.rs:1-6).

5. 사실 — 한 질의의 호출 경로

5.1 읽기 Cypher

og_cypher(graph, query, params)                 cypher/mod.rs:84
 └─ stats::reset()                              cypher/mod.rs:92
 └─ parser::parse(query)                        cypher/parser.rs:22
     └─ Lexer::tokenize()                       cypher/lexer.rs:81
 └─ is_write(&ast) == false                     cypher/mod.rs:33
 └─ run_read()                                  cypher/mod.rs:137
     └─ compile_cached()                        cypher/mod.rs:47
         └─ [PLAN_CACHE 히트 시 즉시 반환]       cypher/mod.rs:49
         └─ Compiler::compile_read(&ast)        cypher/compile.rs:351
             ├─ compile_match → compile_pattern → bind_node / join_rel
             │   ├─ types::resolve_label_set()  catalog/types.rs:152
             │   │   └─ labeling::og_is_subtype() catalog/labeling.rs:233
             │   └─ views::ensure_view(tid)     cypher/views.rs:93   ← DDL 발생 가능
             └─ build_select → build_core       cypher/compile.rs:602,477
     └─ exec_json(sql, params)                  cypher/mod.rs:145
         └─ client.select(sql, None, &[JsonB(params)])   ← $1 로 바인딩
 └─ audit()                                     cypher/mod.rs:122

핵심: 읽기는 SQL 문장 하나로 끝난다. 조인 순서·스캔 방식·병렬성은 전부 PostgreSQL 플래너가 정한다 (cypher/compile.rs:3-7).

5.2 쓰기 Cypher

og_cypher(...)                                  cypher/mod.rs:84
 └─ is_write(&ast) == true
 └─ run_write()                                 cypher/mod.rs:158
     ├─ [DDL 절이면] compat::ddl::run()          compat/ddl.rs:18
     ├─ 1단계: 선행 MATCH/UNWIND만 컴파일해 바인딩 행 생성   cypher/mod.rs:171-236
     │    └─ Compiler::build_select_pub()       cypher/compile.rs:310
     ├─ rename_label() — REMOVE n:Old SET n:New 특례    cypher/mod.rs:517
     └─ 2단계: 바인딩 행마다 쓰기 절 적용         cypher/mod.rs:251-321
          ├─ create_pattern → storage::create_node_inner / create_edge_inner
          ├─ merge_pattern  → SELECT 후 없으면 create        cypher/mod.rs:451
          ├─ apply_set      → storage::set_node_props_inner  cypher/mod.rs:576
          └─ Delete         → storage::delete_edge_inner / delete_node_inner
     └─ fold_aggregates()  — RETURN count(*) 접기  cypher/mod.rs:341

핵심: 쓰기는 SQL 문장 하나가 아니다. 행마다 Rust가 SPI 호출을 반복한다. 이유는 02_write_path.md 참조.

5.3 TypeQL

og_typeql(graph, query)                         typeql/mod.rs:49
 └─ run_script → run_query                      typeql/mod.rs:134,143
     ├─ [define] schema::run_define()  (5 패스)  typeql/schema.rs:56
     ├─ [읽기] compile_read()                    typeql/mod.rs:247
     │    ├─ compile_match()                     typeql/mod.rs:186
     │    │    └─ compile::components(&pats)     typeql/compile.rs:735  ← 연결 성분 분해
     │    │    └─ Compiler::compile_patterns()   typeql/compile.rs:169
     │    └─ 스테이지마다 서브쿼리로 감싸기        typeql/mod.rs:251-354
     └─ [쓰기] run_write_pipeline()              typeql/mod.rs:447

6. 사실 — Rust와 SQL의 경계

access.sql에도 예외가 둘 있다. og_node_json / og_edge_json / og_capture_history는 LANGUAGE plpgsql이다 (access.sql:209,238,274). 동적 EXECUTE format(...)으로 스토리지 테이블 이름을 런타임에 결정해야 하므로 SQL 함수로 쓸 수 없다. 그 대가로 이들은 인라인되지 않는다 — 컴파일 시점에 타입을 모르는 프로퍼티 접근이 og_node_json(n.id)->>'x' 로 컴파일되면 최적화 장벽이 된다 (cypher/compile.rs:991).

7. 결정 — 왜 이 배치인가

금지 / 필수

• 금지: catalog/나 storage/에서 cypher::/typeql::를 부르는 새 코드를 추가하는 것. 현재 2곳(labeling.rs:175, types.rs:564)은 알려진 부채다.
• 금지: bolt/에서 Cypher를 파싱하거나 쓰기 여부를 키워드로 판정하는 것. 반드시 og_cypher_check()에 물어본다 (bolt/src/session.rs:438-461).
• 필수: 새 공개 SQL 함수를 추가할 때는 해당 모듈의 #[pg_extern]으로 선언하고, 순수 SQL로 표현 가능하면 access.sql에 LANGUAGE sql로 쓴다.
• 필수: 새 사용자 데이터 테이블을 bootstrap.sql에 추가하면 반드시 pg_catalog.pg_extension_config_dump()에 등록한다 (bootstrap.sql:390-427). 등록하지 않으면 pg_dump가 내용을 건너뛰고 조용히 빈 그래프로 복원된다.