settfex 0.24.2__tar.gz → 0.26.0__tar.gz

settfex-0.26.0/.github/workflows/live-smoke.yml

@@ -0,0 +1,81 @@
+# Live smoke — the integration probes against the real SET / TFEX / SEC / ThaiBMA hosts, weekly.
+#
+# INERT BY DESIGN. Nothing runs until BOTH of these are true:
+#   1. a self-hosted runner labelled `thailand` is registered for this repository, and
+#   2. the repository variable LIVE_SMOKE_ENABLED is set to `true`.
+# Until then the job is skipped on every trigger, and no request leaves any machine.
+#
+# Why self-hosted, and why in Thailand: nothing ran the `integration` marker, so the live endpoints
+# had no pass/fail history (#135). GitHub-hosted runners sit outside Thailand, and SET's and SEC's
+# bot protection treats datacenter IPs differently from a Thai residential one, so a green run
+# there would not mean what it appears to mean.
+#
+# BEFORE ENABLING — read these, they are the reason this ships switched off:
+#   * Every machine on the home network shares ONE egress IP with production SET market capture,
+#     which cannot be backfilled. A WAF block on that IP would hit the capture too. Pick a window
+#     that never overlaps a SET session or the sec-idisc-archive's traffic; the schedule below is
+#     a Sunday-morning placeholder, not a verified quiet window.
+#   * This repository is PUBLIC. A self-hosted runner on a public repo can be made to run code
+#     from a pull request. Before registering one, set Settings → Actions → "Fork pull request
+#     workflows" approval to ALL outside contributors (it is `first_time_contributors` today).
+#     This workflow itself runs only on schedule and manual dispatch, never on pull_request.
+#
+# Politeness, enforced rather than remembered (CLAUDE.md, "Live probes — politeness budget"):
+#   * concurrency 1, and `-x`: the first failure may be a WAF block, and the next request deepens it
+#   * SETTFEX_LIVE_BUDGET caps request ATTEMPTS through the fetcher (tests/integration/conftest.py);
+#     the cap refuses the next request rather than sending it. Session warmups (one page view per
+#     site) are not counted.
+#   * no retry ladders: the live tests make one attempt each
+#
+# The holiday endpoint has answered 401 upstream since 2026-09-20 (#140), so it runs as a SIGNAL in
+# its own step (continue-on-error) — it would otherwise keep the gate red for a reason no settfex
+# change can fix.
+
+name: Live smoke
+
+on:
+  schedule:
+    - cron: "17 3 * * 0" # Sundays 03:17 UTC (10:17 Asia/Bangkok) — placeholder, see above
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: live-smoke
+  cancel-in-progress: false
+
+jobs:
+  live:
+    name: Live endpoints (Thailand runner)
+    if: vars.LIVE_SMOKE_ENABLED == 'true' && github.repository == 'lumduan/settfex'
+    runs-on: [self-hosted, linux, thailand]
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v7
+
+      # setup-uv stopped publishing floating major tags at v8 — pin the exact version.
+      - uses: astral-sh/setup-uv@v10.1.0
+        with:
+          # Pinned by hand like every other setup-uv step; the monthly drift report checks them all.
+          version: "0.12.17"
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - run: uv python install 3.11
+      - run: uv sync --group dev --frozen
+
+      - name: Live probes (gate)
+        env:
+          SETTFEX_LIVE_BUDGET: "60"
+        run: >-
+          uv run pytest tests/integration -m integration --no-cov -x
+          --deselect tests/integration/test_live_endpoints.py::test_live_set_holidays
+
+      - name: Holiday endpoint (signal, not a gate — #140)
+        continue-on-error: true
+        env:
+          SETTFEX_LIVE_BUDGET: "1"
+        run: >-
+          uv run pytest -m integration --no-cov
+          tests/integration/test_live_endpoints.py::test_live_set_holidays

{settfex-0.24.2 → settfex-0.26.0}/.pre-commit-config.yaml

@@ -21,11 +21,12 @@ repos:
       # The SEC listing fixtures are response bodies captured VERBATIM -- byte ranges of what the
       # server sent, with their sha256 recorded in fixtures_sec/README.md. These two hooks rewrite
       # a file's trailing bytes, which would break both the byte-exactness and those hashes. The
-      # live pages genuinely end without a newline; that is data, not untidiness.
+      # live pages genuinely end without a newline; that is data, not untidiness. The Form 59
+      # detail fixtures (r59/*.json) are verbatim API bodies on the same terms.
       - id: trailing-whitespace
-        exclude: ^tests/services/sec/fixtures_sec/.*\.html$
+        exclude: ^tests/services/sec/fixtures_sec/.*\.(html|json)$
       - id: end-of-file-fixer
-        exclude: ^tests/services/sec/fixtures_sec/.*\.html$
+        exclude: ^tests/services/sec/fixtures_sec/.*\.(html|json)$
       - id: check-yaml
       - id: check-toml
       - id: check-added-large-files

{settfex-0.24.2 → settfex-0.26.0}/AGENTS.md

@@ -110,6 +110,8 @@ Indices: `get_index_list(lang)`, `get_index_info(symbol, lang)`,
 | resolve a company to its SEC id | `resolve_company(query, lang, allow_name_match=False)` |
 | list filings (financial statements, 56-1, 56-2, ratios, MD&A) | `get_sec_documents(query, types=..., from_date=..., to_date=...)` |
 | download the actual file(s) | `download_sec_document(target)` / `download_sec_documents(targets)` |
+| directors'/executives' trades (Form 59, แบบ 59) | `get_executive_trades(received_date=None, symbol=..., date_type=..., start=..., end=..., with_details=False)` |
+| one Form 59 report with holdings before/after | `get_executive_trade_report(batch_no)` |
 
 Dates here are **dd/mm/yyyy**. Pass a wide window to see full year history.
 
@@ -185,6 +187,69 @@ Also a Pydantic model since 0.24.0 (`{files, failed, requested}` + computed `is_
 failure report survives `model_dump()` and slicing. ⚠️ `isinstance(files, list)` is `False`; use
 `files.files`.
 
+**Form 59 (executive trades) — four traps before you count anything:**
+
+- **`reporter_name` is who FILED, not who traded.** The trader is `executor_name` / `executor_id`
+  (a spouse, a minor child, a family company). `is_self` says whether they are the same.
+- **One trade can be listed twice**: by both spouses when both are executives, or by two executives
+  for one company they control. The copy has `duplicate_of`; `duplicate_basis` says why
+  (`holdings` / `executor_own_row` / `executor`). `holding_conflict` is True when the two filings
+  disagree on the holdings, False when both are known and agree, and **None when unknown** (a
+  report was not fetched) — never read None as "no conflict". Rows are never dropped.
+- **Revoked filings stay listed** (`is_revoked=True`, about 5% of rows, mostly re-filings); with
+  `with_details=True` a transaction its report marks `CANCELED` is void too.
+- So **count on `result.economic_trades()`**, which drops copies and void rows. `to_table()`
+  already skips void rows. **Known overcount:** a trade the same reporter filed twice in different
+  batches, with the first left live, is counted twice (duplicates are never merged within one
+  reporter). Example: CREDIT 2026-09-28, 10,000 shares, rows 165104_2_1 and 165237_3_1.
+
+With no arguments `get_executive_trades()` returns what SEC **received today**, which is not the
+site's default page (that one shows what was *recorded* today), and today's set can still grow.
+The listing `price` is rounded to 2 dp; `with_details=True` (at most 100 reports per call) adds
+`detail.avg_price` at full precision and the holdings. A page whose stated count differs from its
+rows raises `ParseError`, so a result you receive is complete. A method label the library does not
+know shows `side="other"` and is counted on `result.unknown_labels`.
+
+**Form 59 recipes — question → call → what to read:**
+
+| Question | Call | Read |
+|---|---|---|
+| Which executives reported trades today? | `get_executive_trades()` | `.economic_trades()`; `.to_table()` for a ready Thai summary |
+| Did insiders of X buy or sell recently? | `get_executive_trades(symbol="X", date_type="transaction", start="YYYY-MM-DD", end="YYYY-MM-DD")` | `side` and `quantity` of each row in `.economic_trades()` |
+| What did the executive hold after the trade? | add `with_details=True`, or `get_executive_trade_report(row.batch_no)` | `row.detail.holding_before` / `holding_after` |
+| The exact average price | `with_details=True` | `row.detail.avg_price` (the listing's `price` is rounded to 2 dp) |
+| On-exchange or off? Who received a transfer? | `with_details=True` | `row.detail.market_source`, `row.detail.counterparty` |
+
+Dates here are **ISO `YYYY-MM-DD`** strings or `date` objects. This is unlike `get_sec_documents`,
+which takes dd/mm/yyyy. Keep windows to what the question needs: anything over 366 days is fetched
+in several requests, and `with_details=True` sends one request per report, at most 100.
+
+```python
+from settfex.services.sec import get_executive_trades
+
+result = await get_executive_trades(symbol="PANEL", date_type="transaction",
+                                    start="2026-09-01", end="2026-09-30")
+trades = result.economic_trades()             # copies and revoked/cancelled filings removed
+bought = sum(t.quantity for t in trades if t.side == "buy" and t.security_type == "หุ้นสามัญ")
+sold = sum(t.quantity for t in trades if t.side == "sell" and t.security_type == "หุ้นสามัญ")
+```
+
+Before you state a number from Form 59:
+- **Count only `economic_trades()`.**
+- **Never add quantities across security types**: shares, warrants and NVDRs are different
+  instruments. Filter on `security_type`.
+- **`transfer_in` / `transfer_out` are not market trades** (gifts to children, depositary moves).
+  Report them separately.
+- **Name the window and the date type** (received vs transaction), and say the count may include
+  the known same-reporter re-filing overcount.
+- **Read `holding_conflict is None` as "unknown"**, not as "no conflict".
+- **With `with_details=True`, check `result.detail_failures` is empty** before relying on
+  holdings. Rows of a failed report keep `detail=None`.
+
+As JSON (`result.model_dump(mode="json")`), the completeness fields travel with the rows:
+`reported_count`, `revoked_count`, `duplicate_count`, `unknown_labels`, `detail_unmatched` and
+`detail_failures`.
+
 ### ThaiBMA bonds — `from settfex.services.thaibma import ...`
 
 | I want… | Call |
@@ -226,9 +291,9 @@ being wrong, so none of them will announce itself.
 
 | Behaviour | What you must do |
 |---|---|
-| **Analyst consensus answers an uncovered symbol with HTTP 500, not 404** — and "uncovered" includes perfectly valid SET stocks (`ABICO`), DRs (`GOOG80`) and warrants (`JAS-W4`) | catch `FetchError`; report "no analyst coverage". **Do not** retry it as a typo or suggest a different symbol |
+| **Analyst consensus answers an uncovered symbol with HTTP 500, not 404** — and "uncovered" includes perfectly valid SET stocks (`ABICO`), DRs (`GOOG80`) and warrants (`JAS-W4`) | catch **`NotFoundError` first**: since 0.25.0 a symbol that is not listed on SET raises `SymbolNotFoundError` (with `.suggestion`). What still arrives as a plain `FetchError(500)` is a listed symbol with no coverage — report "no analyst coverage", and **do not** retry it as a typo |
 | **The DR-profile endpoint 404s for every non-DR symbol**, including `CPALL` | a 404 here means "not a DR", not "unknown symbol" |
-| **The consensus summary endpoint fails silently**: an unknown symbol is HTTP 200 with `overall: []` | check `.count`, or use `.get(symbol)` which returns `None` |
+| **The consensus summary cannot tell "unknown" from "uncovered" by itself**: both are HTTP 200 with `overall: []`. Since 0.26.0 an unlisted symbol raises `SymbolNotFoundError` | catch `NotFoundError` (do not retry); `count == 0` now means a listed symbol with no analyst coverage |
 | **The holiday endpoint returns HTTP 401 for any year but the current one** — and transiently on valid requests too | do not treat 401 as auth failure; there is no auth |
 
 ### Values that are placeholders, not data
@@ -273,10 +338,14 @@ Everything is importable from one place:
 
 ```python
 from settfex.exceptions import (
+    # --- the cross-cutting catch: a name that does not exist (0.25.0) ---
+    NotFoundError,           # base of SymbolNotFoundError AND CompanyNotFoundError; never retry
     # --- the FETCH family: `except FetchError` catches all of these ---
     FetchError,              # HTTP/transport failure; carries .status_code and .symbol
     HTTPStatusError,         # a non-2xx, with .url and .report_code as data
-    SymbolNotFoundError,     # HTTP 404 on a SET endpoint; may carry .suggestion
+    UnexpectedPageError,     # a PAGE where a document was expected (0.26.0); carries the answer
+    SoftNotFoundError,       # its "file not found" page — can be FALSE; NOT a NotFoundError
+    SymbolNotFoundError,     # SET 404, or an unlisted analyst-consensus symbol; .suggestion
     StaleDataError,          # ThaiBMA rolled back and you asked it to raise
     ParseError,              # a response arrived intact and could not be mapped
     IncompleteListingError,  # a ParseError: rows classified, then every one was lost
@@ -287,7 +356,10 @@ from settfex.exceptions import (
     InvalidLanguageError,    # unrecognized lang
     InvalidDateError,        # malformed date string — raised before any request
 )
-from settfex.utils.parsing import ResponseParseError   # also a ParseError since 0.24.0
+from settfex.utils.parsing import (
+    ResponseParseError,      # also a ParseError since 0.24.0
+    BlockedError,            # a WAF block page (0.25.0): stop, never retry; an UnexpectedPageError
+)
 ```
 
 **The split is the thing to internalise: a `FetchError` may be worth retrying; a `ValueError`
@@ -295,12 +367,44 @@ never is.** An input error means the request *succeeded* and your argument was w
 loop on one spins forever. `InvalidSymbolError`, `InvalidLanguageError` and `InvalidDateError` are
 raised before any network call at all.
 
-⚠️ Two "not found" taxonomies coexist today: a SET 404 is a `SymbolNotFoundError` (a `FetchError`),
-while the SEC equivalent is a `CompanyNotFoundError` (a `ValueError`). Catch both if you handle
-both hosts. Unifying them is tracked on #135.
+⚠️ Two "not found" taxonomies still coexist: a SET 404 is a `SymbolNotFoundError` (a
+`FetchError`), while the SEC equivalent is a `CompanyNotFoundError` (a `ValueError`). Since 0.25.0
+both are also a **`NotFoundError`** — catch that one, and catch it **before** `FetchError`, because
+a `SymbolNotFoundError` is a `FetchError` too and a retry handler would otherwise retry a typo
+forever:
+
+```python
+try:
+    data = await get_highlight_data(symbol)
+except NotFoundError:
+    ...          # the name does not exist: fix the input, never retry
+except FetchError:
+    ...          # upstream or transient: a retry may help
+```
+
+Neither class moved family; taking `SymbolNotFoundError` out of `FetchError` would break existing
+handlers, so that is a 1.0 decision, tracked on #135.
+
+⚠️ A **WAF block page** raises **`BlockedError`** (0.25.0) — **stop and back off; never retry**,
+because every further request deepens the block. It is a `ResponseParseError` subclass so older
+handlers still catch it, which also makes it a `ValueError`: catch `BlockedError` **before**
+`ValueError` if you treat `ValueError` as bad input. Only SEC's block page is recognised; a SET
+block may still arrive as a plain `ResponseParseError` — if one keeps repeating from one host,
+treat it the same way.
+
+**A download that answers with a page, not a file, says which page it was (0.26.0).** All three are
+`UnexpectedPageError`s and carry the answer — `.status_code`, `.headers` (credentials removed),
+`.body` (the first 8 KB), `.elapsed_seconds` — so you can decide from evidence, not from message
+text:
+
+| You caught | It means | Do |
+|---|---|---|
+| `BlockedError` | the WAF refused you | stop; back off for a long time; never retry soon |
+| `SoftNotFoundError` | the host's "file not found" page | probably gone — but it has been **wrong** (sixty in a row, each slow, for files that existed). If it was slow (`.elapsed_seconds`) or many arrive together, retry later before recording it as gone. `.matched_marker` says which rule matched |
+| `UnexpectedPageError` (itself) | any other page, e.g. an upstream error page | the source is degraded; try again later |
 
-⚠️ `ResponseParseError` is also what a **WAF block page** currently surfaces as — right family,
-wrong diagnosis. If you see it repeatedly from one host, **stop and back off**; do not retry.
+`download_all` keeps the kind on each failure: `FailedDownload.error_type` names the class and
+`.status_code` the status.
 
 ---
 

{settfex-0.24.2 → settfex-0.26.0}/CHANGELOG.md

@@ -7,6 +7,228 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-10-08
+
+**SEC Form 59 arrives: directors' and executives' trades, with the report behind each one.**
+- **Downloads:** a download that answers with a page instead of a file now says which page it
+  was and carries the answer.
+- **Analyst consensus:** the deprecation announced in 0.25.0 makes its change. An unlisted symbol
+  on the consensus summary raises.
+- **Fixed:** a Thai SEC date on a leap day is no longer lost.
+
+Nothing is removed from the public API. One behaviour change completes its warning period (see
+**Changed**).
+
+### Added
+
+- **SEC Form 59 (แบบ 59): directors' and executives' trades** (`settfex.services.sec`, top-level
+  `get_executive_trades` / `get_executive_trade_report`). Three tiers for the listing
+  (`get_executive_trades`, `fetch_executive_trades`, `fetch_executive_trades_raw`) and three for the
+  report behind each row (`get_executive_trade_report`, `fetch_executive_trade_report`, `…_raw`).
+  - **Who traded vs who filed:** `reporter_name` vs `executor_name`/`executor_id`, with `is_self`.
+  - **Duplicates are marked, not dropped** (`duplicate_of`, `duplicate_basis`). A row is a copy
+    when its report's holdings match another's, or when the same trader appears under a different
+    reporter with the same trade (`executor_own_row`: the trader filed the trade themselves, the
+    spouse case; `executor`: e.g. one company reported by two executives). Rows from the same
+    reporter are never merged that way, so a same-reporter re-filing is counted twice (documented).
+    `holding_conflict` (`bool | None`) flags a trader-rule merge whose holdings disagree; it is
+    `None` when a report was not fetched. All 28 September 2026 pairs are pinned.
+  - **Revoked filings are kept and marked** (`is_revoked`), never counted; a transaction the report
+    marks `CANCELED` is void too. `economic_trades()` drops copies and void rows.
+  - **No silent truncation:** the search page shows at most 100 rows, so the service reads the
+    site's "display all results" page, and every response's stated count must equal the rows parsed,
+    or `ParseError`. The URL builder refuses to build that page without dates: undated, it is the
+    whole database (70 MB).
+  - **Fail-loud cells:** an unknown layout, a bracketed amount or an unparseable number or date
+    raises. Real absences (`-` price, an empty date, the 19% of history without a link) come back as
+    `None`.
+  - **`with_details=True`** adds holdings before and after, the unrounded average price, the trading
+    channel and broker, the counterparty and `holding_consistent`. That is one request per distinct
+    report, at most 100 per call. A failed report is recorded on `detail_failures`; a block page
+    stops everything.
+  - **Output:** `to_table()` renders the agreed Thai summary; `to_dataframe()` needs the
+    `dataframe` extra.
+  - Docs: `docs/settfex/services/sec/executive_trades.md`.
+- **A download that answers with a page instead of a file says which page it was, and carries
+  the answer** (#135). Three `FetchError` subclasses, with the messages 0.25.0 raised as plain
+  `FetchError`s, so every existing `except` keeps catching:
+  - `UnexpectedPageError` — any HTML where a document was expected, including an HTML error page
+    under a non-200 status. The common base of the other two.
+  - `SoftNotFoundError` — the host's "file not found" page, with `.matched_marker`
+    (`"sec-thai"` / `"generic-not-found"`). **Deliberately not a `NotFoundError`**: it has been
+    wrong (below).
+  - `BlockedError` gains `UnexpectedPageError` as a second base (after its 0.25.0 ones), and the
+    SEC download path now recognises the block page under **any** status, not only 2xx. JSON
+    endpoints still report a non-2xx as `HTTPStatusError`.
+  Each carries `url`, `final_url`, `status_code`, `content_type`, `headers` (without
+  `Set-Cookie`, `Cookie`, `Authorization`, `Proxy-Authorization`), `body` — the first 8,192 bytes,
+  support ID screened, the block detector's own cap — with `body_truncated`, and
+  `elapsed_seconds`.
+- `DownloadedFile.elapsed_seconds` and `FailedDownload.status_code`.
+- `SOFT_404_MARKERS` and `SOFT_404_WINDOW_BYTES` in `settfex.services.sec.constants`: the
+  soft-404 rule, documented so a caller can reason about it.
+
+  **Why:** a downstream consumer saw four non-document HTML answers in a row (HTTP 200,
+  `text/html`) and could not tell a WAF block page — back off for days — from an upstream error
+  page — retry the next night: the body was discarded before raising. The same consumer saw sixty
+  consecutive soft-404s, each ~38 s instead of ~3 s, for files that all downloaded the next
+  evening; the rule matches the SEC's Thai text **or any "not found"** in the first 400 bytes.
+
+### Changed
+
+- **`get_consensus_overall()` / `fetch_overall()` raise `SymbolNotFoundError` for a symbol that is
+  not listed on SET.** Settrade answers that symbol, and a listed symbol with no analyst coverage,
+  with the same empty summary under HTTP 200; the SET stock list tells them apart.
+  - 0.25.0 warned (`DeprecationWarning`, registry id `consensus-overall-unknown-symbol`) and
+    returned the empty summary.
+  - The error carries `status_code=200`, the normalized `symbol` and a `suggestion`. It is a
+    `NotFoundError`, so catch `NotFoundError` and do not retry.
+  - `count == 0` now means a listed symbol without coverage.
+  - The whole-market call (`symbol=None`) is unchanged.
+- `FailedDownload.error_type` names the new subclass (`"SoftNotFoundError"`,
+  `"UnexpectedPageError"`, `"BlockedError"`) where it said `"FetchError"`. The message is
+  unchanged; a filter on the class-name **string** needs updating.
+
+### Removed
+
+- The deprecation registry entry `consensus-overall-unknown-symbol`, its change made (above). The
+  registry (`settfex.deprecations.DEPRECATIONS`) is empty.
+- The README's "Upgrading to 0.24" notice, kept for two minor releases as planned. The permanent
+  copy is the 0.24.0 **Data completeness advisory** below, still linked from the README.
+
+### Fixed
+
+- **A Thai SEC date on a leap day was lost** (`settfex.services.sec.utils.parse_dmy_date`). The
+  Buddhist-era conversion ran *after* the date was built in the B.E. year, and 543 is 3 mod 4, so
+  a B.E. year is a Gregorian leap year exactly when its C.E. year is not. `29/02/2567`, the real
+  2024-02-29 (a Thursday), was rejected as "day out of range" and came back `None`: a Thai SEC
+  listing row received or dated that day had `receive_date` / `as_of` silently empty. The
+  impossible `29/02/2568` was accepted in 2568 and then escaped as a bare `ValueError`. The year is
+  now converted first. Malformed or impossible input still returns `None`, as documented: nothing
+  that parsed before parses differently, except the leap days that used to be lost. The Form 59
+  listing alone carries 92 such rows (55 on 29/02/2567, 37 on 29/02/2559).
+
+### Known issues
+
+- **The SEC's Thai listing page prints a 29 February filing as 28 February** (upstream). A Thai
+  B.E. year is never a Gregorian leap year, and the page appears to clamp the day. 103 Thai MD&A
+  rows from 2024-02-29 carry 2024-02-28, and the FILEID shows the true date. settfex parses the
+  page faithfully. A cross-check is proposed in #153.
+- **Form 59: a trade one reporter filed twice is counted twice** by `economic_trades()`. Proposal:
+  #154.
+
+## [0.25.0] - 2026-09-23
+
+The seven items the 0.25.0 backlog on #135 held, plus two defects the 2026-09-23 checklist audit on
+#135 found on the way. Nothing is removed and no exception leaves its family; one behaviour starts
+its deprecation period (see **Deprecated**).
+
+### Added
+
+- **`NotFoundError`** (`settfex.exceptions`, also top-level): one catch for "that name does not
+  exist". `SymbolNotFoundError` (a `FetchError`) and `CompanyNotFoundError` (a `ValueError`) are
+  both `NotFoundError`s now, **without moving family** — every handler written before keeps
+  working. Catch it *before* `FetchError`: a retry handler written as `except FetchError` used to
+  retry a SET typo forever. Moving `SymbolNotFoundError` out of `FetchError` would break existing
+  handlers, so that stays a 1.0 decision (#135).
+- **`BlockedError`** (`settfex.utils.parsing`): a bot-protection block page is now named for what
+  it is. The fetcher recognises SEC's BIG-IP ASM page (`<title>Request Rejected</title>` plus
+  `Your support ID is:`) on the first 2xx that carries it and raises **without retrying** —
+  retrying deepens a block. It carries `url`, `status_code`, `content_type`, the headers minus
+  `Set-Cookie`, and the page itself with its support ID screened (kept out of `str(exc)`), so the
+  next real block yields the byte-exact fixture the synthetic test page stands in for. A
+  `ResponseParseError` subclass, so every handler that caught a block page before still does —
+  which also makes it a `ValueError`: **catch `BlockedError` before `ValueError`**. Only the SEC
+  page is recognised; no SET/Incapsula block page has ever been captured. Built from the recorded
+  markers with **zero live requests** (a single polite request cannot reproduce a block page, and
+  tripping the WAF on purpose would block the IP other workloads share).
+- **Batches stop at the first block.** `download_all`, ThaiBMA `fetch_curves` and ThaiBMA history
+  send nothing more once a request comes back blocked. Items not yet requested are recorded as
+  failures — `FailedDownload(error_type="BlockedError", error="not requested: …")`, or a year on
+  `missing_years` — so the return shape is unchanged.
+- **`setup_logger(filter=None)`**: passed to both sinks as loguru's own `filter`.
+  `filter="settfex"` gives settfex-only sinks, which is what an application that also logs through
+  loguru wants (#146 follow-up). The default stays unfiltered, as documented in 0.24.2.
+- **`settfex.deprecations`**: the registry every `DeprecationWarning` now goes through
+  (`DEPRECATIONS`, `warn_deprecated`). The L1 golden records it by content (format 2), and
+  `tests/test_deprecations.py` triggers every entry, bans any other `warnings.warn` in the
+  package, and fails once an entry's `changes_in` release arrives. The warning names the caller's
+  line, not settfex's.
+- **`.github/workflows/live-smoke.yml`** — a weekly run of the integration probes on a Thailand
+  self-hosted runner, **inert**: nothing runs until a runner labelled `thailand` is registered and
+  the repository variable `LIVE_SMOKE_ENABLED` is `true`. Its header states the two reasons it
+  ships switched off (the home egress IP is shared with production capture; the repository is
+  public). With it, `SETTFEX_LIVE_BUDGET=N` caps request attempts in any live run
+  (`tests/integration/conftest.py`).
+
+### Changed
+
+- **Analyst consensus tells an unknown symbol from an uncovered one.** Settrade answers both with
+  HTTP 500 on the table and an empty list on the summary. On a table 500 the SET stock list now
+  decides — the in-process one if `get_stock_list()` already ran, otherwise **one** load per event
+  loop (no index enrichment, no retries; a failed load answers "unknowable" and is not repeated) —
+  and a symbol that is **not listed** raises `SymbolNotFoundError(status_code=500)` with a real
+  `.suggestion`. A listed symbol with no coverage stays the plain `FetchError(500)` it always was,
+  and the whole-market summary is never classified. Additive under the deprecation policy's new
+  sentence: raising a strict subclass that keeps every documented attribute is not a change.
+- **The deprecation policy says how a deprecation is declared**, and its claim that the golden
+  records warnings is now true. Until 0.25.0 it asserted the golden pinned `DeprecationWarning`s;
+  the generator recorded none, and no warning existed yet to notice.
+- **README links work on PyPI.** 87 relative links (docs, examples, `AGENTS.md`, `CHANGELOG.md`)
+  are absolute `blob/main` / `tree/main` URLs; PyPI resolves nothing relative.
+  `tests/test_readme_links.py` now forbids relative links, checks every repo link's target exists,
+  and scopes its tag-pin rule to CHANGELOG anchors — docs links deliberately follow `main`.
+- **The live holiday probe makes one attempt.** `test_live_set_holidays` used a 7-attempt ladder
+  meant for the transient 401, which 0.24.1 stopped retrying; it only ever fired on 403/429, the
+  WAF signals the politeness rule says never to retry.
+- The fault-injection matrix gains a **raised transport error** (`FetchError` from a connection
+  reset, as the real fetcher raises once its retries are spent). Every earlier fault was a
+  *response*; all 33 entry points now also pass against a request that never completes.
+- `AsyncDataFetcher.fetch()` documents that a non-2xx status is **returned**, not raised.
+
+### Deprecated
+
+- **`get_consensus_overall()` / `fetch_overall()` for a symbol that is not listed on SET.** It
+  answers with an empty summary (`count == 0`) — the same answer as a listed symbol with no
+  coverage — and now emits a `DeprecationWarning` (registry id
+  `consensus-overall-unknown-symbol`). **In 0.26.0 it raises `SymbolNotFoundError`.** Wrap the
+  call in `except NotFoundError` to be ready. `fetch_overall_raw()` never warns.
+
+### Fixed
+
+- **A WAF block page was saved to disk as the requested filing.** The download guard rejected
+  HTML only when the response said it was HTML, and the observed BIG-IP page carries no
+  `Content-Type` — so `download()` returned its 242 bytes as a `DownloadedFile` and `download_all`
+  wrote them under the filing's filename. Found by the 2026-09-23 checklist audit on #135; closed
+  by `BlockedError`.
+- **A "display all results" (ViewMore) page could reduce a section's rows (U-7).** A successful page
+  replaced the inline rows with no comparison, so a short or placeholder-only page deleted rows
+  while `has_losses` stayed `False`; and a page that failed to *map* raised out of the loop, so the
+  whole report code landed on `failed_codes` and every sibling category lost its rows. Both now
+  degrade like an unusable page: inline rows kept, a `DegradedSection` recorded, the inline
+  page's reported count left for `completeness()`. The rule is a count, not file identity. A
+  single-code listing that used to raise `ParseError` here now returns with `has_losses` — the
+  behaviour the 0.22.x notes already described.
+
+### Dependencies
+
+- **pandas 3.0.5 → 3.0.6** (dev group; `dataframe` / `examples` extras keep their `>=2.0.0` floor,
+  so installs were never held back). Lock-only: the pandas entry alone moved — +16 wheels are
+  upstream's new `cp315`/`cp315t` builds — and upstream's 8 regression fixes and 2 bug fixes touch
+  no API settfex calls. Merged as #145 on 2026-09-23.
+
+### Migration to 0.25
+
+- **Catch `NotFoundError` before `FetchError`** wherever you retry on `FetchError`.
+- **Catch `BlockedError` before `ValueError`** if you treat `ValueError` as bad input — and never
+  retry it.
+- A test that pins `type(e) is FetchError` for an analyst-consensus 500 still passes for a listed
+  symbol; for an unlisted one the type is now `SymbolNotFoundError` (`isinstance(e, FetchError)`
+  still holds).
+- If your application logs through loguru, prefer `setup_logger(filter="settfex")` — or no
+  `setup_logger` at all and `logger.enable("settfex")` after `import settfex`.
+- Before 0.26.0: stop relying on `get_consensus_overall(unknown)` returning an empty summary.
+
 ## [0.24.2] - 2026-09-22
 
 ### Fixed