orbitoby 0.1.0__tar.gz

orbitoby-0.1.0/AI_USAGE.md

@@ -0,0 +1,23 @@
+# AI 사용 기록 / AI usage record
+
+AI 기여, 실제 검증, 사람 검토, 최종 결정을 구별한다. 작업 허용이나 자료 제공은 내용 전체의 사람 검토 완료가 아니다. 정확한 모델 식별자는 기록되지 않았으며 추정하지 않는다. / Distinguish AI contribution, performed validation, human review and final decisions. Task authorization or supplied material is not completed substantive human review. Exact model identifiers were not recorded and are not inferred.
+
+| 날짜 / Date | 도구 / Tool | 기여·검증 이력 / Contribution and validation history | 사람 검토 / Human review |
+| --- | --- | --- | --- |
+| 2026-09-28 | Codex | 초기 계획·설계·metadata 검토, 15개 격리 합성 checks, read-only DB/hash, 당시 Ruff 19개와 pytest collection 0개 기록. v2 원문과 0–55절·250 IDs 대조. / Initial plan/design/metadata review, 15 isolated synthetic checks, read-only DB/hashes, historical 19 Ruff findings and zero collected pytest tests; comparison of v2 sections 0–55 and 250 IDs. | 세부 내용 검토 대기 / Substantive review pending |
+| 2026-09-28 후속 / Follow-up | Codex | 당시 9/30 PyPI·DOI 목표와 사용자 실행 방식의 3일 계획 작성, 소스 해시 불변 확인. 현재 일정은 마스터플랜으로 대체. / Drafted the then-current three-day, user-run plan targeting September 30 PyPI/DOI and checked unchanged source hashes. Superseded by the current master plan. | 대기 / Pending |
+| 2026-09-29 | Codex | 복제본 recovery 코드와 합성 tests 제공. 최초에는 AST·source hash만 확인했고 실행하지 않음. 이후 사용자 보고의 5-test/subset 성공을 기록하고 추가 restore rehearsal test 제공. / Supplied copied-archive recovery code and synthetic tests; initially checked only AST/source hashes without execution. Later recorded user-reported five-test/subset success and added restore-rehearsal coverage. | 당시 새 전체 검증은 사용자 실행 대기였음 / New full validation was pending user execution at that time |
+| 2026-09-30 | Codex | 공개 repo 원칙 반영, 선택된 파일/history token 패턴 읽기 전용 점검. GCAT 복제본 OOM 진단. 제품 게시·전수 보안 인증은 하지 않음. / Reflected public-repository policy, read-only selected file/history token scans and GCAT copied-archive OOM diagnosis. No publication or comprehensive security certification. | 대기 / Pending |
+| 2026-10-03 출시 검사 / Release audit | Codex | README·배너·문서·TODO, API 확인, 전체 249 tests, 6 fresh-wheel environments, strict Twine 및 metadata/내용 검사. recovery helper timezone digest 최소 수정과 회귀 test; package 기능·성능은 변경하지 않음. / README/banner/docs/TODO, API review, 249 full tests, six fresh-wheel environments, strict Twine and metadata/content checks; minimum recovery-helper timezone-digest fix and regression test, without package feature/performance changes. | 사용자 최종 검토·업로드 승인 대기 / Final user review and upload approval pending |
+| 2026-10-03 문서 통합 / Documentation consolidation | Codex | 메인 1·2의 제공 대화와 기존 계획을 대조, 한/영 문서·250-ID 추적·통합 master 작성. 원본 백업 및 코드 freeze 해시 확인. 문서 변경 후 artifact 재검증 결과는 release report에 기록. / Compared available Main 1/2 conversation content and existing plans; authored bilingual docs, 250-ID traceability and consolidated master. Preserved original backups and checked code-freeze hashes. Post-edit artifact verification is recorded in the release report. | 내용 검토 대기 / Substantive review pending |
+
+역사적 검증 수와 현재 테스트 수는 다른 snapshot이다. 과거 기록을 이번에 다시 수행했다고 주장하지 않는다. 기존 기여 전체를 감사한 기록이나 저널 정책 준수 인증이 아니다. / Historical and current test counts refer to different snapshots. Earlier checks are not claimed as newly rerun. This is neither a complete audit of earlier contributions nor journal-policy certification.
+
+## 기록 원칙 / Recording rules
+
+- 수행하지 않은 검증·사람 검토를 완료 처리하지 않는다. 최종 결정자는 사용자다. / Never mark unperformed validation or human review complete. The user makes final decisions.
+- 주요 설계 근거는 ADR, 현재 계획은 통합 master, 실행 증거는 release report에 둔다. / Keep design rationale in ADRs, current plans in the master and execution evidence in the release report.
+- 비밀값·계정정보·제한 자료는 기록하지 않는다. / Do not record secrets, account information or restricted data.
+- 외부 투고 시 최신 disclosure 정책을 확인한다. 원래 기록은 문서 백업에 보존한다. / Recheck disclosure policies at submission; preserve original records in the documentation backup.
+
+[마스터플랜 / Master plan](docs/ORBITOBY_MASTER_PLAN.md) · [릴리스 보고서 / Release report](docs/RELEASE_0_1_0_REPORT.md)

