zeitreiher-models 0.1.0__tar.gz

zeitreiher_models-0.1.0/.gitattributes

@@ -0,0 +1,9 @@
+* text=auto eol=lf
+*.go	text eol=lf
+*.py	text eol=lf
+*.json	text eol=lf
+*.ndjson	text eol=lf
+*.proto	text eol=lf
+*.md	text eol=lf
+*.yml	text eol=lf
+testdata/streams/invalid/crlf.ndjson -text

zeitreiher_models-0.1.0/.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: "gomod"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

zeitreiher_models-0.1.0/.github/workflows/dependabot_automerge.yml

@@ -0,0 +1,18 @@
+name: Dependabot auto-approve / -merge
+on: pull_request
+
+jobs:
+  dependabot:
+    permissions:
+      contents: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    env:
+      PR_URL: ${{github.event.pull_request.html_url}}
+      GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+    if: ${{ github.actor == 'dependabot[bot]' }}
+    steps:
+      - name: Approve a PR
+        run: gh pr review --approve "$PR_URL"
+      - name: Enable auto-merge for Dependabot PRs
+        run: gh pr merge --auto --squash "$PR_URL"

zeitreiher_models-0.1.0/.github/workflows/go-lint.yml

@@ -0,0 +1,28 @@
+name: "Go Lint"
+
+on:
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  golangci:
+    runs-on: ubuntu-latest
+    name: lint
+    env:
+      # Build/run the linter with the toolchain the module targets (go 1.27.0).
+      GOTOOLCHAIN: go1.27.0
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.27.x"
+      - uses: actions/checkout@v7
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.15.0
+          args: --enable dupl,gocyclo
+      - name: fmt
+        run: golangci-lint fmt --diff --enable gofmt

zeitreiher_models-0.1.0/.github/workflows/go-test.yml

@@ -0,0 +1,26 @@
+name: "Go Tests"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Install Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.27.x"
+      - name: Checkout code
+        uses: actions/checkout@v7
+      - name: Vet
+        run: go vet ./...
+      - name: Test
+        run: go test -race -covermode=atomic -coverprofile=coverage.out ./...
+      - name: Coverage
+        run: go tool cover -func=coverage.out | tail -1

zeitreiher_models-0.1.0/.github/workflows/packaging-test.yml

@@ -0,0 +1,20 @@
+name: "Packaging Test"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  check_packaging:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Build distributions
+        run: uv build
+      - name: Check distributions
+        run: uv publish --dry-run

zeitreiher_models-0.1.0/.github/workflows/proto.yml

@@ -0,0 +1,27 @@
+name: "Proto"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+permissions:
+  contents: read
+
+jobs:
+  buf:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install Go
+        uses: actions/setup-go@v7
+        with:
+          go-version: "1.27.x"
+      - name: Install buf
+        run: go install github.com/bufbuild/buf/cmd/buf@v1.75.0
+      - name: buf build
+        run: buf build
+      - name: buf lint
+        run: buf lint
+      - name: buf format
+        run: buf format --diff --exit-code

zeitreiher_models-0.1.0/.github/workflows/python-coverage.yml

@@ -0,0 +1,23 @@
+name: "Python Coverage"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Install dependencies
+        run: uv sync --group coverage
+      - name: Run Tests and Record Coverage
+        run: |
+          uv run coverage run -m pytest unittests
+          uv run coverage html --omit 'unittests/*,.venv/*'
+          uv run coverage report --fail-under 80 --omit 'unittests/*,.venv/*'

zeitreiher_models-0.1.0/.github/workflows/python-formatting.yml

@@ -0,0 +1,28 @@
+name: "Python Formatting"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  format:
+    name: "format (${{ matrix.tool }})"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - tool: ruff-format
+            command: "ruff format --check ."
+          - tool: ruff-isort
+            command: "ruff check --select I ."
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Install dependencies
+        run: uv sync --group linting
+      - name: ${{ matrix.tool }}
+        run: uv run ${{ matrix.command }}

zeitreiher_models-0.1.0/.github/workflows/python-lint.yml

@@ -0,0 +1,35 @@
+name: "Python Lint"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  pylint:
+    name: "Python Code Quality and Lint (${{ matrix.linter-env }})"
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        include:
+          - linter-env: linting
+            commands: |
+              uv run ruff check src/zeitreiher_models unittests
+          - linter-env: type_check
+            commands: |
+              uv run mypy --show-error-codes src/zeitreiher_models --strict
+              uv run mypy --show-error-codes unittests --strict
+          - linter-env: spell_check
+            commands: |
+              uv run codespell --ignore-words=domain-specific-terms.txt src
+              uv run codespell --ignore-words=domain-specific-terms.txt README.md
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Install Dependencies
+        run: uv sync --group ${{ matrix.linter-env }}
+      - name: Run ${{ matrix.linter-env }}
+        run: ${{ matrix.commands }}

