hybrid-recursive-ladder 0.0.6__tar.gz

hybrid_recursive_ladder-0.0.6/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.venv-*/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# Local configuration and data
+.env
+.env.*
+*.local
+data/
+*.db
+*.sqlite3

hybrid_recursive_ladder-0.0.6/.zenodo.json

@@ -0,0 +1,37 @@
+{
+  "title": "Hybrid Recursive Ladder: Query Planning for Bucket-Limited Time-Series APIs",
+  "description": "<p>A query-planning method for long-range time-series aggregation over APIs with a hard per-request bucket limit. The range is decomposed into complete calendar units; each maximal contiguous run sharing a fetch level is fetched once at the next finer aggregation and folded locally; optional coverage tracking fetches only uncovered sub-ranges.</p><p>This release is a public disclosure of the method and its formal properties. It is a composition of calendar mixed-radix decomposition, canonical interval decomposition, roll-up and multi-resolution aggregation. The code is released under the MIT License.</p>",
+  "creators": [
+    {
+      "name": "MagicSquarekey",
+      "affiliation": "Independent"
+    }
+  ],
+  "license": "MIT",
+  "upload_type": "software",
+  "access_right": "open",
+  "publication_date": "2026-10-27",
+  "version": "0.0.6",
+  "keywords": [
+    "time series",
+    "aggregation",
+    "query planning",
+    "downsampling",
+    "multi-resolution",
+    "ThingsBoard",
+    "observability"
+  ],
+  "related_identifiers": [
+    {
+      "identifier": "https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm",
+      "relation": "isSupplementTo",
+      "scheme": "url"
+    },
+    {
+      "identifier": "https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm/blob/main/docs/defensive-publication.md",
+      "relation": "isDocumentedBy",
+      "scheme": "url"
+    }
+  ],
+  "notes": "Public disclosure / prior art for the Hybrid Recursive Ladder query-planning method."
+}

hybrid_recursive_ladder-0.0.6/CHANGELOG.md

