추가: 공통 PIT 팩터 계약과 EDGAR 재무 작업대

Author: eddmpython

mainPlan/unified-data-workbench/04-verification-progress-ledger.md

@@ -14,6 +14,7 @@
 | W7 | Signature Data Prism 혼합 query, evidence, quality, Arrow | 완료 |
 | W8 | 170개 전수 실행, selector, 빈 결과, 동시성 hardening | 완료 |
 | W9 | 실제 content 봉인, 외부 구조 보존, 전종목 자동 page 소비 | 완료 |
+| W10 | 공통 feature observation 계약과 실제 EDGAR PIT factor 수직 슬라이스 | 완료 |
 
 ## 2. unit과 contract test
 
@@ -189,3 +190,23 @@ uv run python -X utf8 tests/audit/dartlabGuard.py strict --scope l0-l15 --provid
 - 한 Python 소비 흐름에서 DART 5개와 EDGAR 4개 synthetic shard를 중복과 누락 없이 완주
 - resource owner의 description과 read가 single-use manifest session을 공유해 전수 manifest 순회를 page당 3회에서 2회로 축소
 - strict mutable source의 pre-snapshot과 반환 전 post-validation, committed replay 무접촉 계약 유지
+
+### 2026-07-23 W10
+
+- feature registry, observation, vintage, revision-aware query 계약을 `dartlab.data` 공통 계층으로 이동
+- 기존 simulator import 경로는 compatibility re-export로 유지해 외부 작업대와 simulator의 의미 규칙 통일
+- 엄격한 달력 날짜, `MARKET:ID` entity, feature definition과 normalization 결박, duplicate와 normalization drift 차단
+- valid time과 knowledge time, staleness, bounds, same-day date precision, missing matrix, 동일 timestamp revision ambiguity를 공통 PIT selector에서 검증
+- `observationPIT` 선언 owner가 typed observation envelope 대신 일반 frame을 반환하면 실행 후 fail-closed
+- `analysis.edgarFinancialFeatures` callable asset을 catalog에 추가해 전체 354개, queryable 171개, callable 2개로 확장
+- 로컬 EDGAR companyfacts 전용 9열 reader와 operating-company reduced financial feature owner 구현
+- 외부 JSON mapping 한 번 호출에서 AAPL revenue와 operating margin을 factor row로 반환하고 actual filing time, observation ID, revision ID, feature version, lineage를 보존
+- query cutoff가 달라도 같은 evidence와 값이면 동일 observation과 revision identity를 유지
+- retained companyfacts의 과거 admission snapshot 부재를 `latestRetained`, `periodOnly`, `conditional` gap으로 표면화
+- 전체 시장 원천 DART와 EDGAR continuation과 subject-only PIT feature 범위를 명시적으로 분리
+- 공통 feature, actual owner, catalog, query, simulator 집중 회귀 93건 통과
+- 작업대 핵심, simulator, architecture, Skill OS 연결 회귀 196건 통과
+- continuation, restart, CAS, Arrow, page scan 회귀 207건 통과와 환경 의존 2건 skip
+- resource paging과 별도 process resume 회귀 31건 통과
+- L0부터 L15 strict guard 7개 규칙, workbench purity, 신규 공개 함수 docstring strict, camelCase, Ruff, targeted Pyright 통과
+- 영구 materialization, historical universe, 전종목 계산 feature paging, offline과 online serving은 runtime SSOT 불가능 실측, 사전 설계 토론, 명시 승인 전 미구현 상태 유지

mainPlan/unified-data-workbench/06-full-certification-and-hardening.md

@@ -10,20 +10,22 @@ Data Workbench 공통 계층은 signature-grade로 판정한다. 이유는 일
 
 | 항목 | 실측 |
 |---|---:|
-| 전체 asset | 353 |
-| queryable | 170 |
+| 전체 asset | 354 |
+| queryable | 171 |
 | catalog-only | 183 |
 | engineAxis | 146 |
-| callable | 1 |
+| callable | 2 |
 | resource locator | 23 |
 | L1 queryable | 39 |
 | L1.5 queryable | 28 |
-| L2 queryable | 103 |
+| L2 queryable | 104 |
 
 `gather.calendar`는 registry에 남아 있지만 호출하면 항상 폐기 예외를 내므로 `queryable=False`와 `executorKind=catalog`로 바로잡았다. catalog에서 삭제하지 않아 폐기 이유와 drift는 계속 추적된다.
 
 ## 3. 전수 계약 인증
 
+아래 표는 W8 당시 queryable 170개 baseline이다. W10의 171번째 callable asset은 공통 feature 집중 회귀와 실제 AAPL smoke로 별도 인증했으며 §8에 기록한다.
+
 | gate | 범위 | 결과 |
 |---|---:|---:|
 | executor 해소 | queryable 170 | 170 통과 |