zeitreiher_models-0.1.0/.github/workflows/python-publish.yml

@@ -0,0 +1,52 @@
+name: "Publish to PyPI"
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  tests:
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Install dependencies
+        run: uv sync --group tests --group linting --group coverage --group type_check
+      - name: Run tests
+        run: uv run pytest unittests
+      - name: Run linting
+        run: |
+          uv run ruff check src/zeitreiher_models unittests
+      - name: Run type_check
+        run: |
+          uv run mypy --show-error-codes src/zeitreiher_models --strict
+          uv run mypy --show-error-codes unittests --strict
+      - name: Run coverage
+        run: |
+          uv run coverage run -m pytest unittests
+          uv run coverage report --fail-under 80 --omit 'unittests/*,.venv/*'
+
+  build-n-publish:
+    name: Build and publish Python distributions to PyPI
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    needs: tests
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs derives the package version from the git tag
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: "3.15"
+      - name: Build wheel and source distributions
+        run: uv build
+      - name: Publish distribution to PyPI
+        if: startsWith(github.ref, 'refs/tags/v')
+        uses: pypa/gh-action-pypi-publish@release/v1

zeitreiher_models-0.1.0/.github/workflows/python-test.yml

@@ -0,0 +1,24 @@
+name: "Python Tests"
+
+on:
+  push:
+    branches: [main]
+  pull_request: {}
+
+jobs:
+  pytest:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14", "3.15"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install Dependencies
+        run: uv sync --group tests
+      - name: Run the Unit Tests
+        run: uv run pytest unittests

zeitreiher_models-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Go
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+*.test
+*.out
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.tox/
+.mypy_cache/
+htmlcov/
+.coverage
+src/_zeitreiher_models_version.py
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Env
+.env
+.venv/
+coverage.out

zeitreiher_models-0.1.0/LICENSE

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