@@ -0,0 +1,175 @@
+# Changelog
+
+**语言 / Languages:** [English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.md)
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 0.0.1 onward.
+
+## [0.0.6] — 2026-10-27
+
+Documentation and site release. No algorithm, API, wire-format or storage
+changes.
+
+### Added
+
+* Zenodo archive and DOI: [10.5281/zenodo.23683292](https://doi.org/10.5281/zenodo.23683292).
+* Chinese versions for every document in the repository. All 14 prose documents
+  now have a `.zh-CN.md` mirror — including the API reference, architecture,
+  benchmarks, changelog, contributing guide and the agent skill — and the
+  prior-art matrix has a Chinese CSV.
+* `docs/README.md` / `docs/README.zh-CN.md`: a documentation index for every
+  document, project-level file and diagram in both languages.
+* `tools/check_docs_i18n.py`: fails CI when a document lacks a Chinese mirror,
+  a diagram lacks `zh-CN` SVG/PNG assets, or a new document is not registered.
+* An 11-language switcher on the documentation site, with `?lang=` deep links,
+  a saved preference, translated metadata and right-to-left layout for Arabic.
+
+### Changed
+
+* Every document carries an English / 简体中文 switch at the top.
+* Chinese documents use the Chinese diagrams; other languages keep the English
+  or their localized hero image.
+* On the site, Chinese mode links to the Chinese editions of the algorithm,
+  prior-art, article and disclosure pages.
+* Install snippets, badges, API examples and metadata now reference `0.0.6`.
+
+### Fixed
+
+* The benchmark table on the landing page no longer collapses: the badge rule
+  is scoped to cards and wide tables scroll horizontally.
+* Numeric ranges and arrows keep left-to-right order in the Arabic RTL layout.
+
+## [0.0.5] — 2026-10-26
+
+### Added
+
+* MCP tool annotations on all four tools: a human-readable `title` plus
+  `readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint`.
+  Clients can now tell that `ladder_meta` and `ladder_decompose` are local and
+  side-effect free, that `ladder_sum` can write to the local store through
+  `materialize=True`, and that `ladder_verify` reaches the source.
+* Per-language README diagrams. `docs/assets/hero.<lang>.png` ships for every
+  translated README, and `decomposition`/`architecture` are also localized for
+  Chinese. `tools/localize_assets.py` regenerates them from the English SVGs.
+
+### Fixed
+
+* `tests/test_mcp.py` now accepts the `(content, structured)` return value of
+  `call_tool` in current MCP SDK releases; the previous assertions failed on
+  `mcp` 1.27 and later.
+
+## [0.0.4] — 2026-10-22
+
+Documentation release. No code or algorithm changes. Reworks the READMEs and
+adds diagrams.
+
+### Added
+
+* Zenodo archive and DOI: [10.5281/zenodo.23557574](https://doi.org/10.5281/zenodo.23557574).
+
+### Changed
+
+* Reworked `README.md` and `README.zh-CN.md` into a single narrative with
+  diagrams for the before/after comparison, calendar decomposition and
+  local-first read path.
+* Added the hero diagram and DOI/website badges to the other language READMEs.
+* Bumped the package version to `0.0.4`.
+
+## [0.0.3] — 2026-10-22
+
+Archival release. No code or algorithm changes. This release triggers Zenodo's
+GitHub integration so the public disclosure receives a DOI.
+
+### Added
+
+* Zenodo archive and DOI: [10.5281/zenodo.23556606](https://doi.org/10.5281/zenodo.23556606).
+
+### Changed
+
+* Bumped the package version to `0.0.3` and updated citation, install and site
+  metadata for the archival release.
+
+## [0.0.2] — 2026-10-22
+
+Documentation and public-disclosure release. No algorithm semantics changed.
+
+### Added
+
+* `docs/defensive-publication.md`: a public disclosure of the method and its
+  formal properties as prior art.
+* `CITATION.cff` and `.zenodo.json`: citation and archive metadata.
+* `docs/articles/why-per-bucket-queries-are-slow.md` and its Chinese mirror: a
+  technical article with the production benchmark and prior-art framing.
+* `docs/index.html`: a static landing page for GitHub Pages.
+* `docs/publishing.md`: release, Zenodo, PyPI and distribution checklist.
+* `docs/related-work.md` and `docs/related-work.zh-CN.md`: prior-art
+  comparison, historical algorithms and a defensible novelty statement.
+* `docs/prior-art-search.zh-CN.md` and `docs/prior-art-matrix.csv`: a
+  repeatable prior-art/patent search plan and recording template.
+* Formal refinement-locality, segment-count and request-count propositions in
+  the algorithm specs.
+
+### Changed
+
+* Repositioned the project as a query-planning method for bucket-limited
+  time-series APIs (README, algorithm spec, package description).
+* Bumped the package version to `0.0.2` for the public-disclosure release.
+
+## [0.0.1] — 2026-10-22
+
+First standalone open-source release, extracted from AutoTestHub.
+
+### Added
+
+* Pure decomposition core (`month → day → hour → minute`) with configurable
+  finest level, IANA timezone support and a strict tiling invariant.
+* `LadderEngine` with source-only, local-only and local-first mixed reads.
+* Local materialization with coverage tracking, a 5-minute grace period and
+  rewrite-safe coverage invalidation.
+* Segment-level verification with point-level drilling (`added`, `removed`,
+  `changed`) and repair from the authoritative source.
+* `TimeSeriesSource` and `PointStore` protocols; adapters for ThingsBoard,
+  PostgreSQL, and in-memory use.
+* PostgreSQL schema with monthly partitions, idempotent upserts, batched range
+  sums and coverage tables (`hl_readings`, `hl_coverage`).
+* ThingsBoard adapter handling the 500-bucket limit, mid-bucket timestamps,
+  inclusive `endTs`, token refresh and error translation.
+* `hybrid-ladder` CLI: `decompose`, `demo`, `sum`, `verify`, `repair`,
+  `materialize`, `serve`, `mcp`, `version`.
+* FastAPI app with async tasks, progress, cancellation, synchronous variants
+  and the `{"code":0,"data":...}` envelope.
+* MCP server with `ladder_meta`, `ladder_decompose`, `ladder_sum` and
+  `ladder_verify` (supports MCP 1.x and 2.x).
+* Agent skill package under `skills/hybrid-recursive-ladder/`.
+* Deterministic demo data and an end-to-end `hybrid-ladder demo`.
+* 90+ tests covering decomposition, folding, mixed reads, materialization,
+  verification, repair, tasks, API, CLI, MCP, ThingsBoard and PostgreSQL.
+
+### Fixed (relative to the original AutoTestHub implementation)
+
+* **Multi-level fetch grouping.** Fetch runs are grouped by fetch level +
+  contiguity instead of adjacency only. The original fetched a whole
+  multi-level range at the coarsest level, which assigned a full day's value to
+  the first hour and lost the remaining hours/minutes.
+  Regression: `tests/test_engine.py::test_multilevel_query_is_exact`.
+* **Raw chunk boundary.** Bisection now uses `[a, mid)` and `[mid, b)` under the
+  exclusive-end contract. The original used `mid + 1`, dropping a point that
+  landed exactly on the split boundary.
+  Regression: `tests/test_engine.py::test_raw_split_keeps_boundary_point`.
+
+### Changed
+
+* PostgreSQL tables are namespaced (`namespace`, `entity`, `name`) and use a
+  configurable `table_prefix` instead of AutoTestHub's
+  `connection_id/device_id/device`.
+* `TaskRegistry` is reusable (multiple instances, TTL, max tasks) instead of a
+  module-level singleton.
+* The MCP tool layer and HTTP layer share one `runtime.engine_from_env()`.
+
+### Known limitations
+
+* Only the `sum` rule is implemented. `avg` and `meter_delta` need additional
+  aggregation semantics.
+* In-process task results are lost on restart (data is not).
+* The original AutoTestHub `device_id` migration is not automatic.

hybrid_recursive_ladder-0.0.6/CHANGELOG.zh-CN.md

@@ -0,0 +1,154 @@
+# 变更日志
+
+**语言 / Languages:** [English](CHANGELOG.md) · [简体中文](CHANGELOG.zh-CN.md)
+
+本文件记录项目的所有重要变更。格式遵循
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)，项目从 0.0.1 起使用
+[语义化版本](https://semver.org/spec/v2.0.0.html)。
+
+## [0.0.6] — 2026-10-27
+
+文档与站点发布。没有算法、API、线格式或存储变更。
+
+### 新增
+
+* Zenodo 归档与 DOI：[10.5281/zenodo.23683292](https://doi.org/10.5281/zenodo.23683292)。
+* 仓库内每份文档都有中文版。14 份说明文档全部有 `.zh-CN.md` 镜像，包括 API
+  参考、架构、基准、变更日志、贡献指南和智能体技能；先例矩阵也提供了中文
+  CSV。
+* `docs/README.md` / `docs/README.zh-CN.md`：中英双语的文档索引，覆盖所有
+  文档、项目级文件和示意图。
+* `tools/check_docs_i18n.py`：文档缺中文镜像、示意图缺 `zh-CN` SVG/PNG，
+  或新文档未登记时，CI 直接失败。
+* 文档站点支持 11 种语言切换：`?lang=` 深链、偏好记忆、标题/描述翻译，
+  阿拉伯语使用从右到左布局。
+
+### 变更
+
+* 每份文档顶部都有 English / 简体中文 切换。
+* 中文文档使用中文示意图；其他语言保留英文图或各自的 hero 图。
+* 站点中文模式下的算法、先例、文章和公开披露链接指向中文版。
+* 安装命令、徽章、API 示例和元数据更新到 `0.0.6`。
+
+### 修复
+
+* 落地页基准表格不再被压扁：徽章样式限定在卡片内，宽表格可横向滚动。
+* 阿拉伯语 RTL 布局下，数字区间和箭头保持从左到右的顺序。
+
+## [0.0.5] — 2026-10-26
+
+### 新增
+
+* 四个 MCP 工具都加了工具注解：人类可读的 `title`，以及
+  `readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`。
+  客户端现在可以判断：`ladder_meta` 和 `ladder_decompose` 是本地、无副作用
+  的；`ladder_sum` 在 `materialize=True` 时可能写本地存储；`ladder_verify`
+  会访问数据源。
+* 每种语言的 README 配图。每个翻译版 README 都有
+  `docs/assets/hero.<lang>.png`，`decomposition`/`architecture` 也提供了中文
+  版。`tools/localize_assets.py` 从英文 SVG 重新生成这些图。
+
+### 修复
+
+* `tests/test_mcp.py` 现在接受当前 MCP SDK 版本中 `call_tool` 返回的
+  `(content, structured)`；此前的断言在 `mcp` 1.27 及更高版本上失败。
+
+## [0.0.4] — 2026-10-22
+
+文档发布。没有代码或算法变更。重写 README 并增加示意图。
+
+### 新增
+
+* Zenodo 归档与 DOI：[10.5281/zenodo.23557574](https://doi.org/10.5281/zenodo.23557574)。
+
+### 变更
+
+* 把 `README.md` 与 `README.zh-CN.md` 重写为单一叙事，并加入前后对比、日历
+  分解和本地优先读路径的示意图。
+* 给其他语言 README 加入 hero 图和 DOI/网站徽章。
+* 包版本升到 `0.0.4`。
+
+## [0.0.3] — 2026-10-22
+
+归档发布。没有代码或算法变更。此发布触发 Zenodo 的 GitHub 集成，使公开披露
+获得 DOI。
+
+### 新增
+
+* Zenodo 归档与 DOI：[10.5281/zenodo.23556606](https://doi.org/10.5281/zenodo.23556606)。
+
+### 变更
+
+* 包版本升到 `0.0.3`，并更新引用、安装和站点元数据。
+
+## [0.0.2] — 2026-10-22
+
+文档与公开披露发布。算法语义未变。
+
+### 新增
+
+* `docs/defensive-publication.md`：方法及其形式化性质的公开披露，作为现有技术。
+* `CITATION.cff` 与 `.zenodo.json`：引用与归档元数据。
+* `docs/articles/why-per-bucket-queries-are-slow.md` 及其中文版：带生产基准和
+  现有技术定位的技术文章。
+* `docs/index.html`：GitHub Pages 静态落地页。
+* `docs/publishing.md`：发布、Zenodo、PyPI 与传播清单。
+* `docs/related-work.md` 与 `docs/related-work.zh-CN.md`：现有技术对比、历史
+  算法和可辩护的新颖性陈述。
+* `docs/prior-art-search.zh-CN.md` 与 `docs/prior-art-matrix.csv`：可重复的
+  现有技术/专利检索计划和记录模板。
+* 算法规范中的形式化细化局部性、段数和请求数命题。
+
+### 变更
+
+* 把项目重新定位为面向桶数受限时序 API 的查询规划方法（README、算法规范、
+  包描述）。
+* 包版本升到 `0.0.2`，用于公开披露发布。
+
+## [0.0.1] — 2026-10-22
+
+首个独立开源版本，从 AutoTestHub 抽离。
+
+### 新增
+
+* 纯分解核心（`month → day → hour → minute`），可配置最细层、IANA 时区支持和
+  严格的铺满不变量。
+* `LadderEngine`：纯源、纯本地和本地优先混合读。
+* 本地固化，带覆盖跟踪、5 分钟宽限期和重写安全的覆盖失效。
+* 段级校验与点级展开（`added`、`removed`、`changed`），以及从权威数据源修复。
+* `TimeSeriesSource` 与 `PointStore` 协议；ThingsBoard、PostgreSQL 和内存适配器。
+* PostgreSQL 表结构：月分区、幂等 upsert、批量区间求和和覆盖表
+  （`hl_readings`、`hl_coverage`）。
+* ThingsBoard 适配器：500 桶上限、半桶时间戳、包含端点的 `endTs`、token 刷新
+  和错误翻译。
+* `hybrid-ladder` CLI：`decompose`、`demo`、`sum`、`verify`、`repair`、
+  `materialize`、`serve`、`mcp`、`version`。
+* FastAPI 应用：异步任务、进度、取消、同步变体和 `{"code":0,"data":...}` 信封。
+* MCP server：`ladder_meta`、`ladder_decompose`、`ladder_sum`、`ladder_verify`
+  （支持 MCP 1.x 与 2.x）。
+* `skills/hybrid-recursive-ladder/` 下的 Agent 技能包。
+* 确定性演示数据和端到端 `hybrid-ladder demo`。
+* 90+ 个测试，覆盖分解、折叠、混合读、固化、校验、修复、任务、API、CLI、
+  MCP、ThingsBoard 和 PostgreSQL。
+
+### 修复（相对原 AutoTestHub 实现）
+
+* **多层级取数分组。** 取数 run 按取数层级 + 连续性分组，而不是只按相邻分组。
+  原实现把整个多层级区间按最粗层取数，把一整天的值赋给第一个小时，并丢掉其余
+  小时/分钟。回归测试：`tests/test_engine.py::test_multilevel_query_is_exact`。
+* **原始点分块边界。** 在左闭右开契约下，二分改为 `[a, mid)` 与 `[mid, b)`。
+  原实现用 `mid + 1`，会丢掉正好落在分块边界上的点。回归测试：
+  `tests/test_engine.py::test_raw_split_keeps_boundary_point`。
+
+### 变更
+
+* PostgreSQL 表使用命名空间（`namespace`、`entity`、`name`），并支持可配置的
+  `table_prefix`，替代 AutoTestHub 的 `connection_id/device_id/device`。
+* `TaskRegistry` 可复用（多实例、TTL、最大任务数），不再是模块级单例。
+* MCP 工具层与 HTTP 层共享一个 `runtime.engine_from_env()`。
+
+### 已知限制
+
+* 只实现 `sum` 规则。`avg` 和 `meter_delta` 需要额外的聚合语义。
+* 进程内任务结果在重启后丢失（数据不丢）。
+* 原 AutoTestHub 的 `device_id` 迁移不是自动的。

hybrid_recursive_ladder-0.0.6/CITATION.cff

@@ -0,0 +1,28 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "Hybrid Recursive Ladder: Query Planning for Bucket-Limited Time-Series APIs"
+abstract: >-
+  A query-planning method for long-range time-series aggregation over APIs with
+  a hard per-request bucket limit. The range is decomposed into complete
+  calendar units; each maximal contiguous run sharing a fetch level is fetched
+  once at the next finer aggregation and folded locally; optional coverage
+  tracking fetches only uncovered sub-ranges. The method is a composition of
+  calendar mixed-radix decomposition, canonical interval decomposition, roll-up
+  and multi-resolution aggregation.
+authors:
+  - family-names: "MagicSquarekey"
+    alias: "MagicSquarekey"
+version: "0.0.6"
+doi: "10.5281/zenodo.23683292"
+date-released: "2026-10-27"
+license: "MIT"
+repository-code: "https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm"
+url: "https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm"
+keywords:
+  - "time series"
+  - "aggregation"
+  - "query planning"
+  - "downsampling"
+  - "multi-resolution"
+  - "ThingsBoard"
+  - "observability"

hybrid_recursive_ladder-0.0.6/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing
+
+**语言 / Languages:** [English](CONTRIBUTING.md) · [简体中文](CONTRIBUTING.zh-CN.md)
+
+Thanks for considering a contribution. This project values correctness and
+clarity over feature count: the algorithm's guarantees are the product.
+
+## Development setup
+
+```bash
+git clone https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm.git
+cd hybrid_recursive_ladder_algorithm
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+Optional PostgreSQL integration tests:
+
+```bash
+export HL_TEST_PG_DSN='postgresql://user:pass@127.0.0.1:5432/testdb'
+pytest -m integration
+```
+
+The integration test uses a unique `namespace` and the `hl_test_` table prefix;
+it cleans its rows after each test.
+
+## What to run before opening a PR
+
+```bash
+ruff check .
+pytest
+python examples/benchmark.py       # segment/request counts should stay stable
+```
+
+If you change algorithm semantics, update `docs/algorithm.md`,
+`docs/algorithm.zh-CN.md` and the relevant test in the same PR.
+
+## Commit messages
+
+Conventional Commits are preferred:
+
+```
+feat(engine): add max/min folding
+fix(core): keep boundary point on raw bisection
+docs(api): document sync endpoints
+test(mixed): cover grace-period clamping
+```
+
+Keep a commit focused. A bug fix should include a regression test that fails
+before the fix.
+
+## Adding a source adapter
+
+1. Implement `interval_agg` and `raw_series` from
+   `hybrid_ladder.protocols.TimeSeriesSource`.
+2. Return `{bucket_start_ms: value}` from `interval_agg`; normalize any
+   mid-bucket timestamps your source uses.
+3. Enforce `[start, end)` and ascending order in `raw_series`; return at most
+   `limit` points.
+4. Keep credentials out of logs and error messages.
+5. Add tests with `httpx.MockTransport` (for HTTP sources) or a deterministic
+   fixture. Cover: bucket normalization, chunking, auth, error translation and
+   the exclusive end.
+
+## Adding a store adapter
+
+1. Implement the seven methods from `hybrid_ladder.protocols.PointStore`.
+2. Return `(None, 0)` for an empty range and `(0.0, n)` for a zero-valued
+   range. This distinction is a core guarantee.
+3. Make `upsert_points` idempotent on `(entity, key, ts)`.
+4. `clear_coverage` must remove overlapping coverage rows before a rewrite.
+5. `series` may paginate internally; `max_points` is a page size, not a cap.
+6. Add an opt-in integration test gated by an environment variable.
+
+## Code style
+
+* Python 3.10+, type hints on public functions.
+* Line length 100, `ruff` with the configured rule set.
+* The core (`core.py`) must remain free of I/O and third-party dependencies.
+* Prefer explicit names over abbreviations; comments should explain
+  constraints, not restate code.
+
+## Documentation
+
+* Every prose document ships with a `.zh-CN.md` mirror; every diagram ships
+  with a `zh-CN` SVG and PNG. Run `python tools/check_docs_i18n.py` (also
+  enforced in CI) before opening a PR.
+* English is the primary README; keep `README.zh-CN.md` in sync when behavior
+  changes.
+* API changes require an update to `docs/api.md` and `docs/api.zh-CN.md`.
+* Add benchmarks only with methodology and caveats; never present a
+  single-machine number as a guarantee.
+* README diagrams are language-specific: `docs/assets/<name>.<lang>.png` is
+  rendered from the English `docs/assets/<name>.svg` by
+  `python tools/localize_assets.py`. After editing an SVG or a translation,
+  re-run it; `--check` reports strings that have no translation yet.
+
+## Release process
+
+1. Update `CHANGELOG.md` and the version in `pyproject.toml`.
+2. Run `ruff check .`, `pytest`, and `python -m build`.
+3. Commit, tag (`vX.Y.Z`), and push the tag. The `release.yml` workflow builds
+   the distributions and creates the GitHub release.
+4. If PyPI publishing is enabled, use trusted publishing with the `pypi`
+   environment.
+
+## Reporting issues
+
+Please include:
+
+* the range and `finest` level,
+* the source type and adapter version,
+* the expected and actual totals/segment counts,
+* whether the local store was involved (`source` / `source_counts`),
+* a minimal reproduction when possible.
+
+Never include credentials or production data in an issue.

hybrid_recursive_ladder-0.0.6/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,114 @@
+# 贡献指南
+
+**语言 / Languages:** [English](CONTRIBUTING.md) · [简体中文](CONTRIBUTING.zh-CN.md)
+
+感谢你考虑贡献。这个项目更看重正确性和清晰度，而不是功能数量：算法的保证就是
+产品本身。
+
+## 开发环境
+
+```bash
+git clone https://github.com/MagicSquarekey/hybrid_recursive_ladder_algorithm.git
+cd hybrid_recursive_ladder_algorithm
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+ruff check .
+pytest
+```
+
+可选的 PostgreSQL 集成测试：
+
+```bash
+export HL_TEST_PG_DSN='postgresql://user:pass@127.0.0.1:5432/testdb'
+pytest -m integration
+```
+
+集成测试使用唯一的 `namespace` 和 `hl_test_` 表前缀；每个测试后会清理自己的行。
+
+## 开 PR 前要跑什么
+
+```bash
+ruff check .
+pytest
+python examples/benchmark.py       # 段数/请求数应保持稳定
+python tools/check_docs_i18n.py    # 每份文档/示意图都要有中文版
+```
+
+如果改动了算法语义，请在同一个 PR 中更新 `docs/algorithm.md`、
+`docs/algorithm.zh-CN.md` 和相关测试。
+
+## 提交信息
+
+推荐使用 Conventional Commits：
+
+```
+feat(engine): add max/min folding
+fix(core): keep boundary point on raw bisection
+docs(api): document sync endpoints
+test(mixed): cover grace-period clamping
+```
+
+保持每次提交聚焦。Bug 修复应包含一个在修复前会失败的回归测试。
+
+## 新增数据源适配器
+
+1. 实现 `hybrid_ladder.protocols.TimeSeriesSource` 的 `interval_agg` 和
+   `raw_series`。
+2. `interval_agg` 返回 `{bucket_start_ms: value}`；如果你的数据源使用半桶时间
+   戳，归一化它。
+3. `raw_series` 强制 `[start, end)` 和升序；最多返回 `limit` 个点。
+4. 不要把凭据写进日志或错误信息。
+5. 用 `httpx.MockTransport`（HTTP 数据源）或确定性 fixture 加测试。覆盖：桶
+   归一化、分块、认证、错误翻译和排除端点。
+
+## 新增存储适配器
+
+1. 实现 `hybrid_ladder.protocols.PointStore` 的七个方法。
+2. 空区间返回 `(None, 0)`，零值区间返回 `(0.0, n)`。这个区分是核心保证。
+3. 让 `upsert_points` 在 `(entity, key, ts)` 上幂等。
+4. `clear_coverage` 必须在重写前删除重叠的覆盖行。
+5. `series` 可以在内部翻页；`max_points` 是页大小，不是上限。
+6. 加一个由环境变量控制的选择性集成测试。
+
+## 代码风格
+
+* Python 3.10+，公开函数加类型标注。
+* 行宽 100，使用配置好的 `ruff` 规则。
+* 核心（`core.py`）必须保持无 I/O、无第三方依赖。
+* 优先使用明确的命名而不是缩写；注释应解释约束，而不是复述代码。
+
+## 文档
+
+* 英文是主要 README；行为变化时同步更新 `README.zh-CN.md`。
+* **每一份说明文档都必须有中文版**：英文文件 `foo.md` 配套 `foo.zh-CN.md`；
+  中文文件也要在顶部放语言切换链接。
+* **每一张示意图都必须有中文版**：`docs/assets/<name>.svg` 配套
+  `<name>.zh-CN.svg` 和 `<name>.zh-CN.png`。README 图由
+  `python tools/localize_assets.py` 从英文 SVG 生成；改完 SVG 或翻译后重跑，
+  `--check` 会报告还没有翻译的字符串。
+* API 变化需要同时更新 `docs/api.md`、`docs/api.zh-CN.md` 和
+  `CHANGELOG.md`。
+* 基准数据必须附方法和注意事项；不要把单机数字说成保证。
+* 提交前运行 `python tools/check_docs_i18n.py`（CI 也会跑）。
+
+## 发布流程
+
+1. 更新 `CHANGELOG.md`、`CHANGELOG.zh-CN.md` 和 `pyproject.toml` 中的版本。
+2. 运行 `ruff check .`、`pytest`、`python examples/benchmark.py` 和
+   `python tools/check_docs_i18n.py`。
+3. 提交、打 tag（`vX.Y.Z`）、推 tag。`release.yml` 工作流会构建分发包并创建
+   GitHub Release。
+4. 如果启用了 PyPI 发布，使用 `pypi` 环境和 trusted publishing。
+
+## 报告问题
+
+请包含：
+
+* 区间和 `finest` 层级；
+* 数据源类型和适配器版本；
+* 预期与实际合计/段数；
+* 是否涉及本地存储（`source` / `source_counts`）；
+* 尽可能提供最小复现。
+
+永远不要在 issue 中包含凭据或生产数据。

hybrid_recursive_ladder-0.0.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicSquarekey
+
+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.