finpanel 0.1.0a2__tar.gz

finpanel-0.1.0a2/.gitattributes

@@ -0,0 +1,4 @@
+# Frozen source bytes are hash-verified evidence, not editable text.
+# Preserve their original line endings even when core.autocrlf is enabled.
+tests/fixtures/** -text
+src/finpanel/example_data/** -text

finpanel-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.1.0a2 — preparation, not yet published
+
+Intended tag: `v0.1.0-alpha.2`. This is a documentation/packaging synchronization
+update: corrected public GitHub installation instructions, researcher guide and
+release-status documentation now accompany refreshed wheel metadata and embedded
+README. README links are absolute for package-index rendering.
+
+No financial/accounting semantics, metric contracts, revision, as-of or provenance
+behavior changed. The versioned software identity changes; old receipts still
+require their original matching software. A1 tags and assets are preserved.
+
+
+## 0.1.0a1 — GitHub alpha pre-release (2026-10-08)
+
+Published [GitHub pre-release v0.1.0-alpha](https://github.com/finleydoudou/FinPanel/releases/tag/v0.1.0-alpha) (first alpha).
+PyPI publication has not occurred. See [current release status](docs/release-status.md). Use `0.1.0a1` in Python
+package metadata and dependency specifications; the label is an explicit mapping.
+
+- Preserve frozen evidence bytes during Git checkout on Windows.
+- Make optional example memory telemetry unavailable rather than failing when the
+  Unix `resource` module is absent. No accounting or provenance contract changed.
+
+- Prepare an alpha package for reproducible point-in-time SEC fundamentals.
+- Add authentic historical fiscal-calendar and revision/restatement audit ledgers,
+  with conservative diagnostics and original narrative provenance.
+- Add deterministic validation jobs, verified issuer checkpoints, resume equivalence,
+  corruption rejection, writer locking, and batch failure records.
+- Expand the purposive validation universe from 50 to 100 ordinary US-GAAP issuers.
+- Include a small authentic offline panel example in installed artifacts.
+- Document the public/experimental/private API boundary and supported Python 3.12.
+- Add first-party tzdata fallback for systems without an IANA timezone database.
+- Add cross-platform CI configuration and separate clean wheel/sdist install checks.
+- Prepare researcher onboarding, source notices, validation evidence, and release checklist.
+
+No new financial metric or unsupported sector ontology was added. Existing reported
+metric defaults and accounting selection rules are unchanged. The package/software
+identity changes intentionally; exact older receipts require matching older software.
+Prior work packages remain the historical baseline, not separate published releases.

finpanel-0.1.0a2/LICENSE

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

finpanel-0.1.0a2/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE README.md pyproject.toml
+recursive-include tests *.py *.json
+recursive-include tests/fixtures *.sgml
+recursive-include examples *.py
+
+recursive-include docs *.json *.md
+recursive-include tests/fixtures/xbrl *.xml *.html
+
+recursive-include src/finpanel/validation *.json
+recursive-include tests/fixtures/broad *.gz
+
+include CHANGELOG.md THIRD_PARTY_NOTICES.md
+include .gitattributes
+recursive-include tests/fixtures/release *.gz
+
+recursive-include scripts *.py

finpanel-0.1.0a2/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: finpanel
+Version: 0.1.0a2
+Summary: Research infrastructure for reproducible point-in-time SEC fundamentals
+License-Expression: MIT
+Project-URL: Repository, https://github.com/finleydoudou/FinPanel
+Project-URL: Issues, https://github.com/finleydoudou/FinPanel/issues
+Project-URL: Documentation, https://github.com/finleydoudou/FinPanel#readme
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: httpx<0.29,>=0.28
+Requires-Dist: simplejson<5,>=3.19
+Requires-Dist: pyarrow<24,>=18
+Requires-Dist: duckdb<2,>=1.5
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.11; extra == "dev"
+Requires-Dist: build<2,>=1; extra == "dev"
+Dynamic: license-file
+
+# FinPanel
+
+Research infrastructure for reproducible point-in-time SEC fundamentals.
+
+FinPanel builds financial research panels from SEC filings and XBRL facts while
+preserving which evidence supports each result. Choose a historical cutoff, pin
+the captured evidence, and replay the result later. Unavailable or conflicting
+facts remain explicit states instead of silently becoming numbers.
+
+The alpha pre-release supports six metrics for ordinary US-GAAP operating companies:
+revenue, net income, assets, liabilities, cash and cash equivalents, and operating
+cash flow. It supports reported periods and conservative Q2/Q3/Q4 derivations.
+Banks, insurers, IFRS normalization, segment aggregation, FX normalization, prices,
+and returns are outside scope. Historical/original-XBRL evidence is incomplete for
+some issuers; extension-heavy or dimension-heavy disclosures may remain unresolved.
+
+**Alpha.2:** this source tree builds package **0.1.0a2**, with Git label
+`v0.1.0-alpha.2`. Python **3.12** is required. Check the
+[release list](https://github.com/finleydoudou/FinPanel/releases) and
+[PyPI project](https://pypi.org/project/finpanel/) for publication availability;
+source preparation alone does not imply that a release has been published.
+The existing [a1 GitHub pre-release](https://github.com/finleydoudou/FinPanel/releases/tag/v0.1.0-alpha)
+(package `0.1.0a1`) remains unchanged.
+See [validation evidence](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-validation.md)
+and [release notes](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-a2-notes.md).
+This is experimental research software, not a stable production release.
+
+## Installation
+
+Once version `0.1.0a2` is available on production PyPI, install that exact version
+in a clean Python 3.12 environment with `python -m pip install finpanel==0.1.0a2`.
+Before publication, use only a verified candidate wheel supplied with its
+`SHA256SUMS.txt`. Do not substitute an a1 artifact or rename its wheel.
+For published a1 users, follow the
+[a1 installation instructions](https://github.com/finleydoudou/FinPanel/blob/07f3e16fcf18019b16e5ac25d575e646d126c570/README.md#installation).
+
+The verified-wheel workflow below also works for a2 GitHub release assets when
+available. Maintainers build fresh artifacts from the exact authorized source;
+the a2 wheel is named `finpanel-0.1.0a2-py3-none-any.whl`.
+
+In the artifact folder, print the wheel hash:
+
+```bash
+# macOS
+shasum -a 256 finpanel-0.1.0a2-py3-none-any.whl
+# Linux
+sha256sum finpanel-0.1.0a2-py3-none-any.whl
+```
+
+```powershell
+# Windows PowerShell
+Get-FileHash finpanel-0.1.0a2-py3-none-any.whl -Algorithm SHA256
+```
+
+Manually compare the printed hash with the wheel's row in the supplied checksum
+file (case-insensitively); stop on a mismatch. Comparison is not automatic.
+
+Create and activate a clean Python 3.12 environment:
+
+```bash
+# macOS/Linux
+python3.12 -m venv .venv
+source .venv/bin/activate
+```
+
+```powershell
+# Windows PowerShell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Then install the candidate and verify:
+
+```bash
+python -m pip install ./finpanel-0.1.0a2-py3-none-any.whl
+python -c "import finpanel; print(finpanel.__version__)"
+python -m finpanel.cli --help
+```
+
+Expected candidate version: `0.1.0a2`. Dependencies may download from PyPI; the
+FinPanel package comes from the supplied wheel. The example below is offline.
+If PowerShell activation is unavailable, invoke `.\.venv\Scripts\python.exe`
+in place of `python` without changing execution policy.
+
+For an intentional source clone, see the
+[developer/source workflow](https://github.com/finleydoudou/FinPanel/blob/main/docs/researcher-guide.md#developer-source-user).
+
+## Quick Start — no SEC credentials
+
+After installation, run this from your own working directory. Choose a fresh
+output directory each time:
+
+```bash
+python -m finpanel.example output/quickstart
+```
+
+This uses bundled, hash-verified H&R Block SEC captures. It creates six FY2022
+cells, CSV/Parquet/DuckDB exports, provenance sidecars, and a replay receipt. Three
+cells resolve under the example's cutoff and conservative contracts; three remain
+unresolved. That is **coverage**, not an accuracy percentage. No network access or
+large corpus download is needed. Choose a fresh output directory each time.
+
+```python
+from finpanel import panel
+
+rows = panel.read_export("output/quickstart/panel.parquet")
+for row in rows:
+    print(row["metric"], row["state"], row["value"])
+```
+
+See the [researcher guide](https://github.com/finleydoudou/FinPanel/blob/main/docs/researcher-guide.md) for a custom panel, historical
+cutoffs, original XBRL verification, pinned replay, and troubleshooting.
+
+## What reproducibility means here
+
+- A filing-availability proxy limits facts, filings, and calendar anchors before
+  interpretation. Today's fiscal-year-end cannot explain all historical years.
+- `first_reported` and `latest_available` choose temporal candidates within exact
+  source identities. Different concepts or incompatible scopes are not merged.
+- Derived quarters retain both cumulative operands. Incompatible revision states
+  produce a conflict rather than plausible arithmetic.
+- CompanyFacts is a captured aggregate feed. Filing-time eligibility does **not**
+  establish when that aggregate feed first delivered a fact. Snapshot capture time
+  and historical information cutoff are different dimensions.
+- Exact replay requires the original snapshot and matching software/contracts.
+  CSV semantic rows are deterministic; container bytes and performance timing are
+  not cross-platform reproducibility promises.
+
+## Validation and release status
+
+- Alpha.2 package: **0.1.0a2**, Git label **v0.1.0-alpha.2**. Check the release list for publication availability.
+- Existing public GitHub release: [a1](https://github.com/finleydoudou/FinPanel/releases/tag/v0.1.0-alpha), package **0.1.0a1**, unchanged.
+- Production PyPI: **not published**. TestPyPI rehearsal is conditional on gates and account setup; it is not a production release.
+- Supported Python: **3.12**. [A2 software CI](https://github.com/finleydoudou/FinPanel/actions/runs/37799312175) passed macOS/Linux/Windows with **814 tests / 0 skipped** each on the TestPyPI-tested software candidate. Final release-only documentation/workflow changes additionally require successful CI on the exact final commit before publication.
+
+The audited population contains 100 ordinary US-GAAP operating companies and
+24,000 financial cells. **69.61% scalar coverage is not accuracy**. All 255
+independently audited golden expectations, 2,435,238 invariant checks and 500
+future-evidence mutation checks passed, with zero unexpected mismatches **within
+that specified audited population**. This is not a universal accuracy or
+market-wide support claim.
+
+Read the [validation evidence](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-validation.md),
+[API/support policy](https://github.com/finleydoudou/FinPanel/blob/main/docs/api-stability.md), and [current release status](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-status.md).
+The [earlier gate](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-candidate-gate.md) and
+[earlier checklist](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-checklist.md) are explicitly historical records;
+their original Windows failures are preserved, not current release blockers.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+python -m build
+python scripts/validate_install.py dist
+```
+
+Routine tests and the clean-install example use frozen evidence. Live SEC
+acquisition is a separate, explicitly configured operation. Never commit an SEC
+contact identity, credentials, or the local Tier B corpus.
+
+Detailed references: [accounting/API workflows](https://github.com/finleydoudou/FinPanel/blob/main/docs/technical-reference.md),
+[panels](https://github.com/finleydoudou/FinPanel/blob/main/docs/research-panels.md), [broad validation](https://github.com/finleydoudou/FinPanel/blob/main/docs/broad-validation.md),
+[historical/revision audit](https://github.com/finleydoudou/FinPanel/blob/main/docs/historical-audit.md),
+[resume](https://github.com/finleydoudou/FinPanel/blob/main/docs/resumable-validation.md), [changelog](https://github.com/finleydoudou/FinPanel/blob/main/CHANGELOG.md),
+[third-party notices](https://github.com/finleydoudou/FinPanel/blob/main/THIRD_PARTY_NOTICES.md), and [MIT license](https://github.com/finleydoudou/FinPanel/blob/main/LICENSE).

finpanel-0.1.0a2/README.md

@@ -0,0 +1,168 @@
+# FinPanel
+
+Research infrastructure for reproducible point-in-time SEC fundamentals.
+
+FinPanel builds financial research panels from SEC filings and XBRL facts while
+preserving which evidence supports each result. Choose a historical cutoff, pin
+the captured evidence, and replay the result later. Unavailable or conflicting
+facts remain explicit states instead of silently becoming numbers.
+
+The alpha pre-release supports six metrics for ordinary US-GAAP operating companies:
+revenue, net income, assets, liabilities, cash and cash equivalents, and operating
+cash flow. It supports reported periods and conservative Q2/Q3/Q4 derivations.
+Banks, insurers, IFRS normalization, segment aggregation, FX normalization, prices,
+and returns are outside scope. Historical/original-XBRL evidence is incomplete for
+some issuers; extension-heavy or dimension-heavy disclosures may remain unresolved.
+
+**Alpha.2:** this source tree builds package **0.1.0a2**, with Git label
+`v0.1.0-alpha.2`. Python **3.12** is required. Check the
+[release list](https://github.com/finleydoudou/FinPanel/releases) and
+[PyPI project](https://pypi.org/project/finpanel/) for publication availability;
+source preparation alone does not imply that a release has been published.
+The existing [a1 GitHub pre-release](https://github.com/finleydoudou/FinPanel/releases/tag/v0.1.0-alpha)
+(package `0.1.0a1`) remains unchanged.
+See [validation evidence](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-validation.md)
+and [release notes](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-a2-notes.md).
+This is experimental research software, not a stable production release.
+
+## Installation
+
+Once version `0.1.0a2` is available on production PyPI, install that exact version
+in a clean Python 3.12 environment with `python -m pip install finpanel==0.1.0a2`.
+Before publication, use only a verified candidate wheel supplied with its
+`SHA256SUMS.txt`. Do not substitute an a1 artifact or rename its wheel.
+For published a1 users, follow the
+[a1 installation instructions](https://github.com/finleydoudou/FinPanel/blob/07f3e16fcf18019b16e5ac25d575e646d126c570/README.md#installation).
+
+The verified-wheel workflow below also works for a2 GitHub release assets when
+available. Maintainers build fresh artifacts from the exact authorized source;
+the a2 wheel is named `finpanel-0.1.0a2-py3-none-any.whl`.
+
+In the artifact folder, print the wheel hash:
+
+```bash
+# macOS
+shasum -a 256 finpanel-0.1.0a2-py3-none-any.whl
+# Linux
+sha256sum finpanel-0.1.0a2-py3-none-any.whl
+```
+
+```powershell
+# Windows PowerShell
+Get-FileHash finpanel-0.1.0a2-py3-none-any.whl -Algorithm SHA256
+```
+
+Manually compare the printed hash with the wheel's row in the supplied checksum
+file (case-insensitively); stop on a mismatch. Comparison is not automatic.
+
+Create and activate a clean Python 3.12 environment:
+
+```bash
+# macOS/Linux
+python3.12 -m venv .venv
+source .venv/bin/activate
+```
+
+```powershell
+# Windows PowerShell
+py -3.12 -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Then install the candidate and verify:
+
+```bash
+python -m pip install ./finpanel-0.1.0a2-py3-none-any.whl
+python -c "import finpanel; print(finpanel.__version__)"
+python -m finpanel.cli --help
+```
+
+Expected candidate version: `0.1.0a2`. Dependencies may download from PyPI; the
+FinPanel package comes from the supplied wheel. The example below is offline.
+If PowerShell activation is unavailable, invoke `.\.venv\Scripts\python.exe`
+in place of `python` without changing execution policy.
+
+For an intentional source clone, see the
+[developer/source workflow](https://github.com/finleydoudou/FinPanel/blob/main/docs/researcher-guide.md#developer-source-user).
+
+## Quick Start — no SEC credentials
+
+After installation, run this from your own working directory. Choose a fresh
+output directory each time:
+
+```bash
+python -m finpanel.example output/quickstart
+```
+
+This uses bundled, hash-verified H&R Block SEC captures. It creates six FY2022
+cells, CSV/Parquet/DuckDB exports, provenance sidecars, and a replay receipt. Three
+cells resolve under the example's cutoff and conservative contracts; three remain
+unresolved. That is **coverage**, not an accuracy percentage. No network access or
+large corpus download is needed. Choose a fresh output directory each time.
+
+```python
+from finpanel import panel
+
+rows = panel.read_export("output/quickstart/panel.parquet")
+for row in rows:
+    print(row["metric"], row["state"], row["value"])
+```
+
+See the [researcher guide](https://github.com/finleydoudou/FinPanel/blob/main/docs/researcher-guide.md) for a custom panel, historical
+cutoffs, original XBRL verification, pinned replay, and troubleshooting.
+
+## What reproducibility means here
+
+- A filing-availability proxy limits facts, filings, and calendar anchors before
+  interpretation. Today's fiscal-year-end cannot explain all historical years.
+- `first_reported` and `latest_available` choose temporal candidates within exact
+  source identities. Different concepts or incompatible scopes are not merged.
+- Derived quarters retain both cumulative operands. Incompatible revision states
+  produce a conflict rather than plausible arithmetic.
+- CompanyFacts is a captured aggregate feed. Filing-time eligibility does **not**
+  establish when that aggregate feed first delivered a fact. Snapshot capture time
+  and historical information cutoff are different dimensions.
+- Exact replay requires the original snapshot and matching software/contracts.
+  CSV semantic rows are deterministic; container bytes and performance timing are
+  not cross-platform reproducibility promises.
+
+## Validation and release status
+
+- Alpha.2 package: **0.1.0a2**, Git label **v0.1.0-alpha.2**. Check the release list for publication availability.
+- Existing public GitHub release: [a1](https://github.com/finleydoudou/FinPanel/releases/tag/v0.1.0-alpha), package **0.1.0a1**, unchanged.
+- Production PyPI: **not published**. TestPyPI rehearsal is conditional on gates and account setup; it is not a production release.
+- Supported Python: **3.12**. [A2 software CI](https://github.com/finleydoudou/FinPanel/actions/runs/37799312175) passed macOS/Linux/Windows with **814 tests / 0 skipped** each on the TestPyPI-tested software candidate. Final release-only documentation/workflow changes additionally require successful CI on the exact final commit before publication.
+
+The audited population contains 100 ordinary US-GAAP operating companies and
+24,000 financial cells. **69.61% scalar coverage is not accuracy**. All 255
+independently audited golden expectations, 2,435,238 invariant checks and 500
+future-evidence mutation checks passed, with zero unexpected mismatches **within
+that specified audited population**. This is not a universal accuracy or
+market-wide support claim.
+
+Read the [validation evidence](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-validation.md),
+[API/support policy](https://github.com/finleydoudou/FinPanel/blob/main/docs/api-stability.md), and [current release status](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-status.md).
+The [earlier gate](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-candidate-gate.md) and
+[earlier checklist](https://github.com/finleydoudou/FinPanel/blob/main/docs/release-checklist.md) are explicitly historical records;
+their original Windows failures are preserved, not current release blockers.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+pytest
+ruff check .
+ruff format --check .
+python -m build
+python scripts/validate_install.py dist
+```
+
+Routine tests and the clean-install example use frozen evidence. Live SEC
+acquisition is a separate, explicitly configured operation. Never commit an SEC
+contact identity, credentials, or the local Tier B corpus.
+
+Detailed references: [accounting/API workflows](https://github.com/finleydoudou/FinPanel/blob/main/docs/technical-reference.md),
+[panels](https://github.com/finleydoudou/FinPanel/blob/main/docs/research-panels.md), [broad validation](https://github.com/finleydoudou/FinPanel/blob/main/docs/broad-validation.md),
+[historical/revision audit](https://github.com/finleydoudou/FinPanel/blob/main/docs/historical-audit.md),
+[resume](https://github.com/finleydoudou/FinPanel/blob/main/docs/resumable-validation.md), [changelog](https://github.com/finleydoudou/FinPanel/blob/main/CHANGELOG.md),
+[third-party notices](https://github.com/finleydoudou/FinPanel/blob/main/THIRD_PARTY_NOTICES.md), and [MIT license](https://github.com/finleydoudou/FinPanel/blob/main/LICENSE).

finpanel-0.1.0a2/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,50 @@
+# Third-party notices and evidence provenance
+
+FinPanel's own source is distributed under the repository's MIT license. That
+license does not purport to relicense third-party dependencies or issuer filings.
+
+## Dependencies
+
+Dependencies are installed separately; FinPanel does not vendor their source.
+Their installed distributions carry their own license files and notices.
+
+| Component | Use | Declared runtime range | License reference |
+|---|---|---|---|
+| HTTPX | SEC HTTP transport, timeouts, response handling | `>=0.28,<0.29` | [BSD-3-Clause](https://github.com/encode/httpx/blob/master/LICENSE.md) |
+| simplejson | Exact decimal JSON reading/writing | `>=3.19,<5` | [MIT or AFL-2.1](https://github.com/simplejson/simplejson/blob/main/LICENSE.txt) |
+| PyArrow | Typed Parquet and Arrow interchange | `>=18,<24` | [Apache-2.0 and bundled-component notices](https://github.com/apache/arrow/blob/main/LICENSE.txt) |
+| tzdata | IANA timezone fallback on systems without zone data | `>=2024.1` | [Apache-2.0 package metadata](https://pypi.org/project/tzdata/) |
+| DuckDB | Local analytical export and read-back | `>=1.5,<2` | [MIT](https://duckdb.org/faq) |
+
+Development-only pytest, Ruff, build, and build-backend setuptools identify MIT
+licenses in their installed metadata. These are not added as runtime dependencies.
+No dependency was removed: all existing runtime dependencies have exercised uses. The added first-party tzdata
+fallback supplies the SEC local timezone on platforms without a system IANA database.
+No assertion is made that every allowed dependency combination was tested; see
+[the support audit](docs/api-stability.md) for actual versions.
+
+This inventory records upstream licensing information, not a legal opinion about
+all downstream redistribution arrangements. If dependencies are bundled into a
+standalone binary, preserve their complete distributed notices, including transitive
+components; the short table above does not replace them.
+
+## Authentic SEC evidence
+
+Frozen evidence comes from the official SEC hosts `data.sec.gov` and `www.sec.gov`.
+Each fixture manifest records its source URL, accession where applicable, retrieval
+time, original byte hash, and the lossless compressed-transport hash. Small regression
+captures and the packaged HRB example are source material for reproducible research;
+they are not authored by FinPanel. Public availability through EDGAR is not a blanket
+claim that every issuer-authored narrative, attachment, image, or trademark is public
+domain. FinPanel claims no ownership or endorsement over that material.
+
+WP7 includes HRB, Mattel, and Kraft Heinz aggregates and two issuer narrative filings.
+The full source URLs and hashes live in `tests/fixtures/release/manifest.json`.
+The installed onboarding example contains HRB JSON responses only, with its separate
+`finpanel/example_data/manifest.json`. Lossless gzip is transport, not altered evidence.
+Synthetic test mutations are identified as synthetic and do not replace raw captures.
+
+The broader Tier B SEC corpus remains local and ignored; it is excluded from wheel,
+source distribution, and Git. Before an actual public release, review the specific
+bundled issuer-authored narrative fixtures and the intended distribution context.
+This preparation does not grant rights beyond those held by the original sources.

finpanel-0.1.0a2/docs/api-stability.md

@@ -0,0 +1,103 @@
+# API and package stability policy
+
+This is a pre-release compatibility commitment within the existing research scope,
+not a v1 promise that all importable Python names are public. Existing WP1–WP6
+calls and default behavior are retained. No namespace was removed or renamed.
+
+## Intended supported research surface
+
+| Surface | Entry points / return models | Contract |
+|---|---|---|
+| Raw SEC | `SECClient`, `submissions`, `companyfacts`, raw response/parse models | Explicit CIK; online identity required; offline cache misses fail |
+| Filing/fact inspection | `filings.timeline`, `filings.available_as_of`, `facts.for_concept`, typed filing/fact records | Original raw fields and precision retained |
+| Bounded interpretation | `asof.view`, `asof.revisions`, `periods.for_concept`, `revisions.analyze` | Explicit as-of versus retrospective mode; exact concept groups |
+| Canonical metrics | Exports in `metrics.__all__`, especially `candidates`, `resolve`, `derive_quarter`, `resolve_quarter`, `compare_quarter` | Six declared metrics; reported-only `resolve`; explicit quarter policies |
+| Snapshots | `EvidenceStore`, `Artifact`, `Snapshot`, `Integrity`, `run`, `reproduce`, `read_receipt`, `export_bundle` | Immutable byte captures; explicit version selection; fail-closed replay |
+| Panels | `PanelRequest`, `PeriodEnd`, `PanelRow`, `PanelResult`, `PanelReceipt`, `build`, `export`, `read_export`, `reproduce` | Complete explicit grid, state/provenance per row, lossless semantic exports |
+| Original XBRL | `xbrl.__all__`, including `inspect_filing`, `verify_fact`, `verify_metric`, `verify_derivation` | Supported XML only; retrieval-bounded verification; no fabricated dimensions |
+
+Dataclass return models distinguish absence, ambiguity, unsupported scope, conflict,
+and usable scalar results. `PanelRequest` normalizes query dimensions and validates
+policies. Monetary values remain `int`/`Decimal`; portable exports carry exact decimal
+text and number kind. JSON serialization uses `finpanel.serialization.dumps/loads`;
+plain `json.dumps` is not a replacement for exact Decimal/model serialization.
+
+Public metric entry points and models already carry type annotations. WP7 adds
+annotations to panel build/replay/export/read-back arguments and returns and a
+reported-only resolver docstring. Dynamic provenance dictionaries are intentional;
+the whole package is not advertised as fully statically type-checked. Named states
+remain strings validated by contracts rather than a new breaking enum conversion.
+
+### Errors
+
+`FinPanelError` is the shared expected-operation base. `ValidationError` also inherits
+`ValueError`; cache failures use `CacheError`/`CacheMissError`, transport failures use
+`SECRequestError`/`SECTimeoutError`, snapshot/replay uses `SnapshotError`, and strict
+panel builds use `PanelBuildError`. Transport errors expose URL, attempt count, and
+status where available, not credentials. Parse issues and unresolved financial
+states normally appear in returned evidence/results; they are not automatically
+exceptions. `errors="raise"` is the explicit strict panel option.
+
+### Experimental and private
+
+`validation.*` (universe, acquisition, historical diagnostics, benchmark reports,
+checkpoints, and goldens), the `validate` CLI namespace, and `finpanel.example` are
+experimental research tooling. Their formats are versioned and incompatible resumes
+fail explicitly. Model/candidate construction helpers are advanced inspection APIs,
+not permission to bypass cutoff or scope validation.
+
+Leading-underscore helpers, `_reuse`, `_PinnedCache`, `_publish`, parser internals,
+CLI dispatch implementation, fixture transport details, and benchmark aggregation
+internals are private. Importability alone gives no stability guarantee. Keep raw
+artifacts and receipts rather than depending on those implementation details.
+
+## Version and replay
+
+The prepared PEP 440 version is `0.1.0a2`, mapped to intended tag
+`v0.1.0-alpha.2`. This is a documentation/packaging refresh, not a new financial
+contract. The published a1 tag/package remain unchanged. Production publication
+requires separate authorization. Receipt identity
+includes the package version, source hash, Python patch version, and exact relevant
+JSON/transport dependency versions. An older WP6 receipt intentionally requires its
+original matching software for exact replay. Updating the package does not silently
+upgrade an old receipt or rewrite its evidence.
+
+## Dependencies and platforms
+
+| Dependency | Kind | Declared minimum | Version used in local validation |
+|---|---|---:|---:|
+| httpx | Runtime HTTP transport | 0.28 | 0.28.1 |
+| simplejson | Runtime exact JSON | 3.19 | 4.2.0 |
+| pyarrow | Runtime Parquet/Arrow | 18 | 23.0.1 |
+| duckdb | Runtime analytical export | 1.5 | 1.5.6 |
+| tzdata | Runtime IANA timezone fallback | 2024.1 | 2026.5 |
+| setuptools | Build backend only | 77 | 84.0.0 |
+| build | Development build tool | 1 | 1.6.1 |
+| pytest | Development tests | 8 | 9.1.1 |
+| Ruff | Development lint/format | 0.11 | 0.16.10 |
+
+These ranges are dependency constraints, not a claim that minimum-version matrices
+were executed. HTTPX/simplejson are used by core ingestion/serialization; Arrow and
+DuckDB support promised export formats, so none is an unused dependency. WP7 adds first-party `tzdata` for Windows and other
+installations without an IANA system database. Clean-install checks disable system
+timezone lookup and exercise winter/summer SEC offsets and the full example. Binary
+wheels and architecture availability matter for Arrow and DuckDB.
+
+Python **3.12 only** is declared for this alpha (`>=3.12,<3.13`); local validation uses
+3.12.14 on macOS arm64. Other Python minors are not claimed. The CI matrix defines
+Python 3.12 on macOS, Linux, and Windows with permanent offline tests, builds, and
+clean artifact installs. The final published release commit
+`30ffbbe658fbc517ec838ba499859ec05093283b` passed all three platforms with
+814 tests and 0 skipped per platform, including builds and clean installations.
+See [current release status](release-status.md) and its exact-commit CI link.
+The [earlier failed gate](release-candidate-gate.md) remains a historical record;
+its Windows failures were resolved before publication. There is no
+platform-specific accounting fork.
+
+`scripts/validate_install.py` installs wheel and sdist into separate new virtual
+environments, runs outside the checkout with isolated Python imports, checks the
+installed CLI/module, executes the bundled offline example, verifies replay, and
+compares all three export round trips. It cannot fall back to the developer editable
+installation. Dependency downloads may use PyPI; SEC access remains disabled.
+
+The timezone-data fallback follows the [Python zoneinfo recommendation](https://docs.python.org/3.12/library/zoneinfo.html#data-sources). Local broad validation used the host database; clean installs also verify the packaged fallback. Receipts fail closed on semantic differences; the OS timezone database itself is not yet a separately pinned receipt component.