orbitoby-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# 기여 안내 / Contributing
+
+Orbitoby는 공개 연구 소프트웨어입니다. 현재 0.1.0 기능·성능 코드는 freeze 상태이며 확인된 오류의 최소 수정만 검증 후 반영합니다. 이후 기능은 [통합 계획](docs/ORBITOBY_MASTER_PLAN.md#roadmap)에 기록합니다.
+
+Orbitoby is public research software. Feature and performance code is frozen for 0.1.0; only minimal, verified defect corrections belong in the candidate. Record later features in the [consolidated plan](docs/ORBITOBY_MASTER_PLAN.md#roadmap).
+
+## 개발 환경과 확인 / Development and checks
+
+```bash
+uv sync
+.venv/bin/ruff check --no-cache .
+.venv/bin/ruff format --check --no-cache .
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 PYTHONDONTWRITEBYTECODE=1 \
+  .venv/bin/python -B -W error -m pytest -q -p no:cacheprovider
+```
+
+전체 검사와 배포 확인은 [release.md](docs/release.md)를 따릅니다. 로컬 handoff 테스트가 없는 checkout은 이전 전체 249개보다 적게 수집될 수 있습니다. 숫자만 맞추려고 테스트를 추가·제외하지 않습니다.
+
+Follow [release.md](docs/release.md) for complete verification. A checkout without local handoff tests may collect fewer than the previously reported 249 total. Do not add or exclude tests merely to match a count.
+
+
+- 핵심 설계·과학적 판단의 최종 결정자는 사람입니다. / Humans make final architectural and scientific decisions.
+- AI 보조 변경도 실제 검증과 사람 검토를 구별해 기록합니다. / Record actual validation and human review separately for AI-assisted changes.
+- 기존 API·연구 데이터를 보호하고 migration은 복제본에서 검증합니다. / Protect existing APIs/data and validate migrations on copies.
+- 새 source는 출처·권리·인증·필드/단위·fixture·제한된 live 증거를 갖춰야 합니다. / New sources require provenance, rights, auth, field/unit, fixture, and bounded live evidence.
+- 비밀값·사용자 raw/DB를 commit하지 않습니다. / Never commit secrets or user raw/DB files.
+- 문서는 한·영 병기하며 ADR에는 주요 선택 이유를 남깁니다. / Keep docs bilingual and record major design rationale in ADRs.
+- commit 유형 / commit types: `feat`, `fix`, `test`, `docs`, `refactor`, `chore`.
+
+0.1.x의 공개 API·저장 형식을 v1.0 안정성 약속으로 해석하지 않습니다. 존재하지 않는 CLI나 계획 API를 문서 예제로 추가하지 마세요.
+
+Do not treat 0.1.x APIs/storage as a v1.0 stability promise. Do not document nonexistent CLI commands or planned APIs as executable examples.

orbitoby-0.1.0/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

orbitoby-0.1.0/NOTICE

@@ -0,0 +1,15 @@
+Orbitoby
+Copyright 2026 Jin Yeseo (진예서)
+
+Orbitoby 소프트웨어는 Apache License 2.0으로 배포됩니다.
+The Orbitoby software is licensed under the Apache License 2.0.
+
+외부 과학 데이터는 원래 라이선스, 출처 표기 의무 및 재배포 제한을 유지합니다.
+Third-party scientific datasets retain their original licenses,
+attribution requirements, and redistribution restrictions.
+
+Toby 마스코트, 사진 및 원본 브랜드 자산은 별도 표시가 없는 한
+Copyright 2026 Jin Yeseo (진예서), All Rights Reserved입니다.
+The Toby mascot, photographs, and original brand artwork are
+Copyright 2026 Jin Yeseo (진예서), All Rights Reserved,
+unless separately indicated.

orbitoby-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: orbitoby
+Version: 0.1.0
+Summary: A provenance-first research toolkit for space-weather and orbital time-series data.
+Keywords: astronomy,space-weather,space-environment,satellite,timeseries,provenance
+Author: Jin Yeseo
+Author-email: Jin Yeseo <jinyeseo.public@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: duckdb>=1.5.5
+Requires-Dist: pandas>=3.0.6
+Requires-Dist: pyarrow>=25.0.1
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: pytz>=2026.4
+Requires-Dist: requests>=2.34.2
+Requires-Dist: pymsis>=0.13,<0.14 ; extra == 'models'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/JIN-ARTLW/Orbitoby
+Project-URL: Repository, https://github.com/JIN-ARTLW/Orbitoby
+Project-URL: Issues, https://github.com/JIN-ARTLW/Orbitoby/issues
+Provides-Extra: models
+Description-Content-Type: text/markdown
+
+# Orbitoby
+
+**Orbitoby core never guesses the data.**
+
+Orbitoby는 우주환경·위성 궤도 연구를 위한 provenance-first Python 패키지입니다. 원본 수집, canonical 시계열, exact-time 정렬, catalogue·historical orbit, Swarm 밀도 및 명시적 NRLMSIS 계산을 연결합니다. v0.1.0은 alpha release candidate입니다.
+
+Orbitoby is a provenance-first Python toolkit for space-weather and orbital research. It connects raw acquisition, canonical time series, exact-time alignment, catalogues, historical orbit, Swarm density and explicit NRLMSIS evaluation. Version 0.1.0 is an alpha release candidate.
+
+## 설치 / Installation
+
+Python ≥3.12. 공개 전에는 검증한 로컬 wheel을 설치합니다. 다음 index 명령은 공개된 배포본을 위한 사용법입니다.
+
+Use Python ≥3.12. Before publication, install the verified local wheel; index commands below are instructions for a published distribution.
+
+```bash
+python -m pip install orbitoby
+python -m pip install "orbitoby[models]"
+# 공개 전 로컬 설치 / local installation before publication
+python -m pip install "dist/orbitoby-0.1.0-py3-none-any.whl[models]"
+```
+
+`[models]`는 pymsis를 추가합니다. 기본 탐색·시계열·저장·SVG 플롯에는 필요하지 않습니다. 설치형 CLI entry point는 제공하지 않습니다.
+
+The models extra adds pymsis; base discovery, time series, storage and SVG plotting do not require it. No installed CLI entry point is provided.
+
+## Archive 빠른 시작 / Quick start
+
+```python
+from orbitoby import Archive
+
+with Archive() as archive:
+    print(archive.sources_available())
+    print(archive.datasets(metric="kp", live=False))
+    info = archive.dataset_info("gfz", "kp")
+    kp = archive.timeseries(
+        "kp", source="gfz", dataset="kp", start="2024-05-10", end="2024-05-11"
+    )
+    archive.plot(kp, kind="scatter", title="GFZ Kp").save("kp.svg")
+    window = archive.window(
+        fields=["kp", "ap"], source="gfz", start="2024-05-10", end="2024-05-11"
+    )
+    print(window.data, window.presence)
+```
+
+`datasets()`·`dataset_info()`는 정적 또는 명시적 `live=True` 탐색을 지원합니다. provider-native 자료는 `fetch()`로, 지원된 canonical metric은 `timeseries()` 또는 `space_weather()`로 조회합니다. 모든 provider-native dataset에 canonical mapping이 있는 것은 아닙니다.
+
+Discovery is static unless live lookup is requested. Use fetch() for provider-native data and timeseries()/space_weather() for supported canonical metrics. Native dataset support does not imply canonical mapping.
+
+## 과학적 의미 / Scientific semantics
+
+Canonical 조회와 window는 UTC `[start,end)`입니다. ResearchWindow는 실제 timestamp의 합집합에 exact 정렬하고 `data`, `presence`, `missing_reason`, `provenance`, `units`를 반환합니다. 중복 metric/timestamp는 오류이며 결측값을 보간·평활·resample·ffill·bfill하지 않습니다. 플롯은 line/scatter SVG와 원 데이터·provenance를 반환합니다.
+
+Canonical queries/windows use UTC [start,end). ResearchWindow aligns the union of actual timestamps and retains values, presence, missing reasons, provenance and units. Duplicate claims raise errors. There is no interpolation, smoothing, resampling or filling. Native plotting returns line/scatter SVG, data and provenance.
+
+source가 모호하면 명시해야 합니다. `source_preference`는 첫 matching binding을 선택하며 장애 시 다른 source로 자동 fallback하지 않습니다. 기본 `artifact_resolution="all"`은 중복 주장을 보존합니다. 명시적 `preferred`는 우선순위 선택일 뿐 과학적 충돌 해결이 아닙니다. NRCan의 선언된 같은-source mergeable 제품은 함께 반환될 수 있습니다.
+
+Ambiguous sources require selection. Source preference selects the first matching binding, not runtime outage fallback. Default artifact resolution preserves claims; explicitly requested preferred selection is a priority policy, not scientific adjudication. Declared mergeable products within NRCan can be returned together.
+
+## Population과 historical orbit / Population and orbit
+
+```python
+with Archive(allow_dotenv=True) as archive:
+    candidates = archive.objects(
+        start="2024-05-10",
+        end="2024-05-11",
+        existence="throughout",
+        object_type="payload",
+        sync=True,
+    )
+    orbit = archive.orbit(norad_id=39452, start="2024-05-10", end="2024-05-11")
+    summary = archive.orbit_summary(
+        [39452],
+        start="2024-05-10",
+        end="2024-05-11",
+        periapsis_km=(200, 2000),
+        min_coverage=1.0,
+        sync=False,
+    )
+```
+
+기간 population은 전체 CelesTrak SATCAT의 launch/decay assertion으로 조회합니다. 기본 객체 검색은 로컬이며 `sync=True`로 SATCAT을 갱신합니다. historical orbit은 사용자 credential이 필요한 Space-Track GP_HISTORY이고 날짜 `[start,end)`입니다. 요약 coverage는 실제 레코드가 존재하는 날짜 비율이며 연속 관측을 뜻하지 않습니다.
+
+Period population applies launch/decay assertions from complete CelesTrak SATCAT. Default object searches are local; sync=True refreshes SATCAT. Historical orbit uses authenticated Space-Track GP_HISTORY with date-based [start,end). Summary coverage is the fraction of dates with records, not continuous observation.
+
+## Swarm와 MSIS / Swarm and MSIS
+
+Swarm A/B/C ACC·POD는 관측 기반 provider-derived 밀도이고 NRLMSIS 2.1은 별도 model_output입니다. trajectory는 UTC timestamp·경도/위도 degree·고도 km와 실제 provenance를 제공해야 합니다.
+
+Swarm A/B/C ACC/POD are observation-derived provider products; NRLMSIS 2.1 is separate model output. Supply trajectory UTC timestamps, longitude/latitude in degrees, altitude in kilometres and real provenance.
+
+```python
+# trajectory와 trajectory_parents 구성은 실행 예제를 참고하세요.
+# See the runnable example for trajectory and real parent construction.
+inputs, parents = archive.msis_inputs(
+    trajectory, driver_source="gfz", trajectory_parents=trajectory_parents
+)
+modeled = archive.msis_density(inputs, parents=parents)
+comparison = observed.merge(
+    modeled,
+    on="timestamp",
+    how="outer",
+    suffixes=("_observed", "_model"),
+    validate="one_to_one",
+    indicator=True,
+)
+```
+
+`msis_inputs()`는 명시적으로 GFZ를 선택해 이전 일 F10.7, 완전한 중심 81일 평균, 지정 Ap vector를 구성합니다. 필수 day/bin 누락과 중복 유효 forcing은 오류입니다. 모델 정의 평균은 관측 보간이 아니며 중심 평균은 미래 정보를 사용합니다. 모델 output은 backend/version·parameters·parent lineage를 저장합니다.
+
+Explicit GFZ forcing construction requires the previous-day F10.7, complete centered 81-day mean and defined Ap vector. Missing bins/days and duplicate valid drivers fail. Model-defined means are not observation interpolation; centered means use future information. Model output records versions, parameters and parent lineage.
+
+## 저장·확장 / Storage and extensions
+
+기본 저장소는 `~/.orbitoby`; import 전 `ORBITOBY_DATA_DIR`로 변경합니다. raw payload/manifest/SHA-256, DuckDB metadata, canonical Parquet와 derived/model Parquet를 분리하고 artifact·lineage로 연결합니다. `artifacts()`, `coverage()`, `product_store.lineage()`로 조사합니다.
+
+The default archive is ~/.orbitoby, overridable before import. Raw payloads/manifests/hashes, DuckDB metadata and canonical/derived/model Parquet are separate and linked by artifact IDs and lineage.
+
+HTTPS JSON/CSV/TSV declarative source를 등록하거나 명시적으로 신뢰한 `orbitoby.sources` Python plugin을 확장할 수 있습니다. canonical binding은 명시적으로 정의해야 하며 plugin은 사용자 권한으로 실행됩니다. credential은 runtime/keyring/environment/Colab/opt-in dotenv에서 해석하고 import만으로 .env를 로드하지 않습니다.
+
+Extensions include declarative HTTPS JSON/CSV/TSV and explicitly trusted Python source plugins. Canonical bindings must be explicit; plugins run with user permissions. Credential resolution supports runtime/keyring/environment/Colab/opt-in dotenv without implicit .env loading on import.
+
+## 실행 예제와 연결 검사 / Workflow and connection check
+
+저장소 root에서 순차 실행하세요. 예제는 전체 population→명시적 1개 위성의 historical orbit→F10.7/Kp/Ap/Dst/solar wind→Swarm→MSIS→exact 비교를 시연합니다. 실패 단계는 분리해서 보고합니다.
+
+Run sequentially from the repository root. The example demonstrates complete population, one explicitly selected historical orbit, weather indices, Swarm, MSIS and exact comparison, reporting stage failures separately.
+
+```bash
+.venv/bin/python examples/science_day.py --allow-dotenv
+.venv/bin/python scripts/check_connections.py --allow-dotenv
+```
+
+연결 검사는 source 수·API·DB/storage와 주요 provider를 PASS/FAIL/SKIP으로 표시하며 secrets를 출력하지 않습니다. credential 미설정은 SKIP, FAIL이 있으면 exit 1입니다. `--offline`, `--timeout 20`도 지원합니다. 연결 성공은 자료 전체의 완전성 인증이 아닙니다.
+
+Diagnostics report registry, APIs, local storage and key providers without secrets. Missing credentials are SKIP; any FAIL exits 1. Offline mode and per-worker timeout are available. Connectivity does not certify scientific completeness.
+
+## 제약·문서·인용 / Limits, documentation and citation
+
+현재 snapshot의 과거 존재 판정은 당시 catalogue 복원이 아닙니다. 결측 물리/임무 metadata, quality flag, provider revision, GP ID 중복, cache freshness를 사용자가 검토해야 합니다. orbit propagation·항력/인과적 decay·자동 cohort·범용 CLI는 제공하지 않습니다. E2E 성공과 과학적 타당성 검증은 구별합니다.
+
+Retrospective existence from a current snapshot is not a historical catalogue reconstruction. Researchers must assess missing metadata, quality, revisions, GP-ID deduplication and cache freshness. Propagation, drag/causal decay, automatic cohorts and a general CLI are outside this release. E2E success is distinct from scientific validation.
+
+- [한·영 위키 / Bilingual wiki](docs/wiki/index.md)
+- [전체 공개 API와 dataset / Complete inventory](docs/wiki/api-inventory.md)
+- [연구 예제 코드 / Research example](examples/science_day.py)
+- [검증 보고서 / Verification report](docs/RELEASE_0_1_0_REPORT.md)
+- [기능 동결 / Feature freeze](docs/adr/2026-10-04-release-freeze.md)
+
+소프트웨어 인용: Jin Yeseo, Orbitoby, 사용 버전과 [저장소](https://github.com/JIN-ARTLW/Orbitoby). dataset·model 문헌은 별도로 인용하세요. 확인되지 않은 DOI는 제시하지 않습니다. 코드 라이선스는 [Apache-2.0](LICENSE), 자산·외부 자료 구분은 [NOTICE](NOTICE)를 따릅니다.
+
+Cite Jin Yeseo, Orbitoby, the version used and the repository, plus original datasets and models. No unverified DOI is supplied. Code is Apache-2.0; NOTICE distinguishes assets and external materials.

orbitoby-0.1.0/README.md

@@ -0,0 +1,151 @@
+# Orbitoby
+
+**Orbitoby core never guesses the data.**
+
+Orbitoby는 우주환경·위성 궤도 연구를 위한 provenance-first Python 패키지입니다. 원본 수집, canonical 시계열, exact-time 정렬, catalogue·historical orbit, Swarm 밀도 및 명시적 NRLMSIS 계산을 연결합니다. v0.1.0은 alpha release candidate입니다.
+
+Orbitoby is a provenance-first Python toolkit for space-weather and orbital research. It connects raw acquisition, canonical time series, exact-time alignment, catalogues, historical orbit, Swarm density and explicit NRLMSIS evaluation. Version 0.1.0 is an alpha release candidate.
+
+## 설치 / Installation
+
+Python ≥3.12. 공개 전에는 검증한 로컬 wheel을 설치합니다. 다음 index 명령은 공개된 배포본을 위한 사용법입니다.
+
+Use Python ≥3.12. Before publication, install the verified local wheel; index commands below are instructions for a published distribution.
+
+```bash
+python -m pip install orbitoby
+python -m pip install "orbitoby[models]"
+# 공개 전 로컬 설치 / local installation before publication
+python -m pip install "dist/orbitoby-0.1.0-py3-none-any.whl[models]"
+```
+
+`[models]`는 pymsis를 추가합니다. 기본 탐색·시계열·저장·SVG 플롯에는 필요하지 않습니다. 설치형 CLI entry point는 제공하지 않습니다.
+
+The models extra adds pymsis; base discovery, time series, storage and SVG plotting do not require it. No installed CLI entry point is provided.
+
+## Archive 빠른 시작 / Quick start
+
+```python
+from orbitoby import Archive
+
+with Archive() as archive:
+    print(archive.sources_available())
+    print(archive.datasets(metric="kp", live=False))
+    info = archive.dataset_info("gfz", "kp")
+    kp = archive.timeseries(
+        "kp", source="gfz", dataset="kp", start="2024-05-10", end="2024-05-11"
+    )
+    archive.plot(kp, kind="scatter", title="GFZ Kp").save("kp.svg")
+    window = archive.window(
+        fields=["kp", "ap"], source="gfz", start="2024-05-10", end="2024-05-11"
+    )
+    print(window.data, window.presence)
+```
+
+`datasets()`·`dataset_info()`는 정적 또는 명시적 `live=True` 탐색을 지원합니다. provider-native 자료는 `fetch()`로, 지원된 canonical metric은 `timeseries()` 또는 `space_weather()`로 조회합니다. 모든 provider-native dataset에 canonical mapping이 있는 것은 아닙니다.
+
+Discovery is static unless live lookup is requested. Use fetch() for provider-native data and timeseries()/space_weather() for supported canonical metrics. Native dataset support does not imply canonical mapping.
+
+## 과학적 의미 / Scientific semantics
+
+Canonical 조회와 window는 UTC `[start,end)`입니다. ResearchWindow는 실제 timestamp의 합집합에 exact 정렬하고 `data`, `presence`, `missing_reason`, `provenance`, `units`를 반환합니다. 중복 metric/timestamp는 오류이며 결측값을 보간·평활·resample·ffill·bfill하지 않습니다. 플롯은 line/scatter SVG와 원 데이터·provenance를 반환합니다.
+
+Canonical queries/windows use UTC [start,end). ResearchWindow aligns the union of actual timestamps and retains values, presence, missing reasons, provenance and units. Duplicate claims raise errors. There is no interpolation, smoothing, resampling or filling. Native plotting returns line/scatter SVG, data and provenance.
+
+source가 모호하면 명시해야 합니다. `source_preference`는 첫 matching binding을 선택하며 장애 시 다른 source로 자동 fallback하지 않습니다. 기본 `artifact_resolution="all"`은 중복 주장을 보존합니다. 명시적 `preferred`는 우선순위 선택일 뿐 과학적 충돌 해결이 아닙니다. NRCan의 선언된 같은-source mergeable 제품은 함께 반환될 수 있습니다.
+
+Ambiguous sources require selection. Source preference selects the first matching binding, not runtime outage fallback. Default artifact resolution preserves claims; explicitly requested preferred selection is a priority policy, not scientific adjudication. Declared mergeable products within NRCan can be returned together.
+
+## Population과 historical orbit / Population and orbit
+
+```python
+with Archive(allow_dotenv=True) as archive:
+    candidates = archive.objects(
+        start="2024-05-10",
+        end="2024-05-11",
+        existence="throughout",
+        object_type="payload",
+        sync=True,
+    )
+    orbit = archive.orbit(norad_id=39452, start="2024-05-10", end="2024-05-11")
+    summary = archive.orbit_summary(
+        [39452],
+        start="2024-05-10",
+        end="2024-05-11",
+        periapsis_km=(200, 2000),
+        min_coverage=1.0,
+        sync=False,
+    )
+```
+
+기간 population은 전체 CelesTrak SATCAT의 launch/decay assertion으로 조회합니다. 기본 객체 검색은 로컬이며 `sync=True`로 SATCAT을 갱신합니다. historical orbit은 사용자 credential이 필요한 Space-Track GP_HISTORY이고 날짜 `[start,end)`입니다. 요약 coverage는 실제 레코드가 존재하는 날짜 비율이며 연속 관측을 뜻하지 않습니다.
+
+Period population applies launch/decay assertions from complete CelesTrak SATCAT. Default object searches are local; sync=True refreshes SATCAT. Historical orbit uses authenticated Space-Track GP_HISTORY with date-based [start,end). Summary coverage is the fraction of dates with records, not continuous observation.
+
+## Swarm와 MSIS / Swarm and MSIS
+
+Swarm A/B/C ACC·POD는 관측 기반 provider-derived 밀도이고 NRLMSIS 2.1은 별도 model_output입니다. trajectory는 UTC timestamp·경도/위도 degree·고도 km와 실제 provenance를 제공해야 합니다.
+
+Swarm A/B/C ACC/POD are observation-derived provider products; NRLMSIS 2.1 is separate model output. Supply trajectory UTC timestamps, longitude/latitude in degrees, altitude in kilometres and real provenance.
+
+```python
+# trajectory와 trajectory_parents 구성은 실행 예제를 참고하세요.
+# See the runnable example for trajectory and real parent construction.
+inputs, parents = archive.msis_inputs(
+    trajectory, driver_source="gfz", trajectory_parents=trajectory_parents
+)
+modeled = archive.msis_density(inputs, parents=parents)
+comparison = observed.merge(
+    modeled,
+    on="timestamp",
+    how="outer",
+    suffixes=("_observed", "_model"),
+    validate="one_to_one",
+    indicator=True,
+)
+```
+
+`msis_inputs()`는 명시적으로 GFZ를 선택해 이전 일 F10.7, 완전한 중심 81일 평균, 지정 Ap vector를 구성합니다. 필수 day/bin 누락과 중복 유효 forcing은 오류입니다. 모델 정의 평균은 관측 보간이 아니며 중심 평균은 미래 정보를 사용합니다. 모델 output은 backend/version·parameters·parent lineage를 저장합니다.
+
+Explicit GFZ forcing construction requires the previous-day F10.7, complete centered 81-day mean and defined Ap vector. Missing bins/days and duplicate valid drivers fail. Model-defined means are not observation interpolation; centered means use future information. Model output records versions, parameters and parent lineage.
+
+## 저장·확장 / Storage and extensions
+
+기본 저장소는 `~/.orbitoby`; import 전 `ORBITOBY_DATA_DIR`로 변경합니다. raw payload/manifest/SHA-256, DuckDB metadata, canonical Parquet와 derived/model Parquet를 분리하고 artifact·lineage로 연결합니다. `artifacts()`, `coverage()`, `product_store.lineage()`로 조사합니다.
+
+The default archive is ~/.orbitoby, overridable before import. Raw payloads/manifests/hashes, DuckDB metadata and canonical/derived/model Parquet are separate and linked by artifact IDs and lineage.
+
+HTTPS JSON/CSV/TSV declarative source를 등록하거나 명시적으로 신뢰한 `orbitoby.sources` Python plugin을 확장할 수 있습니다. canonical binding은 명시적으로 정의해야 하며 plugin은 사용자 권한으로 실행됩니다. credential은 runtime/keyring/environment/Colab/opt-in dotenv에서 해석하고 import만으로 .env를 로드하지 않습니다.
+
+Extensions include declarative HTTPS JSON/CSV/TSV and explicitly trusted Python source plugins. Canonical bindings must be explicit; plugins run with user permissions. Credential resolution supports runtime/keyring/environment/Colab/opt-in dotenv without implicit .env loading on import.
+
+## 실행 예제와 연결 검사 / Workflow and connection check
+
+저장소 root에서 순차 실행하세요. 예제는 전체 population→명시적 1개 위성의 historical orbit→F10.7/Kp/Ap/Dst/solar wind→Swarm→MSIS→exact 비교를 시연합니다. 실패 단계는 분리해서 보고합니다.
+
+Run sequentially from the repository root. The example demonstrates complete population, one explicitly selected historical orbit, weather indices, Swarm, MSIS and exact comparison, reporting stage failures separately.
+
+```bash
+.venv/bin/python examples/science_day.py --allow-dotenv
+.venv/bin/python scripts/check_connections.py --allow-dotenv
+```
+
+연결 검사는 source 수·API·DB/storage와 주요 provider를 PASS/FAIL/SKIP으로 표시하며 secrets를 출력하지 않습니다. credential 미설정은 SKIP, FAIL이 있으면 exit 1입니다. `--offline`, `--timeout 20`도 지원합니다. 연결 성공은 자료 전체의 완전성 인증이 아닙니다.
+
+Diagnostics report registry, APIs, local storage and key providers without secrets. Missing credentials are SKIP; any FAIL exits 1. Offline mode and per-worker timeout are available. Connectivity does not certify scientific completeness.
+
+## 제약·문서·인용 / Limits, documentation and citation
+
+현재 snapshot의 과거 존재 판정은 당시 catalogue 복원이 아닙니다. 결측 물리/임무 metadata, quality flag, provider revision, GP ID 중복, cache freshness를 사용자가 검토해야 합니다. orbit propagation·항력/인과적 decay·자동 cohort·범용 CLI는 제공하지 않습니다. E2E 성공과 과학적 타당성 검증은 구별합니다.
+
+Retrospective existence from a current snapshot is not a historical catalogue reconstruction. Researchers must assess missing metadata, quality, revisions, GP-ID deduplication and cache freshness. Propagation, drag/causal decay, automatic cohorts and a general CLI are outside this release. E2E success is distinct from scientific validation.
+
+- [한·영 위키 / Bilingual wiki](docs/wiki/index.md)
+- [전체 공개 API와 dataset / Complete inventory](docs/wiki/api-inventory.md)
+- [연구 예제 코드 / Research example](examples/science_day.py)
+- [검증 보고서 / Verification report](docs/RELEASE_0_1_0_REPORT.md)
+- [기능 동결 / Feature freeze](docs/adr/2026-10-04-release-freeze.md)
+
+소프트웨어 인용: Jin Yeseo, Orbitoby, 사용 버전과 [저장소](https://github.com/JIN-ARTLW/Orbitoby). dataset·model 문헌은 별도로 인용하세요. 확인되지 않은 DOI는 제시하지 않습니다. 코드 라이선스는 [Apache-2.0](LICENSE), 자산·외부 자료 구분은 [NOTICE](NOTICE)를 따릅니다.
+
+Cite Jin Yeseo, Orbitoby, the version used and the repository, plus original datasets and models. No unverified DOI is supplied. Code is Apache-2.0; NOTICE distinguishes assets and external materials.

orbitoby-0.1.0/SECURITY.md

@@ -0,0 +1,25 @@
+# 보안 정책 / Security policy
+
+현재 0.1.0 릴리스 후보를 준비 중입니다. 독립 보안 인증이나 모든 버전의 보안 지원을 주장하지 않습니다. 발견된 문제는 재현 증거와 영향 범위로 평가합니다.
+
+A 0.1.0 release candidate is being prepared. This is not independent security certification or a promise of security support for every version. Evaluate findings using reproducible evidence and impact.
+
+## 비밀정보와 확장 / Secrets and extensions
+
+사용자는 자신의 provider 계정을 사용합니다. `.env`, API key, password, token, 인증 쿠키와 비공개 archive를 공개하지 마세요. URL·manifest·notebook 출력에도 비밀을 넣지 않습니다.
+
+Users supply their own provider credentials. Do not publish `.env`, API keys, passwords, tokens, authentication cookies, or private archives. Keep secrets out of URLs, manifests, and notebook output.
+
+Python plugin의 명시적 trust는 sandbox가 아닙니다. 설치·업데이트할 코드를 검토하세요. `settings.json`의 `0600`은 다른 파일까지 보호한다는 뜻이 아닙니다.
+
+Explicit trust of a Python plugin is not a sandbox. Review code before installation or updates. Mode `0600` on `settings.json` does not protect every other file.
+
+## 취약점 제보 / Vulnerability reports
+
+민감한 내용이나 악용 절차를 공개 Issue에 올리지 말고 관리자에게 비공개로 제보하세요. 저장소는 [JIN-ARTLW/Orbitoby](https://github.com/JIN-ARTLW/Orbitoby)입니다. 비공개 신고 기능의 활성화 여부는 이 문서에서 확인했다고 주장하지 않습니다.
+
+Report sensitive details or exploit instructions privately to the maintainer rather than in a public issue. The repository is [JIN-ARTLW/Orbitoby](https://github.com/JIN-ARTLW/Orbitoby). This document does not claim that a particular private-reporting feature has been enabled.
+
+최소 재현, 영향 버전, 환경, 예상/실제 동작을 비밀값 없이 전달하세요. 실제 토큰이나 전체 사용자 DB를 첨부하지 않습니다.
+
+Provide a minimal reproduction, affected version, environment, and expected/actual behavior without secrets. Do not attach real tokens or a complete user database.