Provider Protocol 동일 surface — 3-regulator drop-in

무엇을 하나

dart · edgar · edinet 3 provider 의 공통 표면을 정의하는 5 Protocol SSOT 와 그 SSOT 위에 새 regulator 를 drop-in 으로 얹는 4 단계 절차를 박는다. P-PR 트랙의 method-level symmetry baseline (providerSymmetry.json) 의 객관 기준이 본 spec.

Protocol 5 종 (SSOT 위치)

Protocol	위치	핵심 메서드
CompanyProtocol	src/dartlab/core/protocols.py:69-225	__enter__ / __exit__ / show / select / trace / diff / filings / disclosure / liveFilings / readFiling / view / quant / ask + index / topics / sections property
DocsProvider	src/dartlab/core/protocols.py:366-419	fetchFiling(stockCode, *, period) / listSections(...) / iterSections(...)
FinanceProvider	src/dartlab/core/protocols.py:422-476	fetchStatements(...) / listAccounts(...) / iterAccounts(...)
FilingsProvider	src/dartlab/core/protocols.py:480-513	search(query, *, market=None, limit=20) / iterSearch(...)
MemorySafeProvider	src/dartlab/core/protocols.py:517-540	cleanupCache() -> int / memorySnapshot() -> dict[str, int]

5 종 모두 @runtime_checkable — isinstance(co, CompanyProtocol) 가능.

새 provider 추가 4 단계

1. providers/{@html String.fromCharCode(123)}name{@html String.fromCharCode(125)}/company.py 의 Company 가 CompanyProtocol 구현

12 메서드 + 3 property 시그니처 그대로. dart-only 메서드 (codeName / keywordTrend / news / listing / credit 등 18) 는 본 Protocol 에 없음 — 신규 provider 는 구현 의무 없음.

# providers/sgx/company.py 예시
from dartlab.core.protocols import CompanyProtocol

class Company:  # implements CompanyProtocol structurally
    def __init__(self, stockCode: str) -> None: ...
    def __enter__(self) -> "Company": ...
    def __exit__(self, *_: object) -> None: ...
    # show / select / trace / ... 12 method + 3 property

2. providers/{@html String.fromCharCode(123)}name{@html String.fromCharCode(125)}/{@html String.fromCharCode(123)}docs,finance,filings{@html String.fromCharCode(125)} namespace 가 각 Provider Protocol 구현

# providers/sgx/docs/__init__.py
from dartlab.core.protocols import DocsProvider, FilingResult, Section

class _SgxDocs:  # implements DocsProvider
    def fetchFiling(self, stockCode: str, *, period: str) -> FilingResult | None: ...
    def listSections(self, stockCode: str, *, period: str) -> list[Section]: ...
    def iterSections(self, stockCode: str, *, period: str) -> Iterator[Section]: ...

3. providers/{@html String.fromCharCode(123)}name{@html String.fromCharCode(125)}/__init__.py 에 Company + 3 namespace re-export

"""SGX (싱가포르 거래소) 데이터 소스 엔진."""
from dartlab.providers.sgx import docs, finance, filings
from dartlab.providers.sgx.company import Company

__all__ = ["finance", "docs", "filings", "Company"]

providers/__init__.py 의 __all__ 에 "sgx" 추가.

4. baseline 갱신

• tests/test_providerContract.py 의 provider iteration 에 "sgx" 추가.
• tests/audit/_baselines/providerSymmetry.json 에 신규 provider 항목 등록.
• tests/audit/providerSymmetry.py 의 _SYMMETRY_MAP 에 SGX-specific rename / dart_only / sgx_deferred 항목 등록.

3 provider asymmetry (현 상태)

dart (한국, 50,855 LoC)

가장 깊은 구현. 한국 시장 특화 18 메서드 보유 — edgar 패리티 대상 아님. _SYMMETRY_MAP.dart_only 영구 등록:

카테고리	메서드
식별자	codeName / resolve / status
시장 메타	listing / industry
검색 / 뉴스	search / keywordTrend / news / publicSentiment
분석 결합	credit / marketScan / keywordTrend / watch / story / analysis / validateStory
데이터	gather / table / rawDocs / rawFinance / rawReport

edgar (미국, 15,010 LoC)

P-PR6/7/8 후 dart 패리티 도달. XBRL / 10-K sections / Form 4 / DEF 14A / 8-K — 자체 구현 확장 (외부 edgartools 미도입).

edinet (일본, 2,856 LoC)

5 method 사용자 명시적 deferred — _SYMMETRY_MAP.edinet_deferred 영구 등록:

• ask (LLM 통합)
• quant (기술적 분석)
• disclosure (공시 검색 확장)
• liveFilings (실시간 공시)
• readFiling (원문 읽기)

본 5 method 는 EDINET API 한정 차이 + 우선순위 결정. P-PR8 strict 전환 시 baseline 영구 제외.

검증

uv run python -X utf8 -c "
from dartlab.core.protocols import CompanyProtocol
from dartlab.providers import dart, edgar, edinet
for mod, code in [(dart, '005930'), (edgar, 'AAPL'), (edinet, '7203')]:
    co = mod.Company(code)
    assert isinstance(co, CompanyProtocol), f'{mod.__name__}: CompanyProtocol fail'
    print(f'{mod.__name__}: CompanyProtocol OK')
"

tests/test_providerContract.py 의 test_company_isinstance_runtime + test_provider_namespaces_isinstance 자동화.

폴더 mirror (10 sub-folder)

폴더	책임
accessor/	provider-specific data access (DartClient · SEC API client 등)
builder/	캐시 빌더 (filings catalog · finance statements 등)
bulk/	bulk 적재 (corp_code dump · companyfacts batch 등)
docs/	공시 본문 파싱 (DocsProvider 구현)
finance/	재무제표 정규화 (FinanceProvider 구현)
openapi/	raw HTTP client / API key
ops/	운영 유틸 (calendar / disclosure schedule 등)
parse/	표·HTML·XBRL 파서
report/	정형 report (옵션)
search/	도메인 검색 (FilingsProvider 구현)

누락 폴더는 placeholder __init__.py 만 — Protocol contract 만족 위해.

다음 단계

• engines.company — Company facade 사용법
• engines.dart / engines.edgar / engines.edinet — provider 별 엔진 사용법
• operation.code § 11 룰 — 모든 provider 준수 룰
• operation.architecture § 3-provider mirror — 아키텍처 SSOT