@@ -102,7 +104,15 @@ quant.entry와 quant.style은 `dipBuy`가 등록하지 않은 camelCase Signal k
 
 - runtime `timeoutMs`는 owner Python 호출을 강제 종료하지 못하는 협력적 제한이다. 전수 인증 runner는 프로세스 격리로 이 한계를 보완했다.
 - row와 byte budget은 owner 결과를 받은 뒤 projection에서 적용된다. owner별 predicate, projection, slice pushdown은 별도 최적화가 필요하다.
-- 실제 knownAt vintage를 제공하는 asset은 아직 없다. latest-only를 과거 성공으로 꾸미지 않는 fail-closed가 현재 정답이다.
-- Arrow table 변환은 완료됐지만 네트워크 Arrow Flight server와 continuation token은 아직 transport 확장 범위다.
+- `analysis.edgarFinancialFeatures`가 실제 filing cutoff를 쓰는 knownAt feature를 제공하지만, retained companyfacts가 historical admission snapshot 전체를 보존하지 않아 exact가 아니라 conditional이다.
+- raw DART와 EDGAR resource는 opaque continuation을 지원한다. 전종목 계산 feature paging과 네트워크 Arrow Flight server는 아직 확장 범위다.
 
 따라서 현재 제품은 단일 프로세스와 외부 Python 소비에 강력한 범용 데이터 작업대다. 분산 서버에서 hard cancellation, streaming, owner pushdown까지 갖춘 최종 물리 플랫폼이라고 부르지는 않는다.
+
+## 8. 2026-07-23 revision-aware feature 확장
+
+data 공통 계층에 feature registry, observation, vintage, revision-aware query 계약을 추가했다. `analysis.edgarFinancialFeatures`는 subject와 knownAt을 받는 두 번째 callable asset이며 로컬 EDGAR companyfacts에서 operating-company reduced financial feature를 만든다. catalog는 354개, queryable은 171개가 됐다.
+
+AAPL 실제 로컬 smoke에서 revenue와 operating margin 두 feature를 한 공개 query로 반환했다. 관측의 `knownAt`은 query cutoff가 아니라 실제 최대 filing date였고, 인접 cutoff는 같은 evidence에 대해 동일 observation ID와 revision ID를 유지했다. 현재 보존 이력의 한계는 `latestRetained`, `periodOnly`, `conditional`로 표시했다.
+
+이 확장은 전종목 raw resource continuation을 전종목 factor store로 바꾸지 않는다. 현재 feature callable은 `subjectFanout`이다. 영구 materialization, historical universe, 전종목 계산 feature paging, offline과 online serving은 runtime SSOT로 불가능하다는 실측, 별도 atomic generation 설계 토론, 명시적 아키텍처 승인 뒤에만 코드와 실행을 진행한다.

mainPlan/unified-data-workbench/README.md

@@ -1,6 +1,6 @@
 # DartLab Unified Data Workbench
 
-상태: 구현, 전수 라우팅과 projection 인증, 170개 실제 물질화 감사, 외부 설치 검증 완료. 2026-07-22 저장소 실측과 공식 외부 설계 조사를 반영한다.
+상태: 구현, 전수 라우팅과 projection 인증, 170개 실제 물질화 감사, 171개 queryable catalog, 외부 설치 검증 완료. 2026-07-23 저장소 실측을 반영한다.
 
 ## 한 문장 정의
 
@@ -24,6 +24,8 @@
 12. partition은 구조화 lineage, quality assertion과 Arrow transport를 제공한다.
 13. catalog `snapshotId`와 실제 반환 content의 `dataSnapshotId`를 분리하고 partition마다 `contentHash`를 둔다.
 14. 전종목 continuation은 첫 `DataResult`의 `iterPages()` 또는 `iterAllArrowBatches()`가 자동 소비한다.
+15. feature registry, observation, vintage, PIT query는 data 공통 계약이며 simulator와 외부 소비자가 같은 의미 규칙을 쓴다.
+16. 전종목 원천 paging과 계산된 전종목 factor paging은 구분한다. 현재 EDGAR PIT feature는 subject 단위 callable이다.
 
 ## 공개 계약
 
