axiolune 0.6.0__py3-none-any.whl

axiolune/ALLOCATION-SPECS.md

@@ -0,0 +1,84 @@
+# 等权与 top-k 目标分配
+
+`axiolune.allocations.evaluate_allocations` 在已有 `Frame` 上执行布尔选择和可选的 Decimal 评分，再生成精确、无量纲的目标权重。输出包含所有输入成员、未入选原因、分配分母和未分配比例。依赖 `[local]`；表达式仍由现有 Polars 或 DuckDB 执行。
+
+## 使用已有固定来源
+
+以下代码使用调用者已有的 TAIFEX 可接受政府债券快照 `snapshot_id` 与 `store`。它给来源清单成员分配等权，属于来源分析；清单成员身份和投资适用性须分别审查。
+
+```python
+from axiolune.allocations import (
+    AllocationBudget, AllocationRule, AllocationSpec, evaluate_allocations,
+)
+from axiolune.typed_frame import DType, FieldBinding, Frame, FrameContract, Order
+
+source = store.read(snapshot_id)
+contract = FrameContract(
+    "my-research.collateral-members", "1",
+    source.receipt.dataset_id, source.receipt.actual_provider,
+    (
+        FieldBinding("Date", "source_date", DType("text"), "identity", False),
+        FieldBinding("Code", "source_code", DType("text"), "identity", False),
+    ),
+    ("source_date", "source_code"),
+)
+frame = Frame.from_snapshot(store, snapshot_id, contract=contract)
+spec = AllocationSpec(
+    definition_id="my-research.equal-members", version="1",
+    selection=frame.column("source_code").eq(frame.column("source_code")),
+    group_by=("source_date",), member_key=("source_code",),
+    order=Order(("source_date", "source_code")),
+    rule=AllocationRule(
+        method="equal_weight", maximum_weight="1/10", unknown_selection="reject",
+    ),
+)
+result = evaluate_allocations(
+    frame, spec, engine="duckdb",
+    budget=AllocationBudget(max_rows=10_000, max_bytes=16 * 1024 * 1024),
+)
+print(result.groups.to_pylist())
+print(result.members.to_pylist())
+portable_spec = spec.to_dict()
+assert AllocationSpec.from_dict(portable_spec).to_dict() == portable_spec
+```
+
+此例的 `1/10` 是调用者明确选择的单成员上限，不是市场规则或包内费用假设。已有非空代码的自等比较选择全部来源成员；实际策略可以使用同一 Frame 的其他已类型检查布尔表达式。金额、货币、交易手数、价格、成交、交收和账户变动均由后续消费者明确提供，不能从这些权重推断。
+
+## 分配合同
+
+`AllocationSpec` 固定 `definition_id`、显式 `version`、Frame 来源摘要、选择/评分的完整 AST、分组列、成员键、唯一输出顺序和 `AllocationRule`。`to_dict/from_dict` 使用闭字段版本 1 合同。定义版本为调用者原生版本文字；改变定义应同时变更其版本，内容摘要始终独立保留。
+
+每个分组中成员键必须唯一且非 null。一个成员可在不同分组重复出现；每个分组独立确定分母。分组可以为空元组，此时全部行属于一个分组。空输入返回有固定 schema 的空组表和成员表。顺序复用 `Frame.collect` 的完整唯一 `Order`；输入行排列不会替代显式顺序。
+
+| 规则字段 | 行为 |
+|---|---|
+| `method="equal_weight"` | 对选择结果为 true 的成员等权；评分字段和 top-k 策略必须为空。 |
+| `method="top_k"` | 仅对选择为 true、评分非空的成员排序，使用显式 `top_k` 与 `descending_score`。评分须为有单位声明的 Decimal 表达式；零与负值正常参与。 |
+| `unknown_selection` | `exclude` 保留成员并记录 `selection_unknown`；`reject` 拒绝整个调用。false 固定记录 `selection_false`。 |
+| `missing_score` | top-k 候选评分缺失时，`exclude` 记录 `score_missing`，或 `reject` 拒绝调用。已经因选择被排除的成员不会参与评分缺失判断。 |
+| `boundary_ties` | `order` 用明确顺序选足 k 个；`include` 纳入所有与第 k 名同分的成员，因此可能超过 k；`reject` 在边界同分时拒绝。 |
+| `maximum_weight` | 正、约分后、至多为一的 `分子/分母` 字符串，两操作数各不超过 128 bit。没有浮点权重或隐式舍入。 |
+
+最终选择 n 个成员时，每个权重为 `min(maximum_weight, 1/n)`；未选择成员为 `0/1`。未分配比例为 `1 − n × 单成员权重`，不会将受上限限制的残余再次摊给其他成员。n 为零时保留 `1/1` 未分配。top-k 大于有效候选数时使用全部有效候选；分母由实际最终选择集合确定。
+
+例如 k=1、首位两个成员同分时，`include` 选择两个成员，单成员上限允许时各 `1/2`；`order` 依显式顺序只选择第一个。`score_position` 是按评分与显式顺序得到的一基位置，用于解释选择，不是共享同分名次。
+
+## 输出与来源
+
+- `result.groups`：每组总数、有效候选数、最终选择数、未选择数、边界扩展数、单成员权重、分配比例、未分配比例、状态和排除原因计数。
+- `result.members`：所有输入行的顺序、原行键、组键、成员键、三态选择、原 Decimal 评分文字、候选/选择状态、原因、精确权重和评分位置。键使用现有带类型编码，日期与文本不会合并。
+- `result.receipt`：不可变规格、完整输入收据与 lineage、资格、两个表的内容摘要和总结果摘要、实际引擎信息及预算。`to_arrow()` 返回两个原 Arrow 表和可独立编辑的收据副本。
+
+结果内容摘要固定实际输入/规格/有序表值，排除运行耗时和物理引擎计划；两个引擎在合同交集内得到相同逻辑结果时摘要相同。评分可以来自现有排名等 AST；分配模块不另写一个评分引擎。来源清单和观察日期不会自动成为规范证券身份或合法交易会话。
+
+## 预算和资格
+
+`AllocationBudget` 集中定义行数、组数、累计表示字节、单份 metadata 上限和性能计数器超时；行数和总字节与原 Frame 上限取较小值。metadata 在 canonical JSON 分配之前进行保守的转义 UTF-8、节点和深度预检。累计字节记录实际显式序列化的中间表示、Arrow 缓冲区与有序行哈希输入；同一数据的多种表示各自计入。receipt 中的 `admitted_representation_bytes_before_final_receipt` 明确不包含该最终收据自身；最终收据另外接受同一预算检查。
+
+这些计数不表示 Python 进程 RSS 或操作系统硬实时上界。既有表达式引擎调用完成后会检查 deadline，逐成员分配和内容哈希也有检查点；此接口不会强行中断引擎内部的同步调用。
+
+默认 `purpose="source_analysis"` 保留现有来源资格；`strict_research` 仍要求相应输入资格。权重本身不建立历史市场可知时间、合法下一会话、价格限制或交易能力。P4 的目标转订单、有效期市场规则、共享账本及 Paper 账户继续按各自实际合同接入。
+
+## 验证
+
+`validation/allocations.py` 使用单独的原创数学说明核对等权、上限残余、未知值、缺失评分、零/负/大 Decimal、同分三种策略、重复成员及预算拒绝。真实来源轮在保留原件的独立副本上执行政府债券成员与外汇观察成员，逐行核对两个引擎的结果和来源摘要；外汇日期成员只用于验证排序分配，不充当可交易资产。验证器禁止网络，并在前后核对原来源目录及运行文件的字节摘要。

