xippios-usda-esmis 0.1.0__tar.gz

xippios_usda_esmis-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# environments and caches
+.venv/
+__pycache__/
+*.py[cod]
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+
+# build artefacts
+dist/
+build/
+*.egg-info/
+
+# local secrets are never files, but belt and braces
+.env
+.env.*
+.envrc
+.envrc.*
+
+# editors
+.idea/
+.vscode/

xippios_usda_esmis-0.1.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/) (pre-1.0: breaking changes bump the minor).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-27
+
+### Added
+
+- Scaffold from [sdk-template](https://github.com/xippios/sdk-template): configured
+  client for USDA ESMIS, MCP server and FastAPI router wired to the task layer, test
+  harness with core's family check, CI, the nightly live tests and the release train,
+  in which a release PR's merge tags and publishes.
+- Upstream documentation snapshot in `docs/upstream/`, fetched 2026-10-27, and its
+  capture script `scripts/refresh_upstream.py`: the ESMIS OpenAPI document verbatim,
+  the WASDE publication page and its newest release's page as Markdown, and an excerpt
+  of the release calendar, with `FETCHED.md` recording every fetch.
+- README and CLAUDE.md name ESMIS in full; the README lists where the live API deviates
+  from its OpenAPI document, as probed on 2026-10-27.
+- Attribution: the README and `docs/upstream/FETCHED.md` state that the ESMIS
+  documentation and release files are works of the United States Government, in the
+  public domain in the United States (17 U.S.C. § 105), and cite USDA's policy page.
+- Endpoint wrappers for the twelve operations of the ESMIS catalog (agencies,
+  publications, releases) under `xippios.usda.esmis.api`, the models `Agency`, `Pager`,
+  `Publication`, `Release`, `PublicationResults` and `ReleaseResults` typed as the wire
+  sends them, with the `StrEnum`s `Status`, `Subscribable` and `ResourceType` that a walk
+  of every publication page confirmed, and the client's `classify`: an unknown id, which
+  the four lookups by id answer with HTTP 404, is `NotFoundError`, and an identifier
+  carrying `/`, which ESMIS refuses, `InvalidRequestError`; the lookups by acronym or
+  identifier answer an unknown one with an empty HTTP 200, returned as such. Recorded
+  fixtures and replay tests in `tests/test_api.py`; CLAUDE.md gains the ESMIS specifics.
+- Seven catalog tasks, each an MCP tool and an HTTP route: `list_agencies`,
+  `search_publications` and `get_publication`, `list_releases` (newest first, with
+  `since`, `until` and `page`), `get_release`, `get_latest_release` and
+  `list_release_files` (each file's URL, name and format, the model `ReleaseFile`).
+  `meta.endpoint` names the operationId, `meta.total` upstream's count for the paged
+  lists, `meta.vintage` the release id; `meta.published_at` of a task about one release
+  is its `release_datetime` as printed, the `+0000` dropped, with `published_at_naive`
+  set (ADR-0022). An unknown identifier raises `NotFoundError` where one record is asked
+  for and gives the empty list from `list_releases`.
+- `download_release_file(release_id, format, dest)`, a bulk task in `BULK_TASKS`,
+  Python only: it streams one file of a release to the path the caller names with
+  core's `download`, nothing cached, `meta.endpoint` the file's name as upstream prints
+  it (`wasde1026.txt`), `meta.published_at` the release's printed time with the flag.
+  Replay tests for every task, the tools called end to end, the October 2026 WASDE
+  `.txt` recorded whole for the download's replay, and live tests for every task and
+  for the release order the release tasks rely on.
+- Two packaged reference tables, written by `scripts/refresh_reference.py` with core's
+  `PackagedList.write` on 2026-10-27: `reference/publication.json`, the 2522
+  publications of every page of `/publication/findAll`, each the eight columns of the
+  new projection `PublicationRow`, and `reference/agency.json`, the 9 agencies with every
+  field.
+- `list_publications(search=None, agency_acronym=None)`, an MCP tool and an HTTP route
+  answered from the packaged publication table without a request: `search` matches the
+  id, an identifier or the title (core's `matches`), `agency_acronym` an acronym the row
+  lists, and an acronym the packaged agency table lacks is refused with core's
+  `UnknownCode`, naming the closest. `meta.retrieved_at` is the table's fetch time and
+  `meta.endpoint` `esmis_api_publication_findAll` (ADR-0022). Its MCP tool keeps the
+  default cap, 200 rows or 64 KB, with a note naming the two filters, since the whole
+  table is 599,402 bytes; Python and HTTP callers get the whole table (ADR-0016). Live
+  tests compare the packaged agencies and the publication count with upstream.
+
+### Changed
+
+- `xippios-core` 0.3.0 from PyPI (`core_version` 0.3.0, `~=0.3.0`; template v0.2.2),
+  which brings the api.data.gov gateway module (C14, unused by this keyless source),
+  `AsyncClient.download` for bulk files (C15, ADR-0019) and ADR-0022's
+  `ResultMeta.published_at_naive`, which the release tasks need.
+- `scripts/refresh_reference.py` refreshes the two packaged tables through `api/` (102
+  requests: the agencies and the 101 publication pages, bounded by `total_pages`) and
+  rewrites the provenance rows of `reference/README.md`; it generates no `enums.py`, and
+  `params.PACKAGED_LISTS` is empty, since the tables are `PackagedList` files that
+  `tasks.py` reads directly.

xippios_usda_esmis-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

xippios_usda_esmis-0.1.0/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.5
+Name: xippios-usda-esmis
+Version: 0.1.0
+Summary: Typed client, MCP tools and HTTP routes for USDA ESMIS
+Project-URL: Homepage, https://github.com/xippios/sdk-usda-esmis
+Project-URL: Upstream, https://esmis.nal.usda.gov
+Project-URL: Changelog, https://github.com/xippios/sdk-usda-esmis/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/xippios/sdk-usda-esmis/issues
+Author: XIPPIOS GmbH
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agriculture,httpx,mcp,pydantic,sdk,usda-esmis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: xippios-core~=0.3.0
+Provides-Extra: http
+Requires-Dist: xippios-core[http]~=0.3.0; extra == 'http'
+Provides-Extra: mcp
+Requires-Dist: xippios-core[mcp]~=0.3.0; extra == 'mcp'
+Provides-Extra: testing
+Requires-Dist: xippios-core[testing]~=0.3.0; extra == 'testing'
+Description-Content-Type: text/markdown
+
+# xippios-usda-esmis
+
+Typed Python client, MCP server and FastAPI routes for
+[USDA ESMIS](https://esmis.nal.usda.gov), the Economics, Statistics, and Market
+Information System of USDA's National Agricultural Library, part of the
+[xippios SDK family](https://github.com/xippios). Names and semantics follow the
+upstream documentation; every response carries release metadata (source, endpoint,
+retrieved_at, published_at, vintage).
+
+## Install
+
+```bash
+uv add xippios-usda-esmis            # client only
+uv add "xippios-usda-esmis[mcp]"     # + MCP server
+uv add "xippios-usda-esmis[http]"    # + FastAPI router
+```
+
+No API key is needed.
+
+## 30-second example
+
+```python
+from pathlib import Path
+
+from xippios.usda.esmis import download_release_file, get_latest_release, list_release_files
+
+latest = get_latest_release("wasde")  # the newest WASDE release
+latest.data.id, latest.data.release_datetime  # "796099", 2026-10-09 12:00:00+00:00, as printed
+latest.meta.vintage  # "796099": the release id
+latest.meta.published_at  # 2026-10-09 12:00:00, the printed time without its +0000
+latest.meta.published_at_naive  # True: upstream's text, no zone attached (ADR-0022)
+
+files = list_release_files(int(latest.data.id))
+[file.format for file in files.data]  # ["pdf", "txt", "xls", "xml"]
+
+# Python only, no MCP tool: streams the TXT to the path you name; nothing is cached
+txt = download_release_file(796099, "txt", Path("wasde1026.txt"))
+txt.data.path, txt.data.bytes, txt.data.content_type  # wasde1026.txt, 122378, "text/plain"
+txt.meta.endpoint  # "wasde1026.txt": the file's name as upstream prints it
+```
+
+`search_publications("wasde")` finds a publication's identifiers, and
+`list_releases("wasde", since=date(2026, 1, 1))` its releases since a date, newest first.
+
+`list_publications()` answers from the table of 2522 publications packaged with this
+version, fetched on 2026-10-27, without a request:
+
+```python
+from xippios.usda.esmis import list_publications
+
+wheat = list_publications(search="wheat")  # id, identifier or title contains "wheat": 30
+ers = list_publications(agency_acronym="ERS")  # as list_agencies() spells it: 121
+ers.meta.retrieved_at  # 2026-10-27 17:24:48+00:00, when the table was fetched
+ers.meta.endpoint  # "esmis_api_publication_findAll", the operation it came from
+```
+
+An acronym the packaged agency table lacks raises `UnknownCode`, an
+`InvalidRequestError` naming the closest (`"ers"`: did you mean `ERS`?).
+
+## MCP
+
+```json
+{
+  "mcpServers": {
+    "usda-esmis": {
+      "command": "uvx",
+      "args": ["--from", "xippios-usda-esmis[mcp]", "xippios-usda-esmis-mcp"]
+    }
+  }
+}
+```
+
+Tools are read-only and named `usda_esmis_<verb>_<noun>`. Results are capped, at
+200 rows or 64 KB unless a tool has a cap of its own, with a note on how to see the rest;
+`usda_esmis_list_publications` keeps the default and says how to filter: unfiltered, its
+packaged table is about 600 KB, so the tool returns its first 200 rows, while
+`list_publications()` in Python and its HTTP route return the whole table.
+`download_release_file` is no tool and no route: a bulk task, Python only (ADR-0019).
+`--http` serves streamable HTTP instead of stdio.
+
+## Status
+
+<!-- Core's family check (tests/test_family.py) reads this table: keep the "## Status"
+heading and the "Task function" column. Each row's Task function cell starts with the
+task's name in backticks, alone or as its call (`get_data(code, year)`); several tasks in
+one row are backticked names separated by commas; prose may follow. The tables list
+exactly tasks.__all__ and tasks_write.__all__. -->
+
+| Upstream operation | Task function | MCP tool | Status |
+| --- | --- | --- | --- |
+| `esmis_api_agency_findAll` | `list_agencies()` | `usda_esmis_list_agencies` | alpha |
+| `esmis_api_publication_findAll`, every page, packaged (fetched 2026-10-27; no request) | `list_publications(search=None, agency_acronym=None)` | `usda_esmis_list_publications` | alpha |
+| `esmis_api_publication_search`, every page unless `page` is given | `search_publications(query, page=None)` | `usda_esmis_search_publications` | alpha |
+| `esmis_api_publication_findByIdentifier` | `get_publication(publication_identifier)` | `usda_esmis_get_publication` | alpha |
+| `esmis_api_release_findByIdentifier`, pages walked newest first unless `page` is given | `list_releases(publication_identifier, since=None, until=None, page=None)` | `usda_esmis_list_releases` | alpha |
+| `esmis_api_release_findById` | `get_release(release_id)` | `usda_esmis_get_release` | alpha |
+| `esmis_api_release_findByIdentifier`, page 0 | `get_latest_release(publication_identifier)` | `usda_esmis_get_latest_release` | alpha |
+| `esmis_api_release_findById` | `list_release_files(release_id)` | `usda_esmis_list_release_files` | alpha |
+| `esmis_api_release_findById`, then the file | `download_release_file(release_id, format, dest)`, a bulk task | none, Python only | alpha |
+
+## Where the live API deviates from its OpenAPI document (probed 2026-10-27)
+
+The OpenAPI document in `docs/upstream/openapi/esmis_public_api.yaml` is the reference
+for names and parameters; the live API answers differently in these points:
+
+- every `id` is a JSON string, not an integer; the walk of every `/publication/findAll`
+  page on 2026-10-27 (pages 0 to 100) found 2522 publications with distinct ids, each a
+  string of digits;
+- `Publication.agency`, `.identifier` and `.agency_acronym` are arrays, not strings;
+- `agency_acronym` is absent on the publications the four other publication operations
+  answer, which carry `publication_agency_export_1` instead; `/publication/findAll`
+  carried `agency_acronym` on all 2522 publications of the walk and
+  `publication_agency_export_1` on none;
+- `Publication.frequency` printed `""` on one publication of the walk (1172), a value
+  the document's enumeration does not list; `status`, `subscribable` and
+  `resource_type` held only the document's values;
+- the list wrapper has `filters`, `sorters` and `system` (`{"page_key": "page"}`)
+  beside `pager` and `results`;
+- `/publication/search` without `query`, or with an empty one, answers 200 with
+  `"pager": []` and empty results, although the document makes `query` required;
+- absence answers differ per lookup, as recorded: an unknown id answers 404
+  `{"message": ""}` at `/agency/findById`, `/publication/findById`, `/release/findById`
+  and `/release/findByPubId`; an unknown name answers 200 with nothing,
+  `/agency/findByAcronym` an empty array, `/publication/findByAgency`,
+  `/publication/findByIdentifier` and `/release/findByIdentifier` empty results with
+  every pager count 0;
+- an identifier carrying `/` (`Market and Trade Economics Division/FDS`) cannot be
+  looked up: the web server answers `%2F` in a path with its own HTML 404, and a raw
+  slash is no route; every publication recorded with such an identifier has another
+  without it (`FDS`);
+- `page` is 0-based and a page holds 25 items, as the YAML's defaults say; undocumented
+  are that the page size is fixed and that a page past the last answers empty results
+  with `current_page` clamped;
+- the orders are undocumented: `/release/findAll` comes highest id first, the newest
+  created, with `release_datetime` only mostly in that order (page 0 runs 2026-10-26,
+  2026-10-09, 2026-10-23); a publication's releases (`/release/findByIdentifier`) come
+  latest `release_datetime` first, as recorded on WASDE's pages 0 and 1 (50 releases,
+  2026-10-09 back to 2022-08-12), while their ids do not follow the dates (96169, 96170
+  and 96171 are August, July and June 2025); publication lists follow no id order
+  (`/publication/findAll` page 0: ids 2425, 1801, 1861, 1922;
+  `/publication/search?query=wasde`: 1762, 1831, 1154);
+- `release_datetime` is `YYYY-MM-DDTHH:MM:SS+0000` (a zone, no colon);
+- `Release.files` paths take two shapes: recent releases use
+  `/sites/default/release-files/{release id}/{name}.{ext}`
+  (`/sites/default/release-files/796099/wasde1026.txt`), older ones the hashed
+  three-segment path the YAML's example shows
+  (`/sites/default/release-files/8336h188j/2514qk05k/j0991c960/prog3925.pdf`);
+- `Publication.upcoming_releases` is `[]` on most publications: the walk found items on
+  24 of 2522, 67 in all, each printed with an Eastern offset
+  (`2026-10-28T15:00:00-0400` and `2026-11-04T15:00:00-0500` for publication 1863),
+  where `release_datetime` prints `+0000`; the YAML lists no release-calendar operation;
+- the zone label of release times: the API prints `release_datetime` with `+0000` and
+  the release page its `datetime` with `Z` (`2026-10-09T12:00:00+0000` and
+  `datetime="2026-10-09T12:00:00Z"` for the October 2026 WASDE), while the release
+  calendar, whose settings say `timeZone: "America/New_York"`, puts the WASDE releases
+  that `/release/findByIdentifier/wasde` (page 0) prints as `2025-09-12T12:00:00+0000`
+  and `2025-12-09T12:00:00+0000` at `2025-09-12T12:00:00-04:00` and
+  `2025-12-09T12:00:00-05:00`, and the October release's own file answers
+  `HEAD /sites/default/release-files/796099/wasde1026.txt` with
+  `Last-Modified: Fri, 09 Oct 2026 16:01:00 GMT`, 12:01 Eastern. The `+0000`/`Z` label
+  is contradicted by upstream's own calendar and file timestamps, which fit a noon
+  Eastern wall-clock time (the recorded download of `wasde1026.txt` answers the same
+  `Last-Modified`); the tasks keep `release_datetime` as printed, and those about one
+  release put its wall-clock time, the `+0000` dropped, into `meta.published_at` with
+  `published_at_naive` set (ADR-0022; CLAUDE.md, release times);
+- the release calendar page (`docs/upstream/pages/release-calendar.md`) held 3776
+  events, drawn from a `publication_upcoming_releases` field (each event's
+  `startField`), while the API's `Publication.upcoming_releases` lists 67 upcoming
+  releases on 24 publications; every calendar event is classed `fc-event-past`, future
+  ones included, and WASDE's events stop at 2025-12-09.
+
+## Upstream terms and attribution
+
+Data comes from USDA ESMIS (https://esmis.nal.usda.gov) under its own terms of use;
+this package adds no rights to it. The documentation and the release files are works of
+the United States Government (USDA National Agricultural Library, ESMIS), in the public
+domain in the United States (17 U.S.C. § 105); a suggested credit line is "Source:
+USDA National Agricultural Library, ESMIS". The pages the snapshot reads print no
+copyright line, and USDA's policy page is cited in `docs/upstream/FETCHED.md`,
+Attribution. Documentation snapshot: `docs/upstream/`.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).