pythograph 0.1.0__tar.gz

pythograph-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# 가상 환경과 도구 캐시
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+build/
+dist/
+*.egg-info/
+
+# 비밀값과 로컬 설정은 커밋하지 않는다
+.env
+.env.*
+
+# fixture 실행 부산물(오라클은 스크래치 가상 환경에서 fixture를 import한다)
+db.sqlite3
+
+# GLM 리뷰 패킷 임시 파일
+.review-tmp/

pythograph-0.1.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+이 프로젝트의 주요 변경 사항을 기록한다.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-30
+
+### Changed
+
+- Phase 6 종료 조건 기록(`experiments/e2e/recorded/`)의 Android 문서를 kartograph `4c09d91`(#122 Retrofit route-call usr·상속
+  인터페이스 호출 간선, #123 Retrofit baseUrl 결합)로 다시 기록하고, route 선택에 `POST /api/checkout/`을 더해 trace를 다시
+  만들었다. Android `OrdersService.getOrder` → `OrderRepository.load`(1) → `OrderViewModel.refresh`(2)와 `OrdersService.checkout`
+  → `CheckoutRepository.submit`(1) → `CheckoutViewModel.pay`(2)가 체인에 붙고, `unattributed-calls-omitted` gap(route 3개·
+  relation 2개)이 사라졌다. **Android 기록은 kartograph `4c09d91` 이상에 의존한다** — 그 전 판으로 다시 기록하면
+  `tests/test_e2e_trace.py`가 실패한다. iOS 기록(cartograph 0.22.0)과 서버 문서는 바뀌지 않았다.
+- `experiments/e2e/record_clients.py --client ios|android`: 한 클라이언트만 다시 기록한다(생략하면 둘 다).
+
+### Added
+
+- 릴리스 준비(게시는 아직 하지 않음): `.github/workflows/release.yml` 초안(`v*` 태그 push → ubuntu·macOS × Python 3.10·3.13 검증 →
+  태그·버전 대조와 sdist·wheel 빌드, 깨끗한 가상 환경의 wheel 설치·`--version`·CLI 계약 확인 → 환경 `pypi`에서 PyPI Trusted
+  Publishing 게시, 액션은 커밋 SHA 고정)과 관리자가 직접 할 절차를 적은 `RELEASING.md`.
+- `DOGFOOD.md`: 공개 앱 네 개(Django-Styleguide-Example, babybuddy, microblog, netbox)의 route 오라클 정밀도·재현율,
+  schemagraph·isthmus 조인율, 핸들러 → relation-use 도달률, 미해석 호출 분포, 실행 시간·메모리와 고친 문제.
+
+- `pythograph graph`·`reach`·`impact`: 표준 라이브러리 `ast`로 만든 파이썬 호출 그래프(`pythograph-graph` v1 스냅샷)와
+  isthmus `language-traversal` v1 순회 문서(`docs/GRAPH.md`). 정점은 모듈·함수·메서드·클래스·중첩 정의와 routes가 등록
+  클래스 기준으로 내는 상속 멤버 핸들러(`<클래스>.<멤버>`)이고, id는 routes·schema `symbol.usr`와 같다. 간선은 import(절대·상대·
+  별칭·`__init__` 재수출·`*`)·모듈 속성·생성자(`__init__`)·C3 MRO로 푼 `self`·`super()`·주석 수신자·property·장식자·콜백·참조·
+  클래스 속성·상속이며 근거 등급 `direct`와 하위 클래스 재정의 `candidate`를 싣는다(`bound`는 아직 없다 — `--dispatch bound`는
+  direct 그래프다). 대상을 모르는 호출은 추측하지 않고 이유별로 세어 `unresolvedCalls`로 낸다(타입 모르는 수신자는 프로젝트가
+  그 이름을 정의·대입하지 않을 때만 외부로 확정).
+- 프레임워크 디스패치: Django 5.2.17·DRF 3.18.1·Flask 3.1.3 설치본 소스를 ast로 읽어 만든 훅 표
+  (`experiments/graph/dump_framework_hooks.py` → `graph/framework_table.py`)로 `as_view()` 디스패치 경로와 프레임워크 구현
+  (`ModelViewSet.retrieve` → `get_queryset`, `ModelSerializer.save` → `create`)이 부르는 프로젝트 훅을 잇는다. 프레임워크가 클래스
+  속성으로 만드는 객체는 `framework-callback` 미해석으로 센다.
+- 순회: `--dispatch direct|bound|candidates`, `--max-depth`, `--max-reached`, `--roots-from <file|->`(JSON 배열·bridge-facts),
+  `--revision`, `--generated-at`. 다중 root 단일 패스(root별 오라클과 무작위 그래프 비교 테스트), root별 하한 `evidence`,
+  `rootsTruncated`, 정점이 아닌 root는 문서를 쓰고 64(root-not-found), 제어 문자 id는 64. `revision`은 작업 트리가 깨끗할 때의
+  git HEAD(또는 `--revision`), `graphRevision`은 그래프 내용 SHA-256.
+- `exchange/order.py`: registration-order `order` 검증기. isthmus `f9dcd1d`의 `http-dispatch` 벡터를 벤더링하고
+  `dispatch.validate` 18건과 routes 출력 golden에 적용한다(생산자 사례 78건 100%).
+- Phase 6 종료 조건 fixture(`fixtures/e2e/shop-api`, `experiments/e2e/`): 합성 Django+DRF 서버, Django DDL의 schemagraph 카탈로그,
+  합성 iOS(cartograph)·Android(kartograph) 클라이언트를 isthmus `trace`(workspace)로 잇고 세 질문(API → DB·DB 의존자, API →
+  클라이언트 호출부 → 영향 심볼, 테이블 → API → 클라이언트)의 기대 경로 일치를 기록한다. `tests/test_e2e_trace.py`가 오프라인으로
+  다시 확인한다.
+
+- 저장소 골격: `pyproject.toml`(hatchling, Python 3.10 이상, 런타임 의존성 없음, 콘솔 스크립트 `pythograph`),
+  `uv tool install`·`pipx install` 배포, dev 도구(uv·pytest·pytest-cov·ruff·mypy), GitHub Actions CI(ubuntu·macOS,
+  Python 3.10·3.13, lint·format·typecheck·테스트·커버리지 90%·CLI 계약·wheel 설치 계약).
+- CLI: `pythograph --version`, `help`, 종료 코드 계약 0/2/64(1은 예약, 예기치 못한 내부 오류도 2),
+  키 정렬 결정적 JSON, `--generated-at`으로 바이트 단위 재현.
+- `pythograph routes --role server`: Django URLconf(설정 모듈·`ROOT_URLCONF`·`include`·변환기·`re_path` 정규식 구문
+  트리 변환·함수/클래스 뷰 method), Django REST framework(`SimpleRouter`·`DefaultRouter`·`@action`·형식 접미사·
+  `api_view`·generic view·viewset), Flask/Werkzeug(앱 팩토리·블루프린트 중첩·`add_url_rule`·`MethodView`·변환기·
+  `strict_slashes`·`merge_slashes`)를 isthmus http `route-decl`(platform `python`)로 낸다. Django는
+  `dispatch: "registration-order"`와 `order`, Flask는 `specificity`다. 규칙은 Django 5.2.17·DRF 3.18.1·Flask 3.1.3·
+  Werkzeug 3.1.9 소스로 확인했다(`docs/HTTP-ROUTES.md`).
+- 심볼 id 규칙 `<프로젝트 상대 경로>#<어휘적 점 경로>`(클래스 핸들러는 등록 클래스 기준). 다음 단계 호출 그래프가
+  같은 id를 쓴다.
+- `--dispatch specificity`: registration-order를 아직 받지 않는 isthmus용 근사(거짓 match만 가능, 거짓 error 없음).
+- isthmus 공유 적합성 벡터를 `78d3dee`에서 벤더링하고 `conformance.lock`으로 고정했다. 해당 생산자 사례 60건을
+  100% 통과한다.
+- `pythograph schema`: Django 모델(추상·프록시·다중 테이블 상속, `INSTALLED_APPS`·`AppConfig` 앱 라벨, 백엔드별
+  `truncate_name` 절단, M2M 중간 테이블, django.contrib 모델)과 QuerySet 사용(조회식 조인·역관계·관계 매니저·
+  `values`·`F`·`Q`·집계·`raw()`·`RawSQL`·`extra(tables=)`), SQLAlchemy 2.x·Flask-SQLAlchemy 3 매핑(Declarative·
+  믹스인·상속·스키마·Core `Table`·자동 snake_case 이름, 버전 미상이면 2·3 규칙이 같은 이름만)과 질의
+  (`select`·`session.query`·`Model.query`·`filter_by`·`text()`), SQL 텍스트(가족 공유 추출기 포트와 공유 벡터)를
+  isthmus persistence `relation-use`(platform `python`)로 낸다. 확정하지 못한 이름은 dynamic 사실과 한계다. 테스트·
+  마이그레이션은 기본으로 읽지 않는다. 규칙은 Django 5.2.17·SQLAlchemy 2.0.54·Flask-SQLAlchemy 3.1.1(2.5.1 비교)
+  소스로 확인했다(`docs/PERSISTENCE.md`).
+- persistence 명명 벡터(`fixtures/persistence-naming/`)와 오라클(`experiments/persistence/`): 실제 ORM(Django 백엔드 4개,
+  SQLAlchemy, Flask-SQLAlchemy) 이름과 100% 일치, 기록을 오프라인 테스트로 다시 확인한다. 사용 fixture 두 개의 ORM DDL로
+  schemagraph·isthmus 종단 조인에서 error 0을 확인했다.
+- 합성 fixture(`fixtures/django/drf-shop`, `fixtures/flask/blog-app`)와 오라클 하네스(`experiments/oracle/`):
+  resolver 순회·DRF 라우터·Flask `url_map` 대비 정밀도 100%, 기록을 오프라인 테스트로 다시 확인한다.
+
+### Fixed
+
+- 이름 해석: 프로젝트 모듈의 `from x import *`를 패키지 `__init__`을 거쳐 거듭 따라가고 리터럴 `__all__`·밑줄 규칙을 지킨다.
+  외부·`__all__` 미확정 모듈의 `*`는 가림(그래프 `star-import`)이다. routes·schema는 별 import를 전혀 따라가지 않았고
+  그래프는 한 단계만 따라갔다.
+- schema: `django.forms` 필드(`forms.CharField` 등)를 선언한 ModelForm·Form을 모델로 오인해 없는 테이블을 내던 문제,
+  `from app import models` 뒤 `models.Book.objects`처럼 모듈 속성으로 닿은 모델을 풀지 않던 문제(바깥 함수까지 지역에서 다시
+  묶으면 풀지 않는다), 조건부 `INSTALLED_APPS.remove(...)`가 앱 목록 전체를 불완전하게 만들던 문제(무조건 `remove`는 적용).
+- routes(Django): 맨 앞 include 문자열이 설정값(`path(settings.BASE_PATH, include(...))`)이면 하위 경로가 모두 dynamic이던
+  문제 → 그 조각을 떼고 `pathAnchor: "base"`와 `unresolved-route-prefix:`. `django.contrib.auth.views` 클래스(`LogoutView`는
+  `http_method_names`로 post만)와 `Base…View`·`ProcessFormView`·`DeletionMixin`·템플릿·날짜 믹스인을 알려진 클래스 표에
+  더했다(Django 5.2.17 설치본 조사). 호출 그래프 프레임워크 표도 같은 클래스로 다시 만들어 상속 핸들러 route usr가 그래프
+  정점이 된다. 설정 모듈을 찾지 못한 한계 문구에 `--settings` 안내를 더했다.
+- routes(Flask): 앱 팩토리 안의 import(`from app.auth import bp as auth_bp`, `from . import main`)를 따라가 `register_blueprint`
+  대상과 `url_prefix`를 푼다. import 뒤 대입·반복 변수·with 대상으로 다시 묶은 이름은 풀지 않는다.
+- `graph`: 16 Mi 문자 출력 상한을 넘을 때 "isthmus rejects" 대신 상한과 `reach`/`impact` 사용을 안내한다.
+
+### Changed
+
+- 배포 메타데이터: Python 3.10~3.13·Django·Flask·`Typing :: Typed` 분류자, Repository·Changelog URL. README의 문서 링크를
+  PyPI에서도 열리도록 절대 URL로 바꾸고, 설치 절에 PyPI 릴리스 전까지의 GitHub·wheel 설치(`uv tool install`·`pipx install`)를 적었다.
+- isthmus 공유 적합성 벡터를 `f9dcd1d`로 다시 벤더링했다(`http-dispatch.json` 추가).
+- README·`docs/HTTP-ROUTES.md`·`docs/PERSISTENCE.md`: isthmus `main`(`f9dcd1d`)이 `platform: "python"`(http
+  `registration-order`, persistence, python 순회 분석)을 받는다는 호환 정보와 호출 그래프 구현을 반영했다.

pythograph-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Coden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pythograph-0.1.0/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.5
+Name: pythograph
+Version: 0.1.0
+Summary: Static facts for Python (Django, Django REST framework, Flask, SQLAlchemy) services for the isthmus bridge-facts exchange: HTTP route declarations and persistence relation uses from the standard-library ast, without importing the analyzed project.
+Project-URL: Homepage, https://github.com/ictechgy/pythograph
+Project-URL: Repository, https://github.com/ictechgy/pythograph
+Project-URL: Issues, https://github.com/ictechgy/pythograph/issues
+Project-URL: Changelog, https://github.com/ictechgy/pythograph/blob/main/CHANGELOG.md
+Author: ictechgy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,django-rest-framework,flask,http,isthmus,persistence,routes,sqlalchemy,static-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# pythograph
+
+[한국어](https://github.com/ictechgy/pythograph/blob/main/README.ko.md)
+
+Static facts for Python services (Django, Django REST framework, Flask, SQLAlchemy), emitted in the
+[isthmus](https://github.com/ictechgy/isthmus) bridge-facts exchange format.
+
+pythograph is the Python member of a family of static-analysis CLIs (tsograph for
+TypeScript/JavaScript, cartograph for Swift, kartograph for Kotlin, dartograph for Dart, gartograph for
+Go, rustograph for Rust, schemagraph for SQL). Each tool reports only what it observes in its own language;
+isthmus joins the documents.
+
+The analyzed project is parsed with the standard-library `ast` only. It is never imported or executed,
+and pythograph has no runtime dependencies and uses no network (`graph`, `reach`, and `impact` run only the project
+root's git to read `revision`).
+
+## Status
+
+| Area | State |
+|---|---|
+| `pythograph routes --role server`: Django URLconf, Django REST framework routers and views, Flask/Werkzeug rules → `route-decl` facts | Implemented |
+| `pythograph schema`: Django models and QuerySets, SQLAlchemy 2.x / Flask-SQLAlchemy 3 mappings and queries, SQL text → persistence `relation-use` facts | Implemented |
+| `pythograph graph` / `reach` / `impact`: Python call graph → isthmus `language-traversal` v1 (evidence tiers `direct`/`candidate`, `unresolvedCalls`, Django/DRF/Flask dispatch) | Implemented |
+| Client route-calls (requests, httpx) | Planned |
+
+isthmus `main` (`f9dcd1d`) accepts `platform: "python"` http documents (including `registration-order`), persistence
+documents, and python `language-traversal` analyses (see [isthmus compatibility](#isthmus-compatibility)).
+
+## Requirements and installation
+
+- Python 3.10 or newer (Django 5.x needs 3.10+, and pythograph parses the analyzed code with the running
+  interpreter, so run it with the same or a newer Python than the project).
+
+pythograph is not on PyPI yet. Until the first release, install it from GitHub (the `main` branch, or a release tag
+such as `@v0.1.0` once it exists):
+
+```sh
+uv tool install git+https://github.com/ictechgy/pythograph
+# or
+pipx install git+https://github.com/ictechgy/pythograph
+
+pythograph --version
+```
+
+A wheel built from a checkout (`uv build`) installs the same way: `uv tool install dist/pythograph-<version>-py3-none-any.whl`
+or `pipx install dist/pythograph-<version>-py3-none-any.whl`. After the PyPI release, `uv tool install pythograph` and
+`pipx install pythograph` will work. The release steps are in [RELEASING.md](https://github.com/ictechgy/pythograph/blob/main/RELEASING.md)
+(Korean).
+
+## `pythograph routes --role server`
+
+```sh
+pythograph routes --role server --project <root> [--service <name>] [--include-tests]
+                  [--framework auto|django|flask] [--settings <module>]
+                  [--dispatch specificity] [--generated-at <timestamp>] [--format json]
+```
+
+Writes a bridge-facts v1 document to stdout: `platform: "python"`, `target: "http"`, `roles: ["server"]`,
+`dispatch`, `sourceSets`, and one `route-decl` fact per (route, HTTP method).
+
+- `--project` (required): the project root. `project` is its POSIX realpath and every `location.path` is
+  relative to it.
+- `--framework`: `auto` (default) detects Django (a `DJANGO_SETTINGS_MODULE` default in `manage.py`,
+  `wsgi.py`, or `asgi.py`, or `--settings`) and Flask (a `Flask(...)` or `Blueprint(...)` object). A project
+  with both is a usage error until you pick one.
+- `--settings`: the Django settings module when the entry files do not name it.
+- `--include-tests`: also emit routes declared in test sources (`test_*.py`, `*_test.py`, `tests.py`,
+  `conftest.py`, files under `tests/` or `test/`) with `testSource: true` and `sourceSets.tests: "included"`.
+- `--dispatch specificity`: declare `specificity` for a Django project and omit `order` (see
+  [Decisions](#decisions)).
+- `--generated-at`: a fixed `generatedAt` for byte-identical output.
+- Exit codes: `0` success (zero facts is still success, not proof of completeness), `2` unreadable project,
+  more than 100,000 facts, output over 16 Mi characters, or an internal error (the message states the cause
+  and a fix, never source text or absolute paths), `64` usage error. `1` is reserved.
+
+Example (synthetic, compacted; the real output is key-sorted JSON with two-space indentation):
+
+```json
+{
+  "dispatch": "registration-order",
+  "facts": [
+    {
+      "channel": "/catalog/items/{}/edit/",
+      "dynamic": false,
+      "kind": "route-decl",
+      "location": { "column": 10, "line": 20, "path": "catalog/urls.py" },
+      "method": "POST",
+      "order": { "group": "django:shop.urls", "index": 7 },
+      "paramConstraints": [{ "kind": "int", "segment": 2 }],
+      "pathAnchor": "root",
+      "symbol": { "qualifiedName": "catalog/views.py#ItemEditView.post", "usr": "catalog/views.py#ItemEditView.post" },
+      "trailingSlash": "strict"
+    }
+  ],
+  "format": "bridge-facts",
+  "platform": "python",
+  "roles": ["server"],
+  "target": "http",
+  "tool": { "name": "pythograph", "version": "0.1.0" },
+  "version": 1
+}
+```
+
+### What is modeled
+
+Every rule was checked against the installed package sources (Django 5.2.17, djangorestframework 3.18.1,
+Flask 3.1.3, Werkzeug 3.1.9). The full table with source files is in [docs/HTTP-ROUTES.md](https://github.com/ictechgy/pythograph/blob/main/docs/HTTP-ROUTES.md)
+(Korean).
+
+- **Django**: `ROOT_URLCONF` from the settings module (star imports of project settings modules are
+  followed), `urlpatterns` built with lists, `+`, `+=`, `.append`, `.extend`, `.insert`, `path()`, `re_path()`,
+  `include()` (module strings, module objects, lists, `(patterns, app_name)` tuples, nested), default and
+  registered path converters, `re_path` regular expressions converted from their syntax tree when possible,
+  function views (`ANY`, narrowed by `require_http_methods`/`require_GET`/`require_POST`/`require_safe`/
+  `api_view`), class views (`as_view()`, handlers along the class chain, `http_method_names`), and the
+  registration order (first match wins).
+- **Django REST framework**: `SimpleRouter`/`DefaultRouter` (`trailing_slash`, `use_regex_path`, lookup
+  settings, `@action` with `detail`, `methods`, `url_path`, and `.mapping`), the `DefaultRouter` API root and
+  format-suffix variants, `format_suffix_patterns`, `APIView`, generic views, and viewsets.
+- **Flask**: `Flask(...)` and `Blueprint(...)` objects at module level or in app factories, `@route`,
+  `@get`/`@post`/`@put`/`@delete`/`@patch`, `add_url_rule`, `register_blueprint` (nested, `url_prefix`),
+  `MethodView`/`View`, Werkzeug converters (`string`, `int`, `float`, `uuid`, `path`, `any`, custom),
+  `strict_slashes`, and `merge_slashes`.
+
+### How facts are built
+
+- **channel**: the canonical path template. A parameter filling a whole segment is `{}`, a partial segment
+  keeps its literal skeleton (`/files/{}.json`), a final parameter that can match `/` is `{**}`, and anything
+  else that cannot be proven (a segment with two parameters, a middle catch-all, lookarounds, unanchored
+  regular expressions) is `dynamic` with a `route-coverage:` limitation. Literals are in the decoded path
+  space, so non-pchar characters are UTF-8 percent-encoded and `%` becomes `%25`.
+- **method**: uppercase verbs or `ANY`. `HEAD` next to `GET` and automatic `OPTIONS` are not emitted (isthmus
+  matches them with `head-as-get` and `options-any`); an explicitly declared `OPTIONS` is.
+- **paramConstraints**: `int`, `slug`, `uuid`, `path` (for `{**}`), or `regex` with the pattern.
+- **trailingSlash**: Django and strict Flask rules are `strict`; `/?` in a regex and Flask
+  `strict_slashes=False` are `optional`; omitted after `{**}`.
+- **order** (Django): `{group: "django:<ROOT_URLCONF>", index: <depth-first position>}`.
+- **location**: the route string argument (Django `path()`/`re_path()`, Flask decorator or `add_url_rule`), the
+  `router.register()` prefix for DRF routes, or the `@action` decorator for extra actions; 1-based line and
+  1-based UTF-8 byte column.
+
+### Symbol ids
+
+`symbol.usr` is `<project-relative POSIX path>#<lexical dotted name>`, outermost declaration first and
+without `<locals>`: `catalog/views.py#item_list`, `blog/__init__.py#create_app.index`,
+`catalog/views.py#ItemEditView.get`, `orders/views.py#OrderViewSet.list`. Class handlers are named after the
+class registered in the URL even when the method is inherited; the call graph (`pythograph graph`) has an
+inherited-member node with the same id. Views defined outside the project have no usr and are counted under
+`missing-route-usrs:`.
+
+### Limitations
+
+When a value cannot be proven, pythograph does not guess: it emits `dynamic`, `pathAnchor: "base"`, or a
+limitation with one of the contract's prefixes, and adds `limitationScopes` only when it can prove an upper
+bound. Examples: conditional registrations (`if settings.DEBUG:`) become `route-coverage:` scoped to their
+templates; unresolved includes and third-party URL modules are scoped to their include prefix; the Django admin,
+`static()`, `django.contrib.staticfiles`, and Flask static files are `framework-provided-routes:` with prefix
+scopes (Flask static also with `GET`/`HEAD`); `FORCE_SCRIPT_NAME`, `i18n_patterns`, and blueprints whose
+registration is not visible use a `base` anchor with `unresolved-route-prefix:`; a project that does not pin
+Django 5, DRF 3, or Flask 3 gets `route-framework-version-unknown:`.
+
+### Decisions
+
+- **Django is `registration-order`, Flask is `specificity`**, as verified from the sources. isthmus releases
+  before `f9dcd1d` reject `registration-order`; `--dispatch specificity` declares specificity for Django and omits
+  `order`. That approximation can only produce false matches (a shadowed pattern matched), never false errors,
+  because isthmus filters by method first and reports a method mismatch only when no candidate accepts the
+  method, which is also when Django answers 405.
+- **Shadowed patterns are still declarations**; shadowing is the consumer's judgement from `order`.
+- **Conditional registrations are scoped limitations**, not declarations.
+
+## `pythograph schema`
+
+```sh
+pythograph schema --project <root> [--include-tests] [--settings <module>] [--generated-at <timestamp>] [--format json]
+```
+
+Writes a bridge-facts v1 document with `platform: "python"`, `target: "persistence"` (or `null` when there are no
+facts), and one `relation-use` fact per observed relation or column reference. isthmus joins it with a
+`platform: "sql"` document (schemagraph `facts --document <catalog>`) under the persistence rules of
+`docs/GRAPH-EXCHANGE.md`. The full rule table with source files is in [docs/PERSISTENCE.md](https://github.com/ictechgy/pythograph/blob/main/docs/PERSISTENCE.md)
+(Korean).
+
+- **Django**: model classes (abstract, proxy, multi-table inheritance, `Meta` inheritance) → tables
+  (`<app_label>_<model>` truncated by `truncate_name` for the backend's `max_name_length`, or `Meta.db_table`), fields →
+  columns (`db_column`, `<name>_id` for foreign keys, many-to-many tables and their columns), app labels from
+  `INSTALLED_APPS`/`AppConfig`, the `DATABASES` backend, and django.contrib models. Uses: managers and QuerySet chains,
+  lookups (`author__profile__city`, reverse relations, `attname`, `pk`), `values`/`order_by`/`F`/`Q`/aggregates,
+  `create`/`update` keywords, related managers and forward relations on proven instances, `raw()`, `RawSQL`,
+  `extra(tables=)`, and cursor SQL.
+- **SQLAlchemy 2.x / Flask-SQLAlchemy 3**: Declarative classes (`DeclarativeBase`, `declarative_base()`, `db.Model`
+  with its snake_case names), mixins, single- and joined-table inheritance, `__table_args__`/`MetaData` schemas, Core
+  `Table`, `ForeignKey("t.c")`, `relationship(secondary=)`. Uses: statement entities (`select`, `insert`, `update`,
+  `delete`, `session.query`, `session.get`, `join`), `Model.column`, `Model.relationship`, `Model.query`, `filter_by`,
+  constructors, `table.c.name`, and `text()`.
+- **SQL text**: the family's shared lexical extractor (the same vectors as tsograph, dartograph, cartograph, and
+  kartograph) for explicit SQL arguments, and uppercase SQL literals elsewhere (docstrings are skipped).
+- **channel** is the relation name as written or mapped (`schema.table` only when qualified; no default schema is
+  guessed), **method** is the column, and **symbol.usr** is the enclosing function, method, or model class with the
+  same ids as `routes`. A name that depends on an unknown backend, app label, or Flask-SQLAlchemy version, an
+  unresolved model or lookup, and SQL built at runtime become `dynamic` facts with a `dynamic-relation-names:`
+  limitation instead of guesses.
+- Test sources (unless `--include-tests`) and migrations (Django `migrations/`, Alembic `versions/`) are not scanned;
+  migrations describe past schemas.
+
+## `pythograph graph` / `reach` / `impact`
+
+```sh
+pythograph graph  --project <root> [--include-tests] [--revision <id>] [--generated-at <timestamp>]
+pythograph reach  --project <root> [--dispatch direct|bound|candidates] [--max-depth <n>] [--max-reached <n>]
+                  [--roots-from <file|->] [--include-tests] [--revision <id>] [--generated-at <timestamp>] [--] <id>...
+pythograph impact (same options as reach)
+```
+
+Builds the project's Python call graph with the standard-library `ast`. `graph` writes pythograph's own snapshot
+(`pythograph-graph` v1); `reach` writes the symbols the roots depend on (`dependencies`) and `impact` the symbols that
+depend on them (`dependents`) as isthmus
+[`language-traversal` v1](https://github.com/ictechgy/isthmus/blob/main/docs/LANGUAGE-TRAVERSAL.md). Ids are the same
+strings as `symbol.usr` in `routes` and `schema`. The full rules are in [docs/GRAPH.md](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md) (Korean).
+
+- **Nodes**: modules (`<path>#<module>`), functions, methods, classes, nested definitions, and inherited members
+  (`<registered class>.<member>`, for view handlers and for inherited members called on exact receivers).
+- **Edges**: `call`, `new` (the project `__init__`, else the class), `callback`, `reference`, `decorator`, `attribute`
+  (class-body attributes), `inherit`, and `dispatch`/`framework` (framework dispatch). Resolution follows imports
+  (absolute, relative, aliases, `__init__` re-exports, `*`), module attributes, constructors, `self` and `super()`
+  through the C3 MRO of project classes, annotated and return-annotated receivers, module-level instances, and
+  properties.
+- **Evidence tiers**: statically resolved edges are `direct`; overrides in project subclasses for `self`, `cls`, and
+  annotated receivers are `candidate`. `bound` edges are not produced yet, so `--dispatch bound` follows the `direct`
+  graph.
+- **No guessing**: calls without a known target are counted by reason (`parameter`, `untyped-receiver`,
+  `dynamic-attribute`, `getattr`, `dynamic-callee`, `unresolved-import`, `framework-callback`, …) as each symbol's
+  `unresolvedCalls`. A method call on an untyped receiver is proven external only when no project class, module, or
+  attribute write defines that name.
+- **Framework dispatch**: a table read with `ast` from the installed Django 5.2.17, DRF 3.18.1, and Flask 3.1.3
+  sources links the project hooks that the `as_view()` dispatch path (`dispatch`, `initial`, permission checks,
+  `__init__`) and framework implementations (`ModelViewSet.retrieve` → `get_object` → `get_queryset`,
+  `ModelSerializer.save` → `create`) call. Objects the framework builds from class attributes (`serializer_class`,
+  `permission_classes`) count as `framework-callback` unresolved calls.
+- **Traversal documents**: a `dispatch` declaration, per-root lower-bound `evidence`, `unresolvedCalls`, one
+  multi-root pass (compared with a per-root oracle on random graphs), `--max-depth`/`--max-reached` truncation, and
+  `rootsTruncated`. Roots that are not graph nodes are listed without `symbol`; the document is written and the
+  command exits `64`. `revision` is `--revision` or git `HEAD` when the work tree is clean; `graphRevision` is a
+  SHA-256 of the graph content.
+
+## Validation
+
+The oracle harness in `experiments/oracle/` imports the synthetic fixtures in a scratch virtual environment
+and compares pythograph's facts with Django's resolver traversal, DRF routers, and Flask's `url_map`
+(`tests/test_fixtures.py` replays the recorded results offline):
+
+| Target | Precision | Recall |
+|---|---|---|
+| `fixtures/django/drf-shop` | 69/69 | 58/59 (one intentional dynamic lookahead pattern) |
+| `fixtures/flask/blog-app` | 28/28 | 27/27 |
+| HackSoftware/Django-Styleguide-Example `a70ef43` (MIT, scratch clone) | 21/21 | 21/22 (the DEBUG-only `static()` route) |
+
+Dogfooding on four public apps (Django-Styleguide-Example, babybuddy, microblog, and netbox, cloned only into a scratch
+directory) measured route precision against each framework's resolver, relation-use join rates through schemagraph and
+isthmus, handler-to-relation reachability, unresolved-call reasons, and runtime; the results and the fixed issues are in
+[DOGFOOD.md](https://github.com/ictechgy/pythograph/blob/main/DOGFOOD.md) (Korean).
+
+The isthmus shared conformance vectors (`conformance/`, vendored from isthmus `f9dcd1d` and locked in
+`conformance.lock`) pass 100% of the applicable producer cases (78: `template.grammar`, `template.normalize`,
+`scope.validate`, `scope.applies`, `dispatch.validate`); the `dispatch.validate` checker also runs on the routes
+golden output.
+
+**Phase 6 exit criterion (Django backend × iOS/Android chain).** `experiments/e2e/` joins a synthetic Django + DRF
+server (`fixtures/e2e/shop-api`), a schemagraph catalog of its Django DDL, and route-calls plus reverse traversals of
+synthetic iOS (cartograph) and Android (kartograph) clients with isthmus `trace` (workspace). The expected paths of the
+three questions match: (a) API → DB tables + DB dependents, (b) API → client call sites → affected client symbols, and
+(c) table → API → client. The Android recording needs kartograph `4c09d91` or later (Retrofit route-call usrs and
+`baseUrl` joins), which attaches the Android order and checkout calls to the chain. `tests/test_e2e_trace.py` re-checks
+the recorded inputs and outputs offline (the table is in
+[docs/GRAPH.md](https://github.com/ictechgy/pythograph/blob/main/docs/GRAPH.md#phase-6-종료-조건-django-백엔드--iosandroid-체인)).
+
+Persistence naming vectors (`fixtures/persistence-naming/vectors.json`) are recorded by importing synthetic models
+with the real ORMs in a scratch environment (`experiments/persistence/run_naming.py`): Django 5.2.17 `_meta` names
+quoted by each backend's `connection.ops` (sqlite3, postgresql, mysql, oracle), and SQLAlchemy 2.0.54 /
+Flask-SQLAlchemy 3.1.1 mappers. pythograph matches 100% (Django 136/136 model-backend pairs, SQLAlchemy 9/9 and
+Flask-SQLAlchemy 10/10 classes, all tables and columns). Joining `pythograph schema` output for the two persistence
+fixtures with schemagraph catalogs of the DDL the ORMs create (`experiments/persistence/run_e2e.py`) gives no isthmus
+errors (41 and 20 matches).
+
+## isthmus compatibility
+
+isthmus `main` (`f9dcd1d`, #128) accepts `platform: "python"`: http `route-decl` facts (Django's `registration-order`
+and `order`, with shadowing diagnostics), persistence `relation-use` facts, and python `forward`/`reverse` analyses
+(`language-traversal` v1) in `trace`. `--dispatch specificity` remains for older isthmus releases.
+
+## Development
+
+```sh
+uv sync
+uv run ruff check src tests && uv run ruff format --check src tests
+uv run mypy
+uv run pytest --cov          # line and branch coverage gate: 90%
+uv run python scripts/verify_cli_contract.py
+```
+
+The framework hook table is regenerated from a scratch virtual environment with Django 5.2.17, DRF 3.18.1, and
+Flask 3.1.3 installed: `python experiments/graph/dump_framework_hooks.py --site-packages <path>` (`--check` compares
+only).
+
+## License
+
+MIT