axiolune/BROKER-PORT.md

@@ -0,0 +1,71 @@
+# Optional paper execution port
+
+`axiolune.broker.BrokerPort` is a small Python protocol for explicit submission,
+cancellation, outcome application, status queries and report reconciliation.
+The shipped `LedgerPaperBroker` adapter binds one existing `Session.ledger`
+paper account. It has no network transport or external credentials, and its
+capabilities always report `live_execution_enabled=False`. A conforming plugin
+does not gain automatic execution authorization or become automatically loaded.
+
+```python
+from axiolune.broker import BrokerPort, LedgerPaperBroker
+
+broker: BrokerPort = LedgerPaperBroker(session.ledger, paper_account_id)
+print(broker.capabilities())
+
+# Existing target_orders.prepare_paper_orders or original ledger admission.
+accepted = broker.submit(prepared_orders.command)
+status = broker.query(prepared_orders.command["command_id"])
+
+# Existing paper_matching.prepare_paper_match produces this exact command.
+outcome = broker.apply_reports(prepared_match.command)
+order = broker.order(order_id)
+page = broker.reports(after_sequence=0, limit=100)
+comparison = broker.reconcile(page["events"], through_head=page["through_head"])
+```
+
+The original shared ledger remains the order, quantity, cash, position, obligation
+and event authority. `submit` accepts its ordinary `OrderDeclared` or
+`FuturesOrderDeclaredV1`; `cancel` accepts `OrderRemainderCancelled` or
+`FuturesOrderCancelledV1`; `apply_reports` accepts the existing retained paper
+recognition/settlement events. Funding, original record admission, model retention
+and source matching retain their existing APIs. Source quotes are not converted
+into account executions by this adapter.
+
+All mutation methods preserve the caller's complete command, command ID, event
+IDs, actor declaration and expected account head. They accept the original
+`expected_plan_sha256`, `LedgerBudget` and cancellation event. Exact retries return
+the original result without another order; changed bytes under a committed ID
+raise `CommandIdentityConflict`. The adapter shares the core invocation meter and
+uses the existing atomic commit path.
+
+If SQLite reports an inconclusive commit, the response has `status="unknown"`
+and retains the original command ID/request digest. Query that ID; never invent
+a replacement ID because an acknowledgement was lost. `query` returns
+`committed` or `not_observed`. The latter does not prove a concurrent invocation
+will never commit. Wait for that invocation to finish, then retry only the exact
+original command if needed. A lost HTTP/client response would use the same query
+discipline; no external broker transport is supplied here.
+
+Cancellation declares the exact remaining quantity against a specific head.
+If a fill commits first, stale cancellation fails with `LedgerRevisionConflict`.
+Read the actual order, then explicitly prepare a new cancellation of its remaining
+quantity. Already executed quantity is never rolled back by cancellation. The
+reverse race uses the same CAS and remainder checks. `order` projects the shared
+state as open, partially filled, partially cancelled, filled or cancelled while
+always returning exact requested/executed/cancelled/remaining values.
+
+Reports are the existing immutable ledger event pages, including nontrade account
+events so the sequence stays continuous. A consumer stores its own cursor and
+pins `through_head` across pages. `reconcile` accepts a bounded page of event
+envelopes in any delivery order, tolerates exact duplicate deliveries, and reports
+missing, unexpected or differing event IDs. It compares original bytes/hashes;
+it never alters the account to agree with an incoming callback. A matched page
+does not imply every page was received. Use `ledger.replay` for complete account
+semantic reconciliation and its existing accounting invariants.
+
+The local proof used the original September 21 paper order prefix and a genuine
+later retained Gemini print in a new private copy. It recomputed paper fills and
+cancelled the remainder on October 4; it did not redate a fresh order or claim a
+current-market execution. No original source/evidence bytes changed, no provider
+request was made, and no real order was sent.