zeitreiher_models-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.5
+Name: zeitreiher-models
+Version: 0.1.0
+Summary: Hand-written public data models of the Zeitreiher API (SAP IS-U EDM profile values)
+Project-URL: Changelog, https://github.com/Hochfrequenz/zeitreiher-models/releases
+Project-URL: Homepage, https://github.com/Hochfrequenz/zeitreiher-models
+Author-email: Hochfrequenz Unternehmensberatung GmbH <info+github@hochfrequenz.de>
+License: MIT
+License-File: LICENSE
+Keywords: edm,is-u,lastgang,sap,time series,zeitreiher
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.11
+Description-Content-Type: text/markdown
+
+# zeitreiher-models
+
+![Go Tests](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Go%20Tests/badge.svg)
+![Go Lint](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Go%20Lint/badge.svg)
+[![Go Reference](https://pkg.go.dev/badge/github.com/hochfrequenz/zeitreiher-models.svg)](https://pkg.go.dev/github.com/hochfrequenz/zeitreiher-models)
+![Python Tests](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Python%20Tests/badge.svg)
+![Python Coverage](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Python%20Coverage/badge.svg)
+![Python Lint](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Python%20Lint/badge.svg)
+![Python Formatting](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Python%20Formatting/badge.svg)
+![Proto](https://github.com/Hochfrequenz/zeitreiher-models/workflows/Proto/badge.svg)
+
+Public data models of the **Zeitreiher API, version 1**: a read-only API over SAP IS-U EDM profile
+values (Lastgänge) — profile metadata plus many `[from, to)` intervals with values.
+
+This repository holds
+
+- **Go** structs (package `zeitreihermodels`, module `github.com/hochfrequenz/zeitreiher-models`),
+- **Python** frozen pydantic v2 models (package `zeitreiher_models`),
+- the shared **fixtures** in [`testdata/`](testdata) that define the JSON contract, and
+- the **gRPC contract** in [`proto/zeitreiher/v1`](proto/zeitreiher/v1).
+
+Everything is **written by hand**. No code is generated and no generated code is committed: every
+type, validator and (un)marshaller is ordinary, readable code. Both languages parse every valid
+fixture, write it back and compare the result with the fixture, and reject every invalid fixture —
+so Go and Python agree on the contract by construction.
+
+## The contract in short
+
+| Topic | Rule |
+|---|---|
+| Intervals | Half-open everywhere: `[from, to)`; `from` must be before `to`. |
+| Request timestamps | RFC 3339, whole seconds, **explicit offset** (`Z` or `±hh:mm`), ASCII digits only, hours 00–23. The instant must lie in the years 1900–9999 **in UTC**, so that it can be echoed in a response (`1900-01-01T00:00:00+01:00` is 1899 in UTC and rejected). Kept as sent (`+02:00` stays `+02:00`). A missing offset (`2026-01-01T00:00:00`) and the "unknown offset" `-00:00` are rejected. |
+| Response timestamps | RFC 3339, whole seconds, always UTC (`Z`). Instants built in code must survive the round trip (no offsets with seconds, years 1900–9999). |
+| Values | Already-scaled decimal **strings** in their **shortest canonical form** (`"160"`, `"0.022"`, `"25.25"`, `"-3.5"`), never JSON numbers. No exponent, no plus sign, no leading zeros, no trailing zeros after the decimal point (`"160.0"` is rejected: after parsing it equals `"160"`), no negative zero. |
+| Profile numbers | In requests 1–18 digits, leading zeros allowed, not all zeros; in responses without leading zeros. |
+| Units | `unit` is a **canonical unit code**: a UN/ECE Recommendation 20 code such as `KWH`, `MWH` or `KVR` (2 or 3 upper-case ASCII letters or digits, strict). Requests send canonical codes; the server maps them to the customer's SAP unit (an unknown code is a 400). In series records `unit` is always present and `null` when the SAP unit has no mapping; the series is delivered anyway. `unit_raw` (series records) is the SAP unit key (T006 `MSEHI`) as SAP delivers it, mapped or not, read leniently: any non-empty text of at most 30 characters (code points) without control characters (Unicode `Cc`). |
+| Series role | Every `series` record carries `role`, the role of its profile assignment (SAP `EPROFASS` role, e.g. `"0001"`; any non-empty text), or `null` when the series was not resolved through a role (e.g. `by: profile`). For `by: malo` the roles to deliver are configurable (default: all). |
+| Selectors | `{"by":"profile","profile":"…"}`, `{"by":"malo","malo":"<11 digits>"}`, or a customer resolver `{"by":"<snake_case name>","params":{"<key>":"<string>"}}`. |
+| Version selector | Exactly one of `{"current":{}}` (default) or `{"number":N}`; no `null` members. v1 has no as-of selector: `{"as_of":…}` is rejected. `{"number":N}` returns the current values overlaid with the stored values of versions ≥ N (the lowest wins), only inside N's covered range (gaps outside). Each value record says its source: `"version":<n>` for a stored version row, `"version":null` for a current value. |
+| Intervals (`interval`) | Sub-daily ISO 8601 durations in minutes: `PT15M`, `PT60M`, … Hours are written in minutes: `PT60M`, never `PT1H` (rejected, so that every interval has one spelling). |
+| Text | Every string is valid Unicode and is written unchanged. Parsers reject invalid UTF-8 and unpaired `\uD800`–`\uDFFF` escapes. Go refuses to marshal a string that is not valid UTF-8 (instead of writing U+FFFD); Python rejects a string with a lone surrogate when the model is built (`ValidationError`). |
+| Unknown keys | Requests **reject** them (a typo fails loudly). Responses **ignore** them (additive server changes do not break older clients). |
+| Duplicate keys | Not rejected: when an object repeats a key, the **last** occurrence wins and earlier ones are ignored without validation (`{"unit":"K H","unit":"MWH"}` is read as `"MWH"`), in both languages and on both sides. Producers must not write duplicate keys; the models never do. Pinned by the `*duplicate_key_last_wins*` fixtures. |
+| `null` | Request fields that are optional may be omitted or `null`. In responses, `series.role`, `series.unit`, `value.version`, `end.next`, `version.to` and `version.created_at` are always present and may be `null`; other optional response fields are omitted when unset. |
+| Error codes | Request-level codes in the error envelope `{"error":{"code","message","request_id"?}}` — btpingo's vocabulary (`invalid_request`, `unauthorized`, `forbidden`, `not_found`, `method_not_allowed`, `request_too_large`, `upstream_unreachable`, `internal`), shared by the Hochfrequenz BTP services, plus `cursor_invalid`, `cursor_mismatch`, `cursor_expired`, `cursor_stale` and `upstream_timeout`; record-level codes in `error` records and resolve/versions results. The known codes are listed in [`testdata/error_codes.json`](testdata/error_codes.json). **Strict on write, lenient on read:** parsers accept unknown snake_case codes so that a newer server does not break older clients (Go `IsKnown()`, Python `RecordErrorCode | str`); writers refuse every code outside the public list (Go `MarshalJSON` returns an error, Python JSON serialization raises `PydanticSerializationError`; `model_dump()` to a dict keeps them). |
+| NDJSON | One record per line, lines end with `\n` (the last one optionally), no `\r`, no blank lines. A response that does not end with exactly one `end` record was cut off and **must be treated as a failure**. The `end` record's `series`, `values` and `errors` count the records **on this page** only; a series record re-sent at the start of a continuation page counts again. |
+
+The full design lives in the `zeitreiher-go` repository (`docs/superpowers/specs/2026-10-27-zeitreiher-design.md`).
+
+## Go
+
+```bash
+go get github.com/hochfrequenz/zeitreiher-models
+```
+
+```go
+import zrm "github.com/hochfrequenz/zeitreiher-models"
+
+cet := time.FixedZone("CET", 3600)
+req := zrm.QueryRequest{
+	Select:   []zrm.Selector{zrm.MaLoSelector("87253749908"), zrm.ProfileSelector("50000000000056")},
+	From:     time.Date(2026, 1, 1, 0, 0, 0, 0, cet),
+	To:       time.Date(2026, 2, 1, 0, 0, 0, 0, cet),
+	Interval: "PT60M",
+}
+body, err := json.Marshal(req) // validates; an invalid request does not marshal
+
+records, err := zrm.ReadStream(resp.Body) // errors.Is(err, zrm.ErrMissingEnd) for a cut-off stream
+for _, rec := range records {
+	switch r := rec.(type) {
+	case *zrm.SeriesRecord:
+	case *zrm.ValueRecord: // r.Value is a zrm.Decimal (string)
+	case *zrm.ErrorRecord: // r.Code.IsKnown()
+	case *zrm.EndRecord: // r.Next != nil → request the next page with Cursor = *r.Next
+	}
+}
+```
+
+`ReadRecords(io.Reader)` yields records one by one (`iter.Seq2[Record, error]`) for streaming;
+`WriteRecord` writes one NDJSON line. Every type validates itself in `UnmarshalJSON` and refuses
+to marshal when it is invalid.
+
+## Python
+
+```bash
+pip install zeitreiher-models  # once published to PyPI
+```
+
+```python
+from datetime import datetime, timedelta, timezone
+
+from zeitreiher_models import MaLoSelector, QueryRequest, ValueRecord, iter_records, read_stream
+
+cet = timezone(timedelta(hours=1))
+request = QueryRequest(
+    select=[MaLoSelector(malo="87253749908")],
+    from_=datetime(2026, 1, 1, tzinfo=cet),
+    to=datetime(2026, 2, 1, tzinfo=cet),
+    interval="PT60M",
+)
+body = request.model_dump_json()  # {"select":[…],"from":"2026-01-01T00:00:00+01:00",…}
+
+for record in read_stream(response_bytes):  # raises MissingEndError for a cut-off stream
+    if isinstance(record, ValueRecord):
+        print(record.from_, record.decimal)  # decimal.Decimal, no float rounding
+```
+
+`from` is a Python keyword, so the attribute is `from_`; the JSON key is always `from`.
+
+## Fixtures
+
+```
+testdata/
+  error_codes.json                       the known request- and record-level codes
+  query_request/{valid,invalid}/         request bodies (DST days, +02:00 vs Z, naive timestamps, custom selectors, versions, …)
+  resolve_request/, versions_request/
+  records/{valid,invalid}/               single NDJSON records, one valid fixture per record-level error code
+  streams/{valid,invalid}/               whole NDJSON responses (DST days with 92/100 quarter hours, gaps, versions, paging, …)
+  resolve_response/, versions_response/
+  error_envelope/{valid,invalid}/        one valid fixture per request-level error code
+  records/read_only/, error_envelope/read_only/
+                                         unknown error codes: they parse, but writing them is refused
+  system_info/
+```
+
+`X.canonical.json` next to `X.json` is the expected re-serialization when it differs from the input
+(e.g. `+00:00` becomes `Z`, `"cursor": null` is omitted, unknown response keys are dropped).
+Consumers in other languages (the Go service, future Rust/C#/TS models) should run the same fixtures.
+
+`testdata/serialized.golden` pins the exact bytes both languages write for every valid fixture
+(`<fixture>\t<JSON>` per line), so Go and Python output is byte-for-byte identical: compact JSON,
+keys in model order, map keys (`params`, `attributes`) sorted, and Go's string escaping — `<`, `>`,
+`&`, U+2028 and U+2029 are written as `<`, `>`, `&`, `
`, `
`; all other
+non-ASCII characters are written as UTF-8. Python's `model_dump_json()` and `dump_record()` apply
+that escaping; in Go, `json.Marshal`, `MarshalRecord` and a default `json.Encoder` produce it (an
+encoder with `SetEscapeHTML(false)` would not).
+
+Every invalid fixture has an entry in `testdata/invalid_reasons.json`, so that a fixture cannot pass by
+being rejected for the wrong reason:
+
+- `go`: a substring of the Go error (the field path and the failed rule);
+- `python`: the pydantic error that must be among `ValidationError.errors()` — its `loc` (joined with
+  `.`), its `type` and, only for the error types whose messages the models write themselves
+  (`value_error`, `instant`, `unknown_key`, `version_selector`), `msg`, a substring of its message.
+  pydantic's own messages are not compared, so rewording them in a pydantic upgrade does not break
+  the fixtures.
+
+### Regenerating the pinned files
+
+- **`serialized.golden`** — after an intended change to the output (or a new valid fixture), run
+  `go test -run Golden -update .`, review the diff, then `uv run pytest unittests` to confirm that
+  Python writes the same bytes. The file is only ever written by Go; Python compares against it.
+- **`invalid_reasons.json`** — maintained by hand, not generated, because each entry states the
+  *intended* reason. For a new invalid fixture, the failing Go test prints the actual error
+  (`go test -run InvalidFixtures .`) and the failing Python test prints a ready-made `python` entry
+  (`uv run pytest unittests -k invalid_fixture`); check that both name the rule the fixture is about
+  before adding them. Keep the file sorted, two-space indented and ASCII-only
+  (`json.dumps(..., indent=2, sort_keys=True, ensure_ascii=True)`).
+- **After a pydantic upgrade** — run `uv run pytest unittests`. A failing `invalid_fixture` test means
+  that pydantic changed an error's `loc` or `type` (messages are not compared), or that a fixture is
+  now rejected for a different reason; compare the printed `errors()` with the entry and update the
+  entry only if the fixture is still rejected for the intended reason. `serialized.golden` failures
+  after an upgrade mean that the output bytes changed and need a fix in the models, not a new golden
+  file.
+
+## gRPC
+
+`proto/zeitreiher/v1/*.proto` (package `zeitreiher.v1`, service `SeriesService` with `Query`,
+`Resolve`, `ListVersions`, `System`) is the published gRPC contract. Field names equal the JSON keys.
+Request timestamps are RFC 3339 strings (so the explicit-offset rule holds for gRPC too); response
+timestamps are `google.protobuf.Timestamp`. Conformance with the JSON contract is defined through
+the hand-written models (fixture → model → proto → model → JSON), not through protojson. Generate
+code in the consuming project, e.g. with buf managed mode.
+
+A failed call (and a `Query` stream cut off before its `EndRecord`) ends with a gRPC status that
+carries a `google.rpc.ErrorInfo` detail with `reason` = the public request-level code and
+`domain` = `"zeitreiher.hochfrequenz.de"`; `series_service.proto` lists the status code for each
+code. Clients switch on `reason`.
+
+## Versioning
+
+`v1` is in the URL path (`/api/v1/…`), the proto package (`zeitreiher.v1`) and the models' major
+version. Additive changes (new optional fields, new error codes) stay in v1; breaking changes need v2.
+
+The Go package `zeitreihermodels` lives at the **repository root** (import path
+`github.com/hochfrequenz/zeitreiher-models`); there is no `v1` sub-package. Its major version follows
+Go module versioning: v1 is released as tags `v1.x.y` of this module path, and a breaking v2 becomes
+the module `github.com/hochfrequenz/zeitreiher-models/v2` (tags `v2.x.y`). The Python package takes its
+version from the same tags.
+
+## Development
+
+```bash
+go test ./...                      # Go
+golangci-lint run && golangci-lint fmt --diff
+uv sync --group dev                # Python
+uv run pytest unittests
+uv run ruff check src unittests && uv run ruff format --check .
+uv run mypy --strict src/zeitreiher_models unittests
+buf lint && buf build && buf format --diff --exit-code   # buf v1.75.0
+```
+
+The Go tests (`fixtures_test.go`) and the Python tests (`unittests/test_fixtures.py`) use the same
+table of fixture kinds; a new fixture directory must be added to both. `unittests/test_proto_contract.py`
+fails when a model and its proto message disagree on field names.
+
+## License
+
+MIT