ahasignals-pit 0.1.0__tar.gz

ahasignals_pit-0.1.0/.gitignore

@@ -0,0 +1,3 @@
+/dist/
+__pycache__/
+*.pyc

ahasignals_pit-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Select the latest eligible fact with an exact period, unit and dimension match.
+- Check declared disclosure and observation clocks, retaining source references.
+- Reconstruct quarterly cash flows from exact quarter or matching fiscal YTD durations.
+- Add an offline JSON CLI, explicit refusal reasons and synthetic examples.
+- Port the financial-query-checks v1 rules to Python; reject malformed Python inputs and ambiguous JSON keys.

ahasignals_pit-0.1.0/LICENSE

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

ahasignals_pit-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: ahasignals-pit
+Version: 0.1.0
+Summary: Point-in-time financial fact selection and quarterly cash-flow checks
+Project-URL: Homepage, https://ahasignals.com/research/point-in-time-financial-data/
+Project-URL: Documentation, https://ahasignals.com/examples/ahasignals-pit/v0.1.0/README.md
+Project-URL: Source, https://ahasignals.com/examples/ahasignals-pit/v0.1.0/ahasignals_pit-0.1.0.tar.gz
+Project-URL: Related benchmark dataset, https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity
+Project-URL: Related paper, https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198
+Author: AhaSignals
+Maintainer-email: AhaSignals <research@ahasignals.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtesting,financial-data,point-in-time,reproducibility
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# AhaSignals PIT
+
+Select financial facts that match a declared historical cutoff, then inspect the period, scope and source version behind each answer. Reconstruct quarterly operating cash flow less cash PP&E without treating cumulative cash flows as a quarter.
+
+Python 3.9 or later. No runtime dependencies. No network requests, telemetry, account or API key required. Version 0.1.0 is an initial alpha release with a deliberately narrow contract.
+
+## Install and run
+
+After the release is available on PyPI:
+
+```bash
+python -m pip install ahasignals-pit==0.1.0
+ahasignals-pit input.json
+# Equivalent:
+python -m ahasignals_pit input.json
+```
+
+For a source checkout, run `python -m pip install .` from this directory, then:
+
+```bash
+ahasignals-pit examples/select.json
+ahasignals-pit examples/quarterly-cash.json
+python -m unittest discover -s tests -v
+```
+
+Both examples are fully synthetic. Their identifiers, amounts, dates, example.org source URL and zero hash do not represent a real issuer or authenticated document. The first selects 120; the second returns quarterly operating cash of 160, cash PP&E of 40 and cash after PP&E of 120 USD. These are arithmetic examples, not investment results.
+
+## Python API
+
+```python
+import json
+from ahasignals_pit import run, select_fact, quarterly_cash
+
+with open('examples/select.json', encoding='utf-8') as stream:
+    payload = json.load(stream)
+result = select_fact(payload['facts'], payload['query'])
+assert result['status'] == 'answer'
+print(result['value'], result['inputs'])
+# run(payload) dispatches by task: select or quarterly-cash.
+```
+
+The public functions accept JSON-compatible dictionaries and lists. Input field names retain the camelCase contract of the related financial query checker. Output status is `answer`, `withheld` or `invalid`. Never replace a withheld value with zero. The CLI returns exit codes 0, 1 and 2 respectively; it also includes the package version and SHA-256 of the exact input bytes. It accepts a filename or `-` for stdin, at most 2 MB, and rejects duplicate JSON keys and non-finite constants. Its output includes supplied source references: review inputs before sharing outputs.
+
+## Exact fact selection
+
+A query requires:
+
+| Field | Contract |
+| --- | --- |
+| `cik` | String of exactly 10 ASCII digits |
+| `taxonomy`, `concept`, `unit` | Nonempty strings; exact match, no alias or currency conversion |
+| `start`, `end` | ISO dates; use empty `start` for an instant fact |
+| `dimensions` | List of `{axis, member}` objects; unique axes; empty for consolidated scope |
+| `cutoff` | Date and time with a known timezone |
+| `mode` | `disclosure-reconstruction` or `observed-pipeline` |
+| `accession` | Optional exact filing filter, `##########-##-######` |
+
+Every fact needs the identity fields plus finite numeric `value`, `accession`, `acceptedAt`, `documentSha256` (64 lowercase hex characters), `contextId`, and an HTTPS `sourceUrl`. Values must have absolute magnitude at most 2^53−1. Booleans, NaN and infinity are rejected. Missing or null `observedAt` is permitted only for disclosure reconstruction. At most 2,000 facts and 32 dimensions per fact are accepted. All supplied facts must have valid required fields, including unmatched facts.
+
+The checker matches the full identity and selects the latest eligible acceptance time. Conflicting values, accessions or hashes at that time produce `ambiguous-latest-fact`. Duplicate facts with the same value, accession and hash are resolved by context ID. No source file is fetched. A syntactically valid URL, hash or timestamp is not evidence that it is authentic.
+
+Timestamps support 1–9 fractional digits and known offsets through ±14:00. Missing zones, `-00:00`, leap seconds, invalid calendar dates and years before 1900 are rejected. Comparisons retain nanosecond precision.
+
+### Two time modes
+
+- `disclosure-reconstruction`: use acceptance timestamps supplied by the caller. This reconstructs disclosure eligibility; it does not establish actual historical system access, market dissemination or tradability.
+- `observed-pipeline`: also require observation timestamps at or before cutoff and at or after acceptance. Unknown observation time on any matching accepted candidate withholds the answer instead of silently choosing an older fact.
+
+The caller must establish trustworthy timestamps independently. Collecting a document today cannot establish that the system observed it years ago.
+
+## Quarterly cash
+
+Call `quarterly_cash(facts, request)` with `cik`, `fiscalStart`, `quarterStart`, `end`, `cutoff`, and `mode`. Add `computedAt` in observed-pipeline mode. See `examples/quarterly-cash.json` for a complete request.
+
+Only consolidated `us-gaap` whole-USD facts for these two concepts are supported:
+
+- `NetCashProvidedByUsedInOperatingActivities`
+- `PaymentsToAcquirePropertyPlantAndEquipment`, expressed as a positive cash outflow
+
+An exact-quarter duration takes precedence. If none matches, current fiscal YTD minus the period ending immediately before the quarter is used. Missing prior periods withhold an answer. A matching but ineligible or ambiguous direct quarter also withholds rather than falling back. The caller supplies and verifies the issuer's fiscal calendar; the tool only checks date validity, ordering and a 60–120-day quarter length.
+
+All selected facts and filing versions remain in `inputs`. Different filing vintages may be combined; review their accessions and presentation comparability before use. Fractional cash dollars, out-of-range results and negative derived cash PP&E are withheld. In observed-pipeline mode, computation must occur after all input observations and no later than cutoff.
+
+`cashAfterPpe` excludes acquisitions, noncash additions, leases and other investment spending. It is not a universal free-cash-flow definition. No price data, factor returns, security universe or backtest performance is supplied.
+
+## Research and citation
+
+- [Point-in-time financial data research](https://ahasignals.com/research/point-in-time-financial-data/)
+- [Worked financial query checks](https://ahasignals.com/research/financial-query-correctness/)
+- [Related benchmark dataset](https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity)
+- [Related working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198)
+
+This package implements financial-query rules. It is not the frozen PIT benchmark scorer and does not reproduce the paper's model scores. Public calibration cases are not held-out evaluation. External datasets and papers retain their own versions and licenses; no third-party document bodies are bundled.
+
+For software use, cite: **AhaSignals. AhaSignals PIT, version 0.1.0.** Include the source commit and input dataset version used in your analysis. Cite the relevant paper separately when its research is used.
+
+## License and scope
+
+Code, documentation, tests and synthetic examples in this distribution: MIT, copyright AhaSignals. No attribution link or network call is required to execute the package. Dataset rights are separate from software rights.
+
+AhaSignals is an independent research publisher, unaffiliated with referenced regulators, issuers and platforms. Third-party names are factual source or compatibility references. Research and education only; no investment, trading, legal, accounting or tax advice. Passing these checks does not certify a backtest or establish predictive value.

ahasignals_pit-0.1.0/README.md

@@ -0,0 +1,101 @@
+# AhaSignals PIT
+
+Select financial facts that match a declared historical cutoff, then inspect the period, scope and source version behind each answer. Reconstruct quarterly operating cash flow less cash PP&E without treating cumulative cash flows as a quarter.
+
+Python 3.9 or later. No runtime dependencies. No network requests, telemetry, account or API key required. Version 0.1.0 is an initial alpha release with a deliberately narrow contract.
+
+## Install and run
+
+After the release is available on PyPI:
+
+```bash
+python -m pip install ahasignals-pit==0.1.0
+ahasignals-pit input.json
+# Equivalent:
+python -m ahasignals_pit input.json
+```
+
+For a source checkout, run `python -m pip install .` from this directory, then:
+
+```bash
+ahasignals-pit examples/select.json
+ahasignals-pit examples/quarterly-cash.json
+python -m unittest discover -s tests -v
+```
+
+Both examples are fully synthetic. Their identifiers, amounts, dates, example.org source URL and zero hash do not represent a real issuer or authenticated document. The first selects 120; the second returns quarterly operating cash of 160, cash PP&E of 40 and cash after PP&E of 120 USD. These are arithmetic examples, not investment results.
+
+## Python API
+
+```python
+import json
+from ahasignals_pit import run, select_fact, quarterly_cash
+
+with open('examples/select.json', encoding='utf-8') as stream:
+    payload = json.load(stream)
+result = select_fact(payload['facts'], payload['query'])
+assert result['status'] == 'answer'
+print(result['value'], result['inputs'])
+# run(payload) dispatches by task: select or quarterly-cash.
+```
+
+The public functions accept JSON-compatible dictionaries and lists. Input field names retain the camelCase contract of the related financial query checker. Output status is `answer`, `withheld` or `invalid`. Never replace a withheld value with zero. The CLI returns exit codes 0, 1 and 2 respectively; it also includes the package version and SHA-256 of the exact input bytes. It accepts a filename or `-` for stdin, at most 2 MB, and rejects duplicate JSON keys and non-finite constants. Its output includes supplied source references: review inputs before sharing outputs.
+
+## Exact fact selection
+
+A query requires:
+
+| Field | Contract |
+| --- | --- |
+| `cik` | String of exactly 10 ASCII digits |
+| `taxonomy`, `concept`, `unit` | Nonempty strings; exact match, no alias or currency conversion |
+| `start`, `end` | ISO dates; use empty `start` for an instant fact |
+| `dimensions` | List of `{axis, member}` objects; unique axes; empty for consolidated scope |
+| `cutoff` | Date and time with a known timezone |
+| `mode` | `disclosure-reconstruction` or `observed-pipeline` |
+| `accession` | Optional exact filing filter, `##########-##-######` |
+
+Every fact needs the identity fields plus finite numeric `value`, `accession`, `acceptedAt`, `documentSha256` (64 lowercase hex characters), `contextId`, and an HTTPS `sourceUrl`. Values must have absolute magnitude at most 2^53−1. Booleans, NaN and infinity are rejected. Missing or null `observedAt` is permitted only for disclosure reconstruction. At most 2,000 facts and 32 dimensions per fact are accepted. All supplied facts must have valid required fields, including unmatched facts.
+
+The checker matches the full identity and selects the latest eligible acceptance time. Conflicting values, accessions or hashes at that time produce `ambiguous-latest-fact`. Duplicate facts with the same value, accession and hash are resolved by context ID. No source file is fetched. A syntactically valid URL, hash or timestamp is not evidence that it is authentic.
+
+Timestamps support 1–9 fractional digits and known offsets through ±14:00. Missing zones, `-00:00`, leap seconds, invalid calendar dates and years before 1900 are rejected. Comparisons retain nanosecond precision.
+
+### Two time modes
+
+- `disclosure-reconstruction`: use acceptance timestamps supplied by the caller. This reconstructs disclosure eligibility; it does not establish actual historical system access, market dissemination or tradability.
+- `observed-pipeline`: also require observation timestamps at or before cutoff and at or after acceptance. Unknown observation time on any matching accepted candidate withholds the answer instead of silently choosing an older fact.
+
+The caller must establish trustworthy timestamps independently. Collecting a document today cannot establish that the system observed it years ago.
+
+## Quarterly cash
+
+Call `quarterly_cash(facts, request)` with `cik`, `fiscalStart`, `quarterStart`, `end`, `cutoff`, and `mode`. Add `computedAt` in observed-pipeline mode. See `examples/quarterly-cash.json` for a complete request.
+
+Only consolidated `us-gaap` whole-USD facts for these two concepts are supported:
+
+- `NetCashProvidedByUsedInOperatingActivities`
+- `PaymentsToAcquirePropertyPlantAndEquipment`, expressed as a positive cash outflow
+
+An exact-quarter duration takes precedence. If none matches, current fiscal YTD minus the period ending immediately before the quarter is used. Missing prior periods withhold an answer. A matching but ineligible or ambiguous direct quarter also withholds rather than falling back. The caller supplies and verifies the issuer's fiscal calendar; the tool only checks date validity, ordering and a 60–120-day quarter length.
+
+All selected facts and filing versions remain in `inputs`. Different filing vintages may be combined; review their accessions and presentation comparability before use. Fractional cash dollars, out-of-range results and negative derived cash PP&E are withheld. In observed-pipeline mode, computation must occur after all input observations and no later than cutoff.
+
+`cashAfterPpe` excludes acquisitions, noncash additions, leases and other investment spending. It is not a universal free-cash-flow definition. No price data, factor returns, security universe or backtest performance is supplied.
+
+## Research and citation
+
+- [Point-in-time financial data research](https://ahasignals.com/research/point-in-time-financial-data/)
+- [Worked financial query checks](https://ahasignals.com/research/financial-query-correctness/)
+- [Related benchmark dataset](https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity)
+- [Related working paper](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198)
+
+This package implements financial-query rules. It is not the frozen PIT benchmark scorer and does not reproduce the paper's model scores. Public calibration cases are not held-out evaluation. External datasets and papers retain their own versions and licenses; no third-party document bodies are bundled.
+
+For software use, cite: **AhaSignals. AhaSignals PIT, version 0.1.0.** Include the source commit and input dataset version used in your analysis. Cite the relevant paper separately when its research is used.
+
+## License and scope
+
+Code, documentation, tests and synthetic examples in this distribution: MIT, copyright AhaSignals. No attribution link or network call is required to execute the package. Dataset rights are separate from software rights.
+
+AhaSignals is an independent research publisher, unaffiliated with referenced regulators, issuers and platforms. Third-party names are factual source or compatibility references. Research and education only; no investment, trading, legal, accounting or tax advice. Passing these checks does not certify a backtest or establish predictive value.

ahasignals_pit-0.1.0/examples/quarterly-cash.json

@@ -0,0 +1,78 @@
+{
+  "exampleKind": "fully-synthetic-not-company-data",
+  "task": "quarterly-cash",
+  "facts": [
+    {
+      "cik": "0000000001",
+      "taxonomy": "us-gaap",
+      "concept": "NetCashProvidedByUsedInOperatingActivities",
+      "unit": "USD",
+      "start": "2025-01-01",
+      "end": "2025-03-31",
+      "dimensions": [],
+      "value": 120,
+      "accession": "0000000001-25-000001",
+      "acceptedAt": "2025-05-01T00:00:00Z",
+      "observedAt": "2025-05-02T00:00:00Z",
+      "sourceUrl": "https://example.org/synthetic-filing",
+      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "contextId": "synthetic-q1"
+    },
+    {
+      "cik": "0000000001",
+      "taxonomy": "us-gaap",
+      "concept": "NetCashProvidedByUsedInOperatingActivities",
+      "unit": "USD",
+      "start": "2025-01-01",
+      "end": "2025-06-30",
+      "dimensions": [],
+      "value": 280,
+      "accession": "0000000001-25-000002",
+      "acceptedAt": "2025-08-01T00:00:00Z",
+      "observedAt": "2025-08-02T00:00:00Z",
+      "sourceUrl": "https://example.org/synthetic-filing",
+      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "contextId": "synthetic-h1"
+    },
+    {
+      "cik": "0000000001",
+      "taxonomy": "us-gaap",
+      "concept": "PaymentsToAcquirePropertyPlantAndEquipment",
+      "unit": "USD",
+      "start": "2025-01-01",
+      "end": "2025-03-31",
+      "dimensions": [],
+      "value": 50,
+      "accession": "0000000001-25-000001",
+      "acceptedAt": "2025-05-01T00:00:00Z",
+      "observedAt": "2025-05-02T00:00:00Z",
+      "sourceUrl": "https://example.org/synthetic-filing",
+      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "contextId": "synthetic-q1"
+    },
+    {
+      "cik": "0000000001",
+      "taxonomy": "us-gaap",
+      "concept": "PaymentsToAcquirePropertyPlantAndEquipment",
+      "unit": "USD",
+      "start": "2025-01-01",
+      "end": "2025-06-30",
+      "dimensions": [],
+      "value": 90,
+      "accession": "0000000001-25-000002",
+      "acceptedAt": "2025-08-01T00:00:00Z",
+      "observedAt": "2025-08-02T00:00:00Z",
+      "sourceUrl": "https://example.org/synthetic-filing",
+      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "contextId": "synthetic-h1"
+    }
+  ],
+  "request": {
+    "cik": "0000000001",
+    "fiscalStart": "2025-01-01",
+    "quarterStart": "2025-04-01",
+    "end": "2025-06-30",
+    "cutoff": "2025-09-01T00:00:00Z",
+    "mode": "disclosure-reconstruction"
+  }
+}

ahasignals_pit-0.1.0/examples/select.json

@@ -0,0 +1,33 @@
+{
+  "exampleKind": "fully-synthetic-not-company-data",
+  "task": "select",
+  "facts": [
+    {
+      "cik": "0000000001",
+      "taxonomy": "us-gaap",
+      "concept": "NetCashProvidedByUsedInOperatingActivities",
+      "unit": "USD",
+      "start": "2025-01-01",
+      "end": "2025-03-31",
+      "dimensions": [],
+      "value": 120,
+      "accession": "0000000001-25-000001",
+      "acceptedAt": "2025-05-01T00:00:00Z",
+      "observedAt": "2025-05-02T00:00:00Z",
+      "sourceUrl": "https://example.org/synthetic-filing",
+      "documentSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "contextId": "synthetic-q1"
+    }
+  ],
+  "query": {
+    "cik": "0000000001",
+    "taxonomy": "us-gaap",
+    "concept": "NetCashProvidedByUsedInOperatingActivities",
+    "unit": "USD",
+    "start": "2025-01-01",
+    "end": "2025-03-31",
+    "dimensions": [],
+    "cutoff": "2025-09-01T00:00:00Z",
+    "mode": "disclosure-reconstruction"
+  }
+}

ahasignals_pit-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling==1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ahasignals-pit"
+version = "0.1.0"
+description = "Point-in-time financial fact selection and quarterly cash-flow checks"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "AhaSignals"}]
+maintainers = [{name = "AhaSignals", email = "research@ahasignals.com"}]
+keywords = ["point-in-time", "financial-data", "reproducibility", "backtesting"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Operating System :: OS Independent",
+  "Topic :: Office/Business :: Financial",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://ahasignals.com/research/point-in-time-financial-data/"
+Documentation = "https://ahasignals.com/examples/ahasignals-pit/v0.1.0/README.md"
+Source = "https://ahasignals.com/examples/ahasignals-pit/v0.1.0/ahasignals_pit-0.1.0.tar.gz"
+"Related benchmark dataset" = "https://huggingface.co/datasets/AhaSignals/financial-ai-pit-integrity"
+"Related paper" = "https://papers.ssrn.com/sol3/papers.cfm?abstract_id=7415198"
+
+[project.scripts]
+ahasignals-pit = "ahasignals_pit.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ahasignals_pit"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["src/ahasignals_pit", "tests/test_core.py", "examples/select.json", "examples/quarterly-cash.json", "README.md", "LICENSE", "pyproject.toml", "CHANGELOG.md"]

ahasignals_pit-0.1.0/src/ahasignals_pit/__init__.py

@@ -0,0 +1,5 @@
+"""AhaSignals point-in-time financial fact checks. No network access."""
+from .core import quarterly_cash, run, select_fact
+
+__version__ = '0.1.0'
+__all__ = ['quarterly_cash', 'run', 'select_fact', '__version__']

ahasignals_pit-0.1.0/src/ahasignals_pit/__main__.py

@@ -0,0 +1,46 @@
+"""JSON CLI. Exit 0: answer; 1: withheld; 2: invalid input."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import sys
+from . import __version__, run
+
+
+def _object(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError('duplicate JSON key')
+        result[key] = value
+    return result
+
+
+def _constant(value):
+    raise ValueError('non-finite JSON constant')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--version', action='version', version=__version__)
+    parser.add_argument('input', help='JSON file, or - for stdin; at most 2 MB')
+    args = parser.parse_args()
+    try:
+        if args.input == '-':
+            raw = sys.stdin.buffer.read(2_000_001)
+        else:
+            with Path(args.input).open('rb') as stream:
+                raw = stream.read(2_000_001)
+        if len(raw) > 2_000_000:
+            raise ValueError('input size')
+        payload = json.loads(raw.decode('utf-8'), object_pairs_hook=_object, parse_constant=_constant)
+        result = run(payload)
+        print(json.dumps(dict(version=__version__, inputSha256=hashlib.sha256(raw).hexdigest(), **result), allow_nan=False, indent=2))
+        return {'answer': 0, 'withheld': 1, 'invalid': 2}[result['status']]
+    except (OSError, ValueError, TypeError, RecursionError, OverflowError):
+        print('Invalid input. Supply a UTF-8 JSON file no larger than 2 MB with unique keys and finite numbers.', file=sys.stderr)
+        return 2
+
+
+if __name__ == '__main__':
+    sys.exit(main())

ahasignals_pit-0.1.0/src/ahasignals_pit/core.py

@@ -0,0 +1,209 @@
+"""Deterministic checks of supplied facts, provenance fields and declared clocks."""
+from copy import deepcopy
+from datetime import date, datetime, timedelta
+import math
+import re
+
+MAX_VALUE = 2**53 - 1
+MODES = ('disclosure-reconstruction', 'observed-pipeline')
+CLOCK = re.compile(r'(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})', re.ASCII)
+EVIDENCE = ('cik', 'taxonomy', 'concept', 'unit', 'start', 'end', 'dimensions',
+            'value', 'accession', 'acceptedAt', 'observedAt', 'sourceUrl',
+            'documentSha256', 'contextId')
+
+
+def _matches(pattern, value):
+    return isinstance(value, str) and re.fullmatch(pattern, value, re.ASCII) is not None
+
+
+def _instant(value):
+    """Return integer nanoseconds, rejecting ambiguous zones and invalid dates."""
+    if not isinstance(value, str):
+        return None
+    m = CLOCK.fullmatch(value)
+    if not m:
+        return None
+    year, month, day, hour, minute, second = map(int, m.groups()[:6])
+    fraction, zone = m.groups()[6:]
+    if year < 1900 or zone == '-00:00':
+        return None
+    try:
+        clock = datetime(year, month, day, hour, minute, second)
+    except ValueError:
+        return None
+    offset = 0
+    if zone != 'Z':
+        hours, minutes = int(zone[1:3]), int(zone[4:6])
+        if hours > 14 or minutes > 59 or (hours == 14 and minutes):
+            return None
+        offset = (hours * 60 + minutes) * 60 * (1 if zone[0] == '+' else -1)
+    delta = clock - datetime(1970, 1, 1)
+    return (delta.days * 86400 + delta.seconds - offset) * 10**9 + int((fraction or '').ljust(9, '0'))
+
+
+def _date(value):
+    return _matches(r'\d{4}-\d{2}-\d{2}', value) and _instant(value + 'T00:00:00Z') is not None
+
+
+def _text(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _dimensions(value):
+    if not isinstance(value, list) or len(value) > 32:
+        return None
+    pairs = []
+    axes = set()
+    for item in value:
+        if (not isinstance(item, dict) or set(item) != {'axis', 'member'}
+                or not _text(item['axis']) or not _text(item['member']) or item['axis'] in axes):
+            return None
+        axes.add(item['axis'])
+        pairs.append((item['axis'], item['member']))
+    return tuple(sorted(pairs))
+
+
+def _identity(value):
+    return (isinstance(value, dict) and _matches(r'\d{10}', value.get('cik'))
+            and all(_text(value.get(k)) for k in ('taxonomy', 'concept', 'unit'))
+            and _date(value.get('end'))
+            and (value.get('start') == '' or (_date(value.get('start')) and value['start'] <= value['end']))
+            and _dimensions(value.get('dimensions')) is not None)
+
+
+def _key(value):
+    return tuple(value[k] for k in ('cik', 'taxonomy', 'concept', 'unit', 'start', 'end')) + (_dimensions(value['dimensions']),)
+
+
+def _number(value):
+    return type(value) in (int, float) and abs(value) <= MAX_VALUE and math.isfinite(value)
+
+
+def _whole(value):
+    return _number(value) and int(value) == value
+
+
+def _valid_fact(fact):
+    return (_identity(fact) and _number(fact.get('value'))
+            and _matches(r'\d{10}-\d{2}-\d{6}', fact.get('accession'))
+            and _instant(fact.get('acceptedAt')) is not None
+            and _matches(r'[a-f0-9]{64}', fact.get('documentSha256'))
+            and _text(fact.get('contextId')) and isinstance(fact.get('sourceUrl'), str)
+            and fact['sourceUrl'].startswith('https://'))
+
+
+def _stop(reason, status='withheld'):
+    return dict(status=status, reason=reason, value=None, inputs=[])
+
+
+def select_fact(facts, query):
+    """Select the latest eligible exact context; return answer/withheld/invalid.
+
+    Inputs use the camelCase JSON contract documented in README.md. This does
+    not fetch documents or authenticate their hashes or declared timestamps.
+    """
+    if (not isinstance(facts, list) or len(facts) > 2000 or not _identity(query)
+            or _instant(query.get('cutoff')) is None or query.get('mode') not in MODES):
+        return _stop('invalid-query-or-facts', 'invalid')
+    if 'accession' in query and not _matches(r'\d{10}-\d{2}-\d{6}', query['accession']):
+        return _stop('invalid-accession-filter', 'invalid')
+    if not all(_valid_fact(f) for f in facts):
+        return _stop('invalid-fact-or-missing-provenance', 'invalid')
+    matched = [f for f in facts if _key(f) == _key(query) and ('accession' not in query or f['accession'] == query['accession'])]
+    if not matched:
+        return _stop('no-matching-context')
+    cutoff = _instant(query['cutoff'])
+    accepted = [f for f in matched if _instant(f['acceptedAt']) <= cutoff]
+    if not accepted:
+        return _stop('source-after-cutoff')
+    eligible = accepted
+    if query['mode'] == 'observed-pipeline':
+        if any(_instant(f.get('observedAt')) is None for f in accepted):
+            return _stop('unknown-observation-time')
+        if any(_instant(f['observedAt']) < _instant(f['acceptedAt']) for f in accepted):
+            return _stop('observation-before-acceptance')
+        eligible = [f for f in accepted if _instant(f['observedAt']) <= cutoff]
+        if not eligible:
+            return _stop('observation-after-cutoff')
+    latest = max(_instant(f['acceptedAt']) for f in eligible)
+    selected = [f for f in eligible if _instant(f['acceptedAt']) == latest]
+    if len({(f['value'], f['accession'], f['documentSha256']) for f in selected}) != 1:
+        return _stop('ambiguous-latest-fact')
+    fact = min(selected, key=lambda f: f['contextId'])
+    return dict(status='answer', reason='latest-eligible-exact-context', value=fact['value'],
+                inputs=[{k: deepcopy(fact.get(k)) for k in EVIDENCE}], mode=query['mode'], cutoff=query['cutoff'])
+
+
+def quarterly_cash(facts, request):
+    """Reconstruct consolidated whole-USD quarterly OCF less cash PP&E.
+
+    Exact-quarter duration wins; otherwise subtract matched fiscal YTD periods.
+    This is not a universal free-cash-flow definition or a trading signal.
+    """
+    if not isinstance(request, dict):
+        return _stop('invalid-quarter-request', 'invalid')
+    fiscal, start, end = (request.get(k) for k in ('fiscalStart', 'quarterStart', 'end'))
+    mode, cutoff, computed = (request.get(k) for k in ('mode', 'cutoff', 'computedAt'))
+    if (not all(_date(d) for d in (fiscal, start, end)) or fiscal > start or start > end
+            or mode not in MODES or _instant(cutoff) is None):
+        return _stop('invalid-quarter-request', 'invalid')
+    if not 60 <= (date.fromisoformat(end) - date.fromisoformat(start)).days + 1 <= 120:
+        return _stop('not-a-quarter-length')
+    previous = (date.fromisoformat(start) - timedelta(days=1)).isoformat()
+    inputs, amounts, methods = [], {}, []
+    for name, concept in (('operatingCash', 'NetCashProvidedByUsedInOperatingActivities'),
+                          ('cashPpe', 'PaymentsToAcquirePropertyPlantAndEquipment')):
+        query = dict(cik=request.get('cik'), taxonomy='us-gaap', concept=concept, unit='USD',
+                     start=fiscal, end=end, dimensions=[], cutoff=cutoff, mode=mode)
+        direct = select_fact(facts, dict(query, start=start))
+        if direct['status'] == 'answer':
+            if not _whole(direct['value']):
+                return _stop('cash-values-must-be-exact-whole-dollars')
+            amounts[name] = int(direct['value'])
+            inputs.extend(direct['inputs'])
+            methods.append('direct-quarter-duration')
+            continue
+        if direct['reason'] != 'no-matching-context':
+            return dict(direct, reason=name + ':' + direct['reason'])
+        current = select_fact(facts, query)
+        if current['status'] != 'answer':
+            return dict(current, reason=name + ':' + current['reason'])
+        prior = dict(value=0, inputs=[])
+        if fiscal != start:
+            prior = select_fact(facts, dict(query, end=previous))
+            if prior['status'] != 'answer':
+                return dict(prior, reason=name + ':' + prior['reason'])
+        if not all(_whole(v) for v in (current['value'], prior['value'])):
+            return _stop('cash-values-must-be-exact-whole-dollars')
+        amounts[name] = int(current['value']) - int(prior['value'])
+        inputs.extend(current['inputs'] + prior['inputs'])
+        methods.append('difference-of-matched-ytd-periods')
+    if amounts['cashPpe'] < 0:
+        return _stop('negative-cash-ppe-needs-source-review')
+    cash = amounts['operatingCash'] - amounts['cashPpe']
+    if not all(_whole(v) for v in (*amounts.values(), cash)):
+        return _stop('derived-value-out-of-range')
+    if mode == 'observed-pipeline':
+        ct = _instant(computed)
+        if ct is None:
+            return _stop('unknown-computation-time')
+        if ct > _instant(cutoff):
+            return _stop('computation-after-cutoff')
+        if any(_instant(f['observedAt']) > ct for f in inputs):
+            return _stop('computation-before-input')
+    return dict(status='answer', reason='+'.join(dict.fromkeys(methods)), **amounts,
+                cashAfterPpe=cash, unit='USD', start=start, end=end, cutoff=cutoff,
+                mode=mode, computedAt=computed, inputs=inputs,
+                selectionPolicy='Latest eligible filing per exact fiscal period; cross-filing inputs are identified, not assumed to have a common presentation vintage.',
+                boundary='Declared consolidated US-GAAP cash flows. Cash PP&E excludes noncash additions and other investment spending. No historical observation or computation time is inferred; no predictive claim.')
+
+
+def run(payload):
+    """Dispatch a JSON-compatible select or quarterly-cash request."""
+    if not isinstance(payload, dict):
+        return dict(status='invalid', reason='invalid-input')
+    if payload.get('task') == 'select':
+        return select_fact(payload.get('facts'), payload.get('query'))
+    if payload.get('task') == 'quarterly-cash':
+        return quarterly_cash(payload.get('facts'), payload.get('request'))
+    return dict(status='invalid', reason='unknown-task')

ahasignals_pit-0.1.0/tests/test_core.py

@@ -0,0 +1,155 @@
+"""Synthetic regression tests; no issuer data or network access."""
+import copy
+import json
+from pathlib import Path
+import subprocess
+import sys
+import unittest
+from ahasignals_pit import run, select_fact, quarterly_cash
+from ahasignals_pit.core import _instant, MAX_VALUE
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class Checks(unittest.TestCase):
+    def setUp(self):
+        self.select = json.loads((ROOT / 'examples/select.json').read_text())
+        self.cash = json.loads((ROOT / 'examples/quarterly-cash.json').read_text())
+        self.facts, self.query = self.select['facts'], self.select['query']
+
+    def test_examples(self):
+        self.assertEqual(run(self.select)['value'], 120)
+        result = run(self.cash)
+        self.assertEqual((result['operatingCash'], result['cashPpe'], result['cashAfterPpe']), (160, 40, 120))
+        self.assertEqual(len(result['inputs']), 4)
+
+    def test_future_revision_excluded(self):
+        self.facts.append(dict(self.facts[0], value=999, acceptedAt='2026-01-01T00:00:00Z'))
+        self.assertEqual(run(self.select)['value'], 120)
+        self.query['cutoff'] = '2026-02-01T00:00:00Z'
+        self.assertEqual(run(self.select)['value'], 999)
+
+    def test_exact_identity(self):
+        for field, value in [('unit', 'EUR'), ('start', '2025-02-01'), ('concept', 'other'), ('cik', '0000000002'), ('dimensions', [{'axis': 'segment', 'member': 'cloud'}])]:
+            with self.subTest(field=field):
+                self.assertEqual(select_fact(self.facts, dict(self.query, **{field: value}))['reason'], 'no-matching-context')
+
+    def test_dimension_order_and_duplicate_axes(self):
+        dims = [{'axis': 'b', 'member': '2'}, {'axis': 'a', 'member': '1'}]
+        self.facts[0]['dimensions'] = dims
+        self.query['dimensions'] = dims[::-1]
+        self.assertEqual(run(self.select)['status'], 'answer')
+        self.query['dimensions'] = dims + [dims[0]]
+        self.assertEqual(run(self.select)['status'], 'invalid')
+
+    def test_conflicting_latest_and_duplicate(self):
+        self.facts.append(dict(self.facts[0], contextId='a'))
+        self.assertEqual(run(self.select)['inputs'][0]['contextId'], 'a')
+        self.facts[1]['value'] = 121
+        self.assertEqual(run(self.select)['reason'], 'ambiguous-latest-fact')
+
+    def test_observation_modes(self):
+        self.facts[0]['observedAt'] = None
+        self.assertEqual(run(self.select)['status'], 'answer')
+        self.query['mode'] = 'observed-pipeline'
+        self.assertEqual(run(self.select)['reason'], 'unknown-observation-time')
+        self.facts[0]['observedAt'] = '2025-04-01T00:00:00Z'
+        self.assertEqual(run(self.select)['reason'], 'observation-before-acceptance')
+        self.facts[0]['observedAt'] = '2025-10-01T00:00:00Z'
+        self.assertEqual(run(self.select)['reason'], 'observation-after-cutoff')
+
+    def test_unknown_newer_observation_withholds(self):
+        self.query['mode'] = 'observed-pipeline'
+        self.facts.append(dict(self.facts[0], acceptedAt='2025-08-01T00:00:00Z', observedAt=None))
+        self.assertEqual(run(self.select)['reason'], 'unknown-observation-time')
+
+    def test_strict_clocks(self):
+        for value in ['2025-02-30T00:00:00Z', '2025-01-01', '2025-01-01T00:00:00-00:00', '2025-01-01T00:00:00+14:01', '2025-01-01T00:00:60Z']:
+            self.assertIsNone(_instant(value))
+        self.assertEqual(_instant('2025-01-01T01:00:00+01:00'), _instant('2025-01-01T00:00:00Z'))
+        self.assertEqual(_instant('2025-01-01T00:00:00.000000001Z') - _instant('2025-01-01T00:00:00Z'), 1)
+
+    def test_nanosecond_cutoff(self):
+        self.facts[0]['acceptedAt'] = '2025-05-01T00:00:00.000000001Z'
+        self.query['cutoff'] = '2025-05-01T00:00:00Z'
+        self.assertEqual(run(self.select)['reason'], 'source-after-cutoff')
+
+    def test_invalid_values(self):
+        for value in [True, float('nan'), float('inf'), MAX_VALUE + 1, 10**500, '120', None]:
+            with self.subTest(value=type(value).__name__):
+                self.assertEqual(select_fact([dict(self.facts[0], value=value)], self.query)['status'], 'invalid')
+
+    def test_invalid_shapes(self):
+        for bad in [None, [], True, 7, 'x']:
+            self.assertEqual(select_fact([bad], self.query)['status'], 'invalid')
+            self.assertEqual(select_fact(self.facts, bad)['status'], 'invalid')
+            self.assertEqual(quarterly_cash(self.facts, bad)['status'], 'invalid')
+        self.assertEqual(select_fact(self.facts * 2001, self.query)['status'], 'invalid')
+
+    def test_missing_provenance(self):
+        for field in ['accession', 'acceptedAt', 'documentSha256', 'contextId', 'sourceUrl']:
+            fact = dict(self.facts[0]); del fact[field]
+            self.assertEqual(select_fact([fact], self.query)['status'], 'invalid')
+
+    def test_accession_filter(self):
+        q = dict(self.query, accession='0000000001-25-000002')
+        self.assertEqual(select_fact(self.facts, q)['reason'], 'no-matching-context')
+        q['accession'] = None
+        self.assertEqual(select_fact(self.facts, q)['status'], 'invalid')
+
+    def test_missing_prior_cash(self):
+        self.cash['facts'] = self.cash['facts'][1:]
+        self.assertEqual(run(self.cash)['reason'], 'operatingCash:no-matching-context')
+
+    def test_direct_quarter_wins(self):
+        direct = dict(self.cash['facts'][1], start='2025-04-01', value=180)
+        self.cash['facts'].append(direct)
+        self.assertEqual(run(self.cash)['operatingCash'], 180)
+        direct['acceptedAt'] = '2026-01-01T00:00:00Z'
+        self.assertEqual(run(self.cash)['reason'], 'operatingCash:source-after-cutoff')
+
+    def test_negative_ppe(self):
+        self.cash['facts'][3]['value'] = 40
+        self.assertEqual(run(self.cash)['reason'], 'negative-cash-ppe-needs-source-review')
+
+    def test_cash_fractions_and_range(self):
+        self.cash['facts'][1]['value'] = 280.5
+        self.assertEqual(run(self.cash)['reason'], 'cash-values-must-be-exact-whole-dollars')
+        self.cash['facts'][1]['value'] = MAX_VALUE
+        self.cash['facts'][0]['value'] = -120
+        self.assertEqual(run(self.cash)['reason'], 'derived-value-out-of-range')
+
+    def test_quarter_length(self):
+        self.cash['request']['quarterStart'] = '2025-06-01'
+        self.assertEqual(run(self.cash)['reason'], 'not-a-quarter-length')
+
+    def test_computation_clock(self):
+        self.cash['request']['mode'] = 'observed-pipeline'
+        for computed, reason in [(None, 'unknown-computation-time'), ('2025-10-01T00:00:00Z', 'computation-after-cutoff'), ('2025-08-01T00:00:00Z', 'computation-before-input')]:
+            self.cash['request']['computedAt'] = computed
+            self.assertEqual(run(self.cash)['reason'], reason)
+        self.cash['request']['computedAt'] = '2025-08-03T00:00:00Z'
+        self.assertEqual(run(self.cash)['status'], 'answer')
+
+    def test_no_mutation(self):
+        before = copy.deepcopy(self.select)
+        result = run(self.select)
+        result['inputs'][0]['dimensions'].append({'axis': 'x', 'member': 'y'})
+        self.assertEqual(before, self.select)
+
+    def test_cli(self):
+        def cli(raw):
+            return subprocess.run([sys.executable, '-m', 'ahasignals_pit', '-'], input=raw, capture_output=True)
+        good = cli(json.dumps(self.select).encode())
+        self.assertEqual(good.returncode, 0)
+        self.assertEqual(len(json.loads(good.stdout)['inputSha256']), 64)
+        self.query['cutoff'] = '2024-01-01T00:00:00Z'
+        self.assertEqual(cli(json.dumps(self.select).encode()).returncode, 1)
+        for raw in [b'{"task":"select","task":"x"}', b'NaN', b'{' , b' ' * 2_000_001]:
+            result = cli(raw)
+            self.assertEqual(result.returncode, 2)
+            self.assertNotIn(b'Traceback', result.stderr)
+
+
+if __name__ == '__main__':
+    unittest.main()