axiolune/COMPANY_RESEARCH.md

@@ -0,0 +1,130 @@
+# 公司研究
+
+公开入口为 `axiolune.company_research`，使用现有 `Session` 和
+`FinancialQuerySpec`；需要 `financial` 依赖。没有另设行情抓取器、财务内核或数据库。
+
+当前源码另提供[原生三表绑定准备器](SOURCE-FINANCIAL-BINDINGS.md)：
+`company inspect-bindings/prepare` 与 `source_financials.prepare_company` 支持显式大陆宽表、
+港股长表及其他 JSON 财报映射。该增量已包含在 a18 中；未知源存储/共享资格仍不获授权。
+
+```python
+from axiolune.company_research import (
+    CompanyInput, CompanyResearch, ValuationAssumptions,
+)
+
+# financial_query 是固定财报快照、来源指针、声明证据及运算组成的 FinancialQuerySpec。
+# 所有非空别名必须是 financial_query.outputs 中的节点。
+company = CompanyInput(
+    entity_id="sec:cik:0000320193",
+    query=financial_query,
+    metrics={"income": "net_income", "revenue": "revenue",
+             "outstanding": "instant_common_shares", "unknown_claim": None},
+)
+research = CompanyResearch(session).evaluate(
+    company,
+    assumptions=assumptions,  # ValuationAssumptions；可省略以只做财务研究
+    peers=peer_inputs,
+    compare=("income", "revenue"),
+    comparison_period_policy="exact",
+)
+document = research.to_dict()
+```
+
+已有财务查询支持的单季、TTM、利润率、负债比例、平均资产/权益回报及每股收益，
+继续放在 `FinancialQuerySpec` 中计算。公司研究保留完整财务 receipt、原始 fact/output
+身份、期间、单位、来源快照和 Citation，不把调用方的会计口径声明升级为业务认证。
+
+同业必须是不同实体。默认比较相同概念、期间、币种/单位、会计基础和合并范围。
+不相容或缺失的行保留数值与排除原因，同行中位数排除研究主体。显式选择
+`fiscal_year_end_year` 时，也允许同一公历年结束、长度 330–400 天的年度报告期间；
+原始日期及金额均保留，不声称已经对齐经营月份或按年化处理。别名不会自动使不同概念等价。
+
+## 估值假设
+
+`ValuationAssumptions` 要求作者、带时区的创建时间、理由、币种、估值日、资产负债表日、
+会计基础/范围、流通股数别名和股本口径说明。金额、倍数和利率只接收有限 `Decimal`。
+序列化为十进制字符串，`from_dict()` 可还原，`version_id` 固定完整假设内容。
+`revise(author=..., created_at=..., rationale=..., multiple=...)` 产生引用旧版本哈希的新版本。
+
+三种方法：
+
+- `equity_multiple`：`metric × multiple` 直接得到股权价值；输入为声明的期间货币指标。
+- `enterprise_multiple`：先得到企业价值，再使用逐项价值桥。
+- `dcf_fcff`：1–40 个显式年度、年末支付的基础币种 FCFF 假设，按
+  `discount_rate` 折现。`terminal_growth` 非空时使用 Gordon 永续增长，并要求
+  `-1 < g < r`；空值明确表示不计终值。模块不把净利润或经营现金流自动当作 FCFF。
+
+`BridgeLine(metric, sign, explanation)` 逐项加回非经营资产或扣除债权等索取权。
+每个余额和实际流通股数须是同一资产负债表日的时点事实，单位可以显式缩放。
+`bridge_complete` 与 `bridge_policy` 说明本次假设覆盖哪些项目、哪些被排除；
+不完整桥或任何缺失项目使股权/每股价值保持未知。没有默认零负债、隐式汇率或隐式稀释。
+期间加权平均股数会被拒绝作为时点估值分母。终值、价值桥和每股价值均有计算及输入回链。
+负数盈利的常规正倍数估值显示不适用；未人为截断负的 DCF 股权情景结果。
+
+例如倍数敏感性传入
+`sensitivity={"multiple": [Decimal("15"), Decimal("20"), Decimal("25")]}`；
+DCF 可同时传入 `discount_rate`、`terminal_growth` 两个轴，最多 121 个情景。
+每格保留假设版本与原始假设父版本。非法组合直接拒绝，缺失输入保留未知。
+中间运算用精确有理数，最终显示调用共享财务内核的 `ROUND_HALF_EVEN` 舍入。
+
+## 研究对象和 Run
+
+`research.research_content(question=...)` 可交给现有 `team.research.create`、
+`save_draft`、`freeze`。`research.save_research(team, project_id=..., title=...,
+question=..., idempotency_key=...)` 是现有创建 API 的薄封装，仍由团队 API 管理权限和修订。
+派生研究内容不会授予来源发布许可。
+
+`CompanyInput.source_run_id` 可指定已有成功的财务 Run；此时 `evaluate(..., team=team)`
+通过已认证团队 API 及原 Artifact reader 检查完整财务 receipt、Run、revision、environment
+和 input 身份是否与本次实际求值相同，并记录 resource/Run/Artifact 引用。
+该引用明确属于**输入财务计算**，不声称既有 Run 执行过后来新增的估值假设。
+需要后台执行时，用 `CompanyResearchSpec` 将公司、同业、估值假设和敏感性网格放入现有
+`ResearchBundleSpec`。方法名为 `company_research_with_evidence`，由现有 query worker
+调度；继续使用原 Run 的租约、取消、权限、环境身份、版本和 Artifact 保存端口。
+
+```python
+from axiolune.company_research import CompanyResearchSpec
+
+spec = CompanyResearchSpec(company, assumptions=assumptions, peers=tuple(peer_inputs),
+                           compare=("income", "revenue"))
+# published_inputs 是既有 BundleRef 序列，覆盖 spec.required_refs 及来源父引用闭包。
+# environment_id 对应实际执行环境；输入须已按现有权限和来源条款发布。
+published_inputs = spec.publish_inputs(session, team, project_id=project_id,
+                                      allowed_actors=actual_actor_ids)
+run = spec.submit(team, inputs=published_inputs, project_id=project_id,
+                  title="公司估值", question="当前假设对应的价值与同业差异？",
+                  environment_id=environment_id, idempotency_key=request_key)
+state = team.runs.status(run_id=run["id"])
+saved = CompanyResearchSpec.result(team, run_id=run["id"])
+```
+
+现有 `python -m axiolune.adapters.workers query` 执行该任务；参数沿用 worker 帮助。
+`result()` 在未完成时返回真实状态和空结果，成功后返回研究修订、Run、Artifact 及结果。
+重现继续使用 `team.runs.reproduce`。结果内容不含本次执行墙钟时间，因此相同固定输入可以
+比较完整表和内容身份；实际执行时间保留在外层 Run。完成校验会重新读取来源并计算完整结果。
+排队的 `CompanyInput.source_run_id` 必须为空；此任务自己的 Run 记录本次执行。
+手动保存的 `research_content()` 是派生研究文档，后台可执行形式是上述 Spec。
+
+## 实际例子
+
+`validation/company_research.py` 在私有存储副本运行。2026-09-21 的实际结果位于
+`build/package-system/company-research-20260921/`：
+
+- `example-inputs.json`：可用 `CompanyInput.from_dict`、`ValuationAssumptions.from_dict` 重载。
+- `company-result.json`、`dcf-result.json`：两家公司实际财报输入与明确标注的估值情景。
+- `report.json`：15 项实际检查，包括独立高精度 Decimal 估值计算和来源回链。
+
+苹果使用已保留的 FY2025 原件；微软使用实际 SEC companyfacts 响应
+`f8aae2965b20ad0df44bdf7ccbedf797d275b6b8dc030154a7a311361bb7246f`。
+验证执行本身离线，前置微软采集为一次真实公开 HTTP 获取。
+示例的倍数、FCFF、折现率和终值增长率是作者假设，不是市场观测。
+上述首轮只验证本地计算。后续 `validation/company_research_run.py` 已通过真实 TCP、
+PostgreSQL、团队研究保存、现有 query worker、Artifact 完成校验和一次 Run 重现。
+结果位于 `build/package-system/company-research-run-20260921-r3/report.json`：
+15 个实际输入引用，两个成功 Run 的结果内容和 Parquet 表一致，业务 HTTP 为零。
+该后台例子仅使用可分享的发行人财报及所需指标；旧例子中未获分享许可的私有方法说明
+仍被现有权限拒绝，原失败保留。验证后私有 PostgreSQL 已停止。
+
+方法来源：[SEC 财报 API 的单位与期间说明](https://www.sec.gov/search-filings/edgar-application-programming-interfaces)、
+[Damodaran 估值课程](https://pages.stern.nyu.edu/~adamodar/New_Home_Page/lectures/val.html)、
+[企业价值与每股价值](https://pages.stern.nyu.edu/adamodar/New_Home_Page/littlebook/valuepershare.htm)。

axiolune/DATA-READINESS.md

@@ -0,0 +1,84 @@
+# 已加载数据的刷新就绪状态
+
+`s.data.readiness(as_of=...)` 返回可 JSON 序列化摘要；`is_tradable`、
+`next_future_expiry`、`suggested_tradable_time` 复用同一核。
+后两者返回 UTC `datetime | None`。调用只读，不联网、不刷新、不创建调度任务。
+`as_of` 必須显式提供带时区时间；系统不猜市场、开盘时间、节假日或发布计划。
+
+成功的 `fetch`、`read`、`import_file`、`import_sql` 自动登记当前会话实际加载的
+receipt；失败获取不会登记。登记只留 receipt，不复制数据，不改变现有缓存。
+对返回对象留弱引用，供只读来源字段绑定核对；不会延长数据对象寿命。
+每个 input_id 同时包含 dataset、provider、实际参数、返回字段与来源合同版本，
+因此两个不同参数请求不是同一个所需输入。新的成功读取替换同一 input_id 的旧记录。
+索引受 Session 行/字节预算限制；被淘汰的所需输入明确报告 input_not_loaded。
+
+```python
+summary = s.data.readiness(as_of=observed_clock)
+input_id = summary["inputs"][0]["input_id"]
+requirements = {
+    input_id: {
+        "refresh_after": publisher_required_refresh_utc,
+        "next_update_at": publisher_next_update_utc,
+        "evidence": publisher_schedule_reference,
+        "publication": {"kind": "data_cutoff", "precision": "date", "at": required_data_date},
+    }
+}
+summary = s.data.readiness(
+    as_of=observed_clock, required=requirements, market_open=next_open_utc,
+    publications={input_id: {
+        "result": loaded_result, "field": original_source_date_field,
+        "partition_by": original_source_series_keys,
+        "evidence": publisher_field_definition_reference,
+    }},
+)
+```
+
+声明中的时间用带时区 ISO 字符串。`refresh_after` 是本次使用要求已经完成的最近
+来源刷新时刻；`next_update_at` 是下一次预期来源更新；`evidence` 是支持该声明的
+来源依据。这些声明来自调用者实际采用的来源/市场合同，摘要原样保留。日期粒度的
+公告不能擅自变成午夜发布时间。若没有依据，应省略声明，结果保持 unknown 阻塞。
+
+**计划不是实际完成证据。** 即使HTTP成功且TTL新鲜，抓取时间超过计划发布时间也不能
+证明发布者更新了数据。所需输入还必须声明 `publication`：`kind` 为 `data_cutoff`
+或 `publication_time`，`precision` 为 `date` 或 `timestamp`，`at` 为要求达到的实际
+数据截止/发布时间。日期保持日期精度，timestamp必须带时区。
+
+`publications` 绑定当前会话实际返回且仍被调用者持有的 SourceResult、原始来源字段、
+字段语义依据，以及可选的来源序列身份字段 `partition_by`。系统核对对象身份、原始
+响应和schema哈希、原字段身份；不能提交一个只有新时间戳的替代receipt。摘要记录
+实际观察值、字段、分区数量、request_id与响应哈希。数据截止取各已观察序列的最新日期，
+再要求每个序列都达到阈值；发布时间要求所有返回行的发布时间达到阈值。空/未知值不满足。
+多序列来源应显式提供完整身份字段；未返回的序列仍须作为独立 required 输入声明，
+本接口不从一条最新记录推导全市场覆盖。数据截止满足也不证明新的修订批次已经发布。
+
+未提供实际字段绑定或所需截止/发布时间时，`publication.status` 为 `unknown`，
+阻塞 `publication_unknown`，无论计划链接、抓取时刻和TTL是否满足。已观察到的源数据
+早于所需时刻则为 `not_satisfied`。这些检查不会把 `fetched_at` 当成发布时间。
+
+ready 只表示 **显式所需的这些已加载输入满足给定刷新合同**：receipt完整、非空、
+fresh；实际获取时间不晚于 as_of 且不早于所需刷新；实际来源发布/截止字段达到要求；
+TTL已知且严格晚于开盘；来源下一更新也严格晚于开盘。
+未声明所需输入、开盘、TTL、来源时刻或实际来源字段证据均不 ready。
+它不证明发布者已经交付全部真实业务数据、历史 PIT、全市场交易资格或下单权限。
+摘要固定带 `trading_authorization: false`。
+
+新 fetch receipt 保存实际采用的 `freshness_policy`（调用 max_age 或来源合同默认值），
+包括 cache mode；旧 receipt 缺少该字段时仍保持原序列化及身份，不推测 TTL。
+旧缓存经一次按当前策略成功 fetch 后，返回 receipt 才记录实际使用的策略。
+缓存仅在会话确实读取后纳入本摘要；不会扫描未加载的磁盘缓存。
+`next_future_expiry` 返回已加载缓存记录中仍在未来的最早 TTL 截止时刻，跳过已过期和
+cache=bypass；它不表示期货合约到期。快照读取不能证明缓存条目仍物理驻留。
+
+建议时刻根据声明的更新时刻与已知截止时刻计算，已过时的计划收敛到 as_of，
+不添加虚构缓冲分钟数。缺少所需来源计划时返回 None。它只是再检查来源的时刻，
+不会保证届时数据到账；应实际重新 fetch，再读摘要。ready 时同样返回 None，
+需结合 summary.ready 区分状态。
+
+AsyncSession 使用 await 调同一实现。RemoteSession 仅检查本客户端已经收到的服务器
+receipt；保留服务器 freshness_policy，不使用客户端目录替代服务器策略。
+旧服务器不传策略则 TTL unknown。不会请求或声称能观察服务器整个缓存。
+
+对应冻结 `finlab_documented_api.tsv.gz` 数据行 24、26、28（含表头物理行25、27、29），
+SDK-002/005/007。参考 2.0.18 wheel 的公开 docstring 与
+[当前官方说明](https://finlab.finance/docs/reference/data/)；原库默认市场与固定估计缓冲
+不适用于 Axiolune 的多源合同，因此这里必须显式声明，不声称参数完全同名兼容。

axiolune/DOCUMENTS.md

@@ -0,0 +1,190 @@
+# Document originals, parsing, citations and candidate claims
+
+`Session.documents` stores explicitly authorized originals and traces quotations
+back through an immutable parse to those exact bytes. It does not verify financial
+facts, authenticate the supplied author label or promote claims into canonical M2.
+
+Install `axiolune[documents]` for HTTP and optional PDF parsing. Local UTF-8 text,
+HTML, JSON, CSV and TSV parsing uses the standard library. A PDF operation without
+`pypdf` returns `ExtraRequired`; importing this module and restoring its existing
+objects do not import PDF libraries or make network requests.
+
+For a retained public PDF whose fonts or scanned pages cannot be read correctly
+as text, the separate explicit [local PDF reading adapter](PDF-READING.md) consumes
+the same original bytes or `SourceResult`. Its optional `ocr` extra provides
+bounded PDFium/RapidOCR reading, coordinates, scores and uncertainty. This does
+not change document evidence v1 or make `Session.documents.parse` perform OCR.
+
+```python
+from axiolune import Session
+
+rights = {
+    "access": "public",
+    "storage": "allowed",
+    "sharing": "unverified",
+    "basis": "https://www.federalreserve.gov/disclaimer.htm",
+    "scope": "Board-authored statement text for local research",
+}
+with Session(data_root="./research", network="enabled") as session:
+    original = session.documents.fetch(
+        "https://www.federalreserve.gov/monetarypolicy/files/monetary20240918a1.pdf",
+        rights=rights, format="pdf",
+    )
+    parsed = session.documents.parse(original.id)
+    fragments = session.documents.fragments(parsed.id)
+    # Inspect the actual returned text before selecting an excerpt.
+    fragment = fragments[0]
+    citation = session.documents.cite(
+        parsed.id, fragment_id=fragment["id"], start=0, end=10,
+    )
+    claim = session.documents.claim(
+        "My candidate interpretation of the cited passage.",
+        citations=[citation.id], author="Research notebook author",
+    )
+    assert claim.manifest["status"] == "candidate"
+```
+
+The Federal Reserve Board's [copyright notice](https://www.federalreserve.gov/disclaimer.htm)
+states that Board website information is generally public domain unless otherwise
+marked, with separate restrictions for non-Board material and protected marks.
+That basis applies to the explicitly selected Board statement. It is not a default
+license for other source documents. This implementation grants no sharing or
+external publication permission. Caller-supplied rights need permitted access,
+`storage` equal to `allowed` or `permitted`, and a nonempty `basis`; a processing
+denial also prevents use. Rights remain attached to the original, parse and
+citation and are preserved per original in a claim's `source_rights`.
+
+For an existing file, call
+`import_file(path, rights=rights, format="text", source_uri=None)`. The default URI
+is its absolute file URI; a supplied source URI lets a downloaded local copy retain
+the same source identity. No rights are inferred from its presence on disk. HTTP
+acquisition requires `network="enabled"` and reuses the session's bounded transport;
+URL credentials, queries, fragments and control characters are rejected. HTTP
+redirects are not followed. The exact requested original is retained; publication
+time remains unknown instead of being inferred from acquisition time.
+
+Every evidence result is an `EvidenceRecord` with `id`, deeply immutable `manifest`
+and detached `to_dict()`. Original identity pins content, source URI, format and
+rights. `content_version` is the original byte SHA-256. Identical bytes can share a
+content object while distinct provenance or rights produce distinct original
+records. Acquisition times live in separate append-only events, so re-reading the
+same original does not invent a new content revision. Parses pin their algorithm,
+Python version and optional pypdf version and have content-addressed fragment
+objects. Explicitly parsing an original again with the same parser produces the
+same parse ID. Old originals and parses remain addressable.
+
+The v1 locators are explicit:
+
+| Format | Fragment and coordinate |
+| --- | --- |
+| UTF-8 text | Original decoded line, one-based line number, zero-based decoded character offset; line endings retained |
+| HTML | Nonempty text node, one-based source line and zero-based source column from `HTMLParser`; entities decoded, scripts/styles and whitespace-only nodes excluded |
+| JSON | Scalar value, RFC 6901 pointer and value kind; numeric source lexemes remain strings and never pass through binary floating point |
+| CSV / TSV | Every cell including headers and empty cells, one-based table/row/column and original physical line span; no type or header inference |
+| PDF | One fragment per page, one-based page and offsets in its extracted text; empty pages carry a diagnostic |
+
+A citation pins original ID, content version, parse ID, parser version, fragment
+ID, locator and a nonempty half-open `[start, end)` range measured in Unicode code
+points. It stores the exact parsed substring and its UTF-8 SHA-256. Readers verify
+that substring against the persisted parse and verify the original byte digest.
+HTML coordinates are parser source positions, not browser DOM locations. PDF
+coordinates are page/text offsets, not visual bounding boxes. Parsed excerpts can
+differ from raw-byte spelling, such as decoded HTML entities or JSON string escapes;
+both parse and original remain available. Source text is untrusted data and cannot
+authorize actions or override caller instructions.
+
+To cite several inspected fragments from the same parse, use one bounded group:
+
+```python
+citations = session.documents.cite_many(
+    parsed.id,
+    selections=[
+        {"fragment_id": first_fragment_id, "start": 0, "end": None},
+        {"fragment_id": second_fragment_id, "start": 0, "end": excerpt_end},
+    ],
+)
+```
+
+Every selection has exactly `fragment_id`, `start` and `end`; coordinates are
+integers, and `end=None` means the fragment's end. Empty/duplicate selections,
+invalid ranges, extra fields and groups exceeding the Session row/byte budget
+are rejected. Selection count and shape are checked before building a group.
+The group returns a tuple of the existing `EvidenceRecord` type in input order.
+`AsyncSession.documents.cite_many` forwards through the same async worker lane.
+
+`cite` and `cite_many` share one manifest construction and validation path.
+Single-citation manifests, IDs, schema and the `cite` event operation stay
+compatible. A group holds one SQLite write transaction: the parse/raw closure is
+verified once using that transaction's bounded object cache, and every citation
+still rereads its own actual SQL index and immutable content through `_record`.
+Only previously verified common parents are reused. The cache is discarded when
+the transaction ends. All indices and each citation's `succeeded` event commit
+together; group events share an attempt ID and carry batch size/index. A failure
+rolls back the entire group and its success events. Unreferenced objects can
+remain, and the real failed attempt is recorded separately. No half-group result
+is returned and no cache spans calls.
+
+`get(document_id)` reads verified original metadata; `original_bytes(document_id)`
+returns the exact original. `parsed(parse_id)` returns parse metadata and
+`fragments(parse_id)` returns deeply immutable fragments. `citation(citation_id)`
+and `get_claim(claim_id)` validate their complete dependency closure. A revised
+claim uses `previous_claim_id`; the old claim remains intact. Claims always remain
+`candidate`, authors are explicitly `caller_asserted`, and no verification command
+is provided. Reference chains have a 128-level limit and reject cycles.
+
+`history(subject_id=None)` returns the actual append-only lifecycle events. A
+subject filter includes the entire matching attempt, so its start and terminal
+event can be reviewed together. A start without a terminal event means the outcome
+is unknown; reading history does not update it, invent success or resume network
+activity. Retry by explicitly invoking a new operation. Missing files, corrupted
+objects, denied rights, parser failures and budget failures remain distinguishable.
+Metadata-only invalid credential URLs are rejected before any secret-bearing URL
+can enter a stored event.
+
+The existing `SnapshotStore` owns all bytes under `objects/<prefix>/<sha256>` and
+all five `document_*` tables under `control.sqlite3`. Mutations write and verify
+objects before a single SQLite transaction inserts the evidence index and success
+event. A failure can leave an unreferenced immutable object, but it cannot publish
+a successful original or replace an older version. Start/failure audit events are
+separate commits. Small control-event overhead is separate from payload budgets
+except that `cite`/`cite_many` also budget their start and success event payloads;
+failure cleanup records remain separate bounded control events.
+Reads honor session byte/row/deadline/cancellation limits. Parser output growth,
+JSON depth, PDF page count and decoded page-stream size are checked; in-process PDF
+extraction is not a hard operating-system memory or CPU sandbox. It performs no OCR
+and makes no promise that PDF reading order is visually faithful.
+
+Recovery uses the pure read-only `document_object_closure(connection, store)` hook
+and the exported `DOCUMENT_TABLE_COLUMNS` exact column inventory. All DB lookups
+use the supplied fixed SQLite view; only immutable object reads use the store. A
+fully absent document table group is valid; a partially present group is rejected.
+The hook verifies original/parse/citation/claim/event references and does not load
+optional parsers or change lifecycle state.
+
+The CLI mirrors these operations:
+
+```text
+axiolune documents import-file PATH --format pdf --rights-file rights.json --data-root ROOT
+axiolune documents parse DOCUMENT_ID --data-root ROOT
+axiolune documents fragments PARSE_ID --data-root ROOT
+axiolune documents cite PARSE_ID --fragment-id 0 --start 0 --end 10 --data-root ROOT
+axiolune documents claim --text-file claim.txt --citations-file citations.json --author AUTHOR --data-root ROOT
+axiolune documents get-claim CLAIM_ID --data-root ROOT
+axiolune documents history --subject-id DOCUMENT_ID --data-root ROOT
+```
+
+`citations.json` is an array of committed citation IDs. The CLI does not write raw
+document bytes to stdout. `AsyncSession.documents` exposes the same contracts and
+checks the same session lifetime. No local document API creates team publication
+or a shared permission grant implicitly.
+
+Actual validation is implemented in `validation/document_evidence.py`. It fetches
+the Board's [HTML statement](https://www.federalreserve.gov/newsevents/pressreleases/monetary20240918a.htm)
+and [four-page PDF](https://www.federalreserve.gov/monetarypolicy/files/monetary20240918a1.pdf),
+reconciles their exact excerpts, reads retained real FX source data plus repository
+engineering text/TSV, exercises genuine parse/missing/corruption failures, and
+checks SQLite recovery, CLI and async paths. This establishes only the reported
+format and evidence behaviors, not general provider qualification or financial
+truth. Parser APIs follow official [HTMLParser](https://docs.python.org/3/library/html.parser.html),
+[pypdf extraction](https://pypdf.readthedocs.io/en/stable/user/extract-text.html)
+and [HTTPX](https://www.python-httpx.org/quickstart/) documentation.

axiolune/ECB-EST.md

@@ -0,0 +1,30 @@
+# ECB €STR 的获取与离线使用
+
+`ecb.euro_short_term_rate` 使用 ECB 的 EST CSV 接口，保留全部源列和原始文本值。已有的 `Session.data.fetch`、缓存、快照、Parquet 导出和 SQL 读取共同处理此产品，无需另装 ECB 客户端。
+
+以下函数由调用者明确指定日期与存储位置。`B.EU000A2X2A25.WT` 是本次实际验证的 €STR 利率系列键；其他系列仍须按 ECB EST 目录选择，不由包猜测。
+
+```python
+from axiolune import Session
+
+def retain_estr(data_root, start_date, end_date, export_path):
+    parameters = {
+        "series_key": "B.EU000A2X2A25.WT",
+        "startPeriod": start_date,
+        "endPeriod": end_date,
+    }
+    with Session.local(data_root=data_root, network="enabled") as session:
+        result = session.data.fetch(
+            "ecb.euro_short_term_rate", params=parameters, cache="refresh"
+        )
+        snapshot = session.snapshots.freeze(result)
+        result.export(export_path)  # .parquet；旁文件保留来源及权利条件
+    with Session.local(data_root=data_root, network="offline") as session:
+        return session.data.read(snapshot.id)
+```
+
+已验证窗口为 2026-01-01 至 2026-09-11：177 行、29 列，CSV 的 5,133 个字段值与 Arrow、pandas、Polars、Parquet 和断网读取一致。利率原值以文本保留，计算时应显式声明 Decimal 类型和单位。目录中的旧获取证据仍指向原先那次请求；本次新获取和实际留存见 a13 的独立验证记录。
+
+EST 元数据明确其发布来源为 ECB，并区分交易参考日期与次一营业日的发布时间。`TIME_PERIOD` 不能直接当作历史可知时刻；此产品的 source 读取不会自动取得严格研究或 PIT 资格。[ECB EST 说明](https://data.ecb.europa.eu/data/datasets/EST/data-information)
+
+留存与共享依据是 ECB 统计再使用政策及其声明。使用时须准确保留原统计和元数据并标明来源；派生计算须说明是使用者的计算。付费文档另须按声明提示原信息可从 ECB 免费获得。receipt 保存条款链接、条件和实取官方材料的摘要；EXR/FM 及第三方数据不因本次核对而取得授权。[再使用政策](https://www.ecb.europa.eu/stats/ecb_statistics/governance_and_quality_framework/html/usage_policy.en.html)、[版权与使用声明](https://www.ecb.europa.eu/services/using-our-site/disclaimer/html/index.en.html)、[€STR 声明](https://www.ecb.europa.eu/stats/financial_markets_and_interest_rates/euro_short-term_rate/html/index.en.html)