@@ -45,6 +47,8 @@ result = dartlab.data(
 )
 ```
 
+같은 진입점에서 `analysis.edgarFinancialFeatures`를 `knownAt`과 `FactorProjection`으로 요청하면 실제 filing cutoff를 보존한 revision-aware feature row를 얻는다. 현재 retained companyfacts의 이력 한계 때문에 이 자산은 `latestRetained`, `periodOnly`, `conditional`로 정직하게 반환한다.
+
 `DataResult`는 최소한 `status`, `partitions`, `assets`, `snapshotId`, `dataSnapshotId`, `contractHash`, `coverage`, `gaps`, `lineageRefs`, `executionReceipts`, `continuation`을 함께 가진다. schema와 실제 값의 `contentHash`는 각 partition이 보존한다.
 
 ## 문서 지도

src/dartlab/analysis/dataProduct.py

@@ -29,5 +29,37 @@
             "temporalSupport": ("latest", "validAt"),
             "metadata": {"stockRequired": True, "returnType": "dict"},
         },
+        {
+            "assetId": "analysis.edgarFinancialFeatures",
+            "kind": "featureSet",
+            "label": "EDGAR 영업회사 축약 재무 feature",
+            "description": "로컬 companyfacts에서 knownAt 기준으로 구성한 조건부 축약 재무 관측",
+            "executor": {
+                "module": "dartlab.analysis.financial.dataAssets",
+                "attribute": "edgarFinancialFeatures",
+            },
+            "sourceModules": (
+                "dartlab.analysis.financial.filingFeatures",
+                "dartlab.analysis.financial.edgarPitState",
+                "dartlab.analysis.financial.stepProjection",
+                "dartlab.providers.edgar.finance.facts",
+            ),
+            "subjectParam": "subject",
+            "knowledgeTimeParam": "knownAt",
+            "temporalSupport": ("knownAt",),
+            "selectorKind": "subject",
+            "selectorRequired": True,
+            "executionMode": "subjectFanout",
+            "universeMarkets": ("US",),
+            "metadata": {
+                "definitionVersion": "edgar-reduced-operating-financial-features-v1",
+                "featureCoverage": "reducedOperatingCompany",
+                "knownAtRequired": True,
+                "market": "US",
+                "observationPIT": True,
+                "returnType": "feature-observation-input-v1",
+                "stockRequired": True,
+            },
+        },
     ),
 }

src/dartlab/analysis/financial/dataAssets.py

@@ -58,9 +58,11 @@ def simulationInputs(
             raise ValueError("simulationInputs는 subject 또는 company가 필요합니다")
         import dartlab
 
-        company = dartlab.Company(subject)
+        companyFactory = getattr(dartlab, "Company")
+        company = companyFactory(subject)
+    resolvedCompany: Any = company
     try:
-        quarterly = company._buildFinanceSeries(freq="Q")
+        quarterly = resolvedCompany._buildFinanceSeries(freq="Q")
     except (ValueError, KeyError, AttributeError):
         quarterly = None
     rawSeries = quarterly[0] if isinstance(quarterly, tuple) and len(quarterly) >= 2 else None
@@ -78,3 +80,50 @@ def simulationInputs(
         "latestAsOf": latestAsOf,
         "requestedAsOf": requestedAsOf,
     }
+
+
+def edgarFinancialFeatures(
+    *,
+    subject: str | None = None,
+    company: Any | None = None,
+    knownAt: str,
+) -> dict[str, Any]:
+    """로컬 EDGAR evidence에서 operating-company PIT feature envelope를 만든다.
+
+    Args:
+        subject: US ticker 또는 Company가 해소할 수 있는 EDGAR identity.
+        company: 테스트와 read-once 조합을 위한 기존 EDGAR Company.
+        knownAt: SEC filing knowledge cutoff.
+
+    Returns:
+        Data Workbench가 검증하고 FactorProjection으로 변환할 plain mapping.
+
+    Raises:
+        ValueError: Subject가 없거나 EDGAR Company가 아니거나 coherent reduced state가 없을 때.
+        FileNotFoundError: 현재 runtime에 local companyfacts shard가 없을 때.
+
+    Example:
+        ``payload = edgarFinancialFeatures(subject="AAPL", knownAt="20250201")``
+    """
+
+    if company is None:
+        if not subject:
+            raise ValueError("edgarFinancialFeatures는 subject 또는 company가 필요합니다")
+        import dartlab
+
+        companyFactory = getattr(dartlab, "Company")
+        company = companyFactory(subject)
+    resolvedCompany: Any = company
+    cik = getattr(resolvedCompany, "cik", None)
+    ticker = str(getattr(resolvedCompany, "ticker", subject or "")).strip().upper()
+    if not cik or not ticker or ticker.isdigit():
+        raise ValueError("edgarFinancialFeatures는 canonical ticker가 있는 EDGAR Company가 필요합니다")
+    from dartlab.analysis.financial.filingFeatures import buildEdgarFinancialFeatureInput
+    from dartlab.providers.edgar.finance.facts import readCompanyFactsLocal
+
+    facts = readCompanyFactsLocal(str(cik))
+    return buildEdgarFinancialFeatureInput(
+        facts,
+        entityId=f"US:{ticker}",
+        knownAt=knownAt,
+    )