fastapi-streams 0.0.1__tar.gz → 0.1.0__tar.gz

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/.github/workflows/ci.yml

@@ -2,7 +2,9 @@ name: CI
 
 on:
   push:
+    branches: ["**"]
   pull_request:
+  workflow_call:
 
 permissions:
   contents: read
@@ -16,15 +18,17 @@ jobs:
       matrix:
         python: ["3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python }}
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: "24"
           cache: npm
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: "0.9.2"
           enable-cache: true
@@ -38,7 +42,7 @@ jobs:
       - run: npm run typecheck
       - run: npm run test:coverage
       - run: uv run pytest -q --cov --cov-report=term-missing --cov-report=xml:coverage-python.xml
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
           name: coverage-python-${{ matrix.python }}
@@ -47,4 +51,5 @@ jobs:
             coverage-typescript.lcov
       - run: uv run python scripts/codegen.py --check
       - run: uv build
+      - run: uv run --frozen twine check --strict dist/*
       - run: uv run python scripts/check_package.py

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/.github/workflows/compatibility.yml

@@ -2,7 +2,9 @@ name: Dependency compatibility
 
 on:
   push:
+    branches: ['**']
   pull_request:
+  workflow_call:
   workflow_dispatch:
   schedule:
     - cron: '17 7 * * 1'
@@ -22,22 +24,24 @@ jobs:
         python: ['3.12', '3.13', '3.14']
         dependencies: [lowest, latest]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: ${{ matrix.python }}
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
         with:
           node-version: '24'
           cache: npm
-      - uses: astral-sh/setup-uv@v6
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with:
           version: '0.9.2'
           enable-cache: true
       - run: npm ci --ignore-scripts
       - name: Resolve dependencies and run native FastAPI and client integration tests
         run: python scripts/test_compat.py --python ${{ matrix.python }} --dependencies ${{ matrix.dependencies }}
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
           name: compatibility-${{ matrix.os }}-${{ matrix.python }}-${{ matrix.dependencies }}

fastapi_streams-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,115 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - name: Validate tag, versions and main ancestry
+        id: version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: python scripts/check_release.py "$RELEASE_TAG" >> "$GITHUB_OUTPUT"
+
+  ci:
+    needs: validate
+    uses: ./.github/workflows/ci.yml
+
+  compatibility:
+    needs: validate
+    uses: ./.github/workflows/compatibility.yml
+
+  build:
+    needs: [validate, ci, compatibility]
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+          cache: npm
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: '0.9.2'
+      - run: uv sync --locked --all-extras
+      - run: npm ci --ignore-scripts
+      # Build the wheel from the sdist, including packaged templates and schemas.
+      - run: uv build --no-sources
+      - run: uv run --frozen twine check --strict dist/*
+      - run: uv run --frozen python scripts/check_package.py
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: release-distributions
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 30
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/fastapi-streams
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Publish to PyPI with Trusted Publishing and attestations
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          attestations: true
+
+  github-release:
+    needs: [validate, publish]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Create GitHub Release with the published distributions
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          PRERELEASE: ${{ needs.validate.outputs.prerelease }}
+        run: |
+          gh release create "$RELEASE_TAG" dist/* \
+            --verify-tag --generate-notes --title "$RELEASE_TAG" \
+            --prerelease="$PRERELEASE"

fastapi_streams-0.1.0/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+All notable changes and consumer upgrade steps are recorded here. Entries marked
+unreleased describe prepared source versions that have not been published.
+
+## 0.1.0 - 2026-10-17
+
+### Added
+
+- Generated TypeScript JSDoc and Python method docstrings include OpenAPI
+  summaries, descriptions, deprecation, and SDK-specific iteration, cancellation,
+  validation, and error behavior. Endpoint descriptions remain the source for
+  business guarantees such as retention or job lifetime after disconnect.
+- `OptionalDiscriminatorWarning` identifies optional discriminator fields in
+  stream event unions, including nested and referenced events. Diagnostics name
+  the operation, route, model, and field; generation preserves schema requiredness.
+- Explicit `OperationErrorBody` aliases in both SDKs distinguish declared HTTP
+  response bodies from thrown exceptions. Existing `OperationError` aliases remain
+  available; TypeScript marks them deprecated. Method documentation lists the
+  declared HTTP statuses and media types. Existing Python anonymous error-model
+  imports such as `OperationError0` retain their names.
+- TypeScript `isHttpError(error, isDetails)` narrows `HttpError.details` only after
+  a caller-supplied type guard succeeds. It adds no runtime dependencies or assumed
+  problem format. HTTP status and operation provenance remain caller checks.
+- Checked TypeScript and Python error-handling consumer examples, plus a
+  standalone FastAPI dependency/problem-response regression without an error
+  framework. Public generated error-alias name collisions now fail explicitly.
+
+### Changed
+
+- Develop in `mathisarends/canon`; package source, documentation, and issue URLs
+  now point to the monorepo.
+- Single-value string fields now use TypeScript/Python literals instead of
+  synthesizing a separate public constant object or `StrEnum` for every field.
+  Explicitly named enums, multi-value field enums, and shared event discriminator
+  enums remain available. TypeScript also omits unnecessary property quotes and
+  union parentheses while preserving intersection grouping and extra-field types.
+
+### Breaking generated-code changes
+
+- Synthesized single-field constants such as `InvalidCredentialsProblemTitle`
+  and `InvalidCredentialsProblemType` are no longer exported. Replace usages like
+  `InvalidCredentialsProblemTitle.INVALID_CREDENTIALS` with the wire literal
+  `"Invalid credentials"`, then remove unused imports. Python singleton fields
+  now contain plain strings instead of generated `StrEnum` members; replace
+  identity checks with value comparisons. Shared discriminator values such as
+  `RunEventType.RUN_STARTED` and explicit schema enums are unchanged.
+- Generated `OperationError`/`OperationErrorBody` names are reserved in both
+  SDKs. Python now reports collisions explicitly too. If a schema uses one of
+  these names, rename the colliding model or choose a distinct `operation_id`.
+
+### Upgrade from 0.0.1
+
+1. Update `fastapi-streams[codegen]` to `0.1.0`, using the same version for schema
+   export and both SDKs.
+2. Regenerate committed clients from the application's OpenAPI document. Existing
+   method names and call signatures are unchanged:
+
+   ```sh
+   uv run fastapi-streams schema --app your_app:app --output openapi.json
+   uv run fastapi-streams generate --schema openapi.json --language typescript --output generated/typescript
+   uv run fastapi-streams generate --schema openapi.json --language python --output generated/python
+   uv run fastapi-streams check --app your_app:app --schema openapi.json --language typescript --output generated/typescript
+   uv run fastapi-streams check --app your_app:app --schema openapi.json --language python --output generated/python
+   ```
+
+   Substitute the application's existing module and output paths. Preserve
+   `--python-http-client httpx2` on generation and checks if it is already used.
+3. Review optional discriminator warnings. For output-only Pydantic event models
+   whose defaults are always serialized, see the serialization configuration in
+   [the codegen guide](docs/codegen.md#event-discriminators). Do not make optional
+   request fields required merely because they have Python defaults. Add
+   endpoint-specific guarantees to OpenAPI descriptions. Export and regenerate
+   again after changing models or descriptions.
+4. Apply the single-field constant migration above if the application imported
+   these generated names. HTTP payloads, method names, and signatures are unchanged.
+5. Prefer `OperationErrorBody` over `OperationError` when referring to response
+   bodies. Keep caught errors unknown until checked; validate `HttpError.details`
+   with a body guard in TypeScript or Pydantic `TypeAdapter` in Python. See
+   [HTTP error contracts](docs/clients.md#http-error-contracts). Unexpected proxy
+   responses must continue through the generic `HttpError` fallback.
+6. Run the consuming project's TypeScript/Python type checks and stream tests.
+   Commit the exported schema and regenerated SDKs together with call-site updates.
+
+## 0.0.1
+
+- Initial typed GET/POST JSON SSE routers, OpenAPI export, TypeScript and Python
+  generators, shared transports, and contract/client drift checks.

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.0.1
+Version: 0.1.0
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
-Project-URL: Documentation, https://github.com/mathisarends/fastapi-streams/tree/main/docs
-Project-URL: Source, https://github.com/mathisarends/fastapi-streams
-Project-URL: Issues, https://github.com/mathisarends/fastapi-streams/issues
+Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams/docs
+Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams
+Project-URL: Issues, https://github.com/mathisarends/canon/issues
 Author: Mathis Arends
 License-Expression: MIT
 License-File: LICENSE
@@ -224,6 +224,9 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 
 ## Documentation
 
+See the [changelog and upgrade steps](CHANGELOG.md) when updating the library
+and regenerating committed clients.
+
 | Guide | Topics |
 | --- | --- |
 | [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
@@ -231,6 +234,7 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 | [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
 | [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+| [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
 v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
 contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/README.md

@@ -206,6 +206,9 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 
 ## Documentation
 
+See the [changelog and upgrade steps](CHANGELOG.md) when updating the library
+and regenerating committed clients.
+
 | Guide | Topics |
 | --- | --- |
 | [Quickstart](docs/quickstart.md) | Setup, event models, and FastAPI integration. |
@@ -213,6 +216,7 @@ and committed OpenAPI regression fixtures in `tests/fixtures/`. Verify all gener
 | [Client usage](docs/clients.md) | Enums, authentication, cancellation, and errors. |
 | [Architecture](docs/architecture.md) | Native SSE, shared IR, templates, and transports. |
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
+| [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
 v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
 contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/docs/README.md

@@ -9,6 +9,7 @@ TypeScript Fetch and Python HTTPX clients from the same definitions.
 | [Contracts and codegen](codegen.md) | Export OpenAPI, generate both clients, and detect drift in CI. |
 | [Client usage](clients.md) | Named event values, typed iteration, authentication, cancellation, and errors. |
 | [Development](development.md) | Local checks, test coverage, supported features, and roadmap. |
+| [Releasing](releasing.md) | Tag-based releases, PyPI Trusted Publishing setup, and recovery. |
 | [Architecture](architecture.md) | Server integration, shared IR, generation, and transport boundaries. |
 
 Start with the [quickstart](quickstart.md), then use the

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/docs/clients.md

@@ -5,8 +5,10 @@
 ## Named values and typed iteration
 
 Discriminated unions produce an enum named after the union and discriminator:
-`RunEvent` + `type` becomes `RunEventType`. String enums and literal model fields
-also get named values. Python emits `StrEnum`; TypeScript emits an `as const`
+`RunEvent` + `type` becomes `RunEventType`. Named string enums and multi-value
+literal model fields also get named values. Single constant fields, such as
+problem titles and URIs, remain inline literals. Python emits `StrEnum` for enums;
+TypeScript emits an `as const`
 object plus a union type. Both retain exhaustive discriminator narrowing.
 Parameters use camelCase in TypeScript and snake_case in Python; wire aliases
 are preserved.
@@ -117,6 +119,54 @@ Pydantic; TypeScript provides static types and JSON decoding, with no runtime
 schema validator. Cancellation propagates normally; application error events
 remain ordinary members of the user-defined union.
 
+## HTTP error contracts
+
+The SDK works with ordinary OpenAPI response declarations, including
+`application/json`, `application/problem+json`, and other declared response media
+types. No error registry or particular problem envelope is required. Declare
+HTTP failures with FastAPI's `responses=`; put authentication, authorization,
+and resource checks in dependencies so they can fail before the response starts.
+Even generator statements before the first `yield` execute after response start.
+
+Each operation with declared error schemas exports an `OperationErrorBody`
+union: for example `StreamRunEventsErrorBody`. The earlier `OperationError`
+name remains an alias for compatibility; it describes response bodies, not
+the exceptions thrown by the SDK. Python imports these aliases from `models`;
+TypeScript exports them from the SDK entrypoint.
+
+Catch HTTP failures around **iteration**, since opening the request is lazy.
+`HttpError.details` deliberately remains unvalidated: proxies and servers can
+return unexpected JSON, plain text, HTML, incomplete bodies, or no body at all.
+An operation's body union does not associate each variant with a status and does
+not prove which operation produced an exception. Check the actual HTTP status
+and validate the body before using application fields.
+
+TypeScript provides `isHttpError(error, isDetails)`. Supply a type guard that
+checks every field promised by its return type, or adapt an existing runtime
+validator. The helper verifies the SDK exception class and invokes that guard;
+it does not generate a schema validator or validate the HTTP status. A generic
+type argument alone cannot replace the required guard. Failed guards leave the
+original `HttpError` available for generic handling.
+
+Python can validate `error.details` with `TypeAdapter(OperationErrorBody)` and
+handle `ValidationError` as an unexpected response. Both approaches retain
+the original status, response, and diagnostics. Schema unions with permissive
+variants may accept a broad range of bodies; inspect the parsed variant before
+using its fields. Existing limits on bounded HTTP diagnostics still apply.
+
+The checked consumer examples show HTTP validation errors, fallback handling,
+stream parsing/transport errors, and ordinary application error events:
+
+- [TypeScript error handling](../examples/agent_runs/errors.ts), compiled with the
+  generated SDK under the repository's strict TypeScript configuration.
+- [Python error handling](../examples/agent_runs/errors.py), checked by Pyright
+  with the generated models.
+
+Caller cancellation continues to propagate. Neither SDK converts application
+error events into exceptions or automatically retries a stream.
+
+## Python model fields
+
 Python uses `None` for omitted optional fields; `model_fields_set` distinguishes
 absence from explicit null. Explicit null is rejected for fields that may only
 be omitted. Requests exclude unset fields and serialize using wire aliases.

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/docs/codegen.md

@@ -29,6 +29,12 @@ The generator extracts application data from
 reachable from their parameters, bodies, events and error responses are emitted.
 Operations use the first tag as their group, defaulting to `streams`.
 
+Generated method documentation carries each operation's `summary`, `description`,
+and `deprecated` marker alongside language-specific SDK behavior. Describe
+replay, retention, and server job lifetime explicitly on your endpoint; the
+generator does not infer these business guarantees. Python early exits should
+use `contextlib.aclosing`; TypeScript `for await` cleanup closes its reader.
+
 TypeScript has no runtime dependencies and uses Fetch-compatible APIs. The
 example uses ES modules and is tested on Node 24. Generated Python packages
 require Python 3.12+, `httpx>=0.28` and `pydantic>=2.11.2` (`uv add httpx pydantic`).
@@ -57,6 +63,38 @@ REST operations remain available in the contract for an existing SDK generator
 such as Orval or HeyAPI. Keep REST and streaming SDKs in separate output
 directories. Reusing external generated model imports is a future feature.
 
+## Event discriminators
+
+A Python default allows omitting a field when constructing a model. It does not
+automatically make the field required in JSON Schema. The generator respects
+`required` and warns with `OptionalDiscriminatorWarning` when a stream event
+union uses an optional discriminator, including nested unions. An absent tag may
+prevent variant selection; TypeScript's static types do not validate incoming JSON.
+
+For **output-only** event models whose serializer always emits default fields,
+configure the output schema to describe that behavior:
+
+```python
+from pydantic import BaseModel, ConfigDict
+
+
+class StreamEvent(BaseModel):
+    model_config = ConfigDict(
+        json_schema_mode_override="serialization",
+        json_schema_serialization_defaults_required=True,
+    )
+```
+
+Inherit event variants from this model, or apply the configuration to an existing
+output-only base. It marks all serialized default fields required, not only the
+discriminator. Avoid applying it globally to shared request models: input and
+output requiredness can differ. Alternatively, declare the tag without a default
+and pass it explicitly. Regenerate the schema and clients after changing models.
+
+Warnings are advisory and do not change fields or defaults. Python callers can
+filter or promote this category using the standard `warnings` module; the category
+is available from `fastapi_streams.codegen.diagnostics`.
+
 ## Check drift in CI
 
 ```sh

{fastapi_streams-0.0.1 → fastapi_streams-0.1.0}/docs/development.md

@@ -17,6 +17,7 @@ npm run test:coverage
 uv run pytest -q --cov --cov-report=term-missing --cov-report=xml:coverage-python.xml
 uv run python scripts/codegen.py --check
 uv build
+uv run --frozen twine check --strict dist/*
 uv run python scripts/check_package.py
 ```
 

fastapi_streams-0.1.0/docs/releasing.md

@@ -0,0 +1,160 @@
+# Releasing
+
+[Documentation](README.md) · [Project](../README.md)
+
+A pushed Git tag is the release signal. The agent preparing a release only needs
+permission to push the release tag to GitHub. GitHub Actions authenticates to PyPI
+with OIDC (Trusted Publishing); no PyPI password or API token is stored in GitHub
+or provided to an agent.
+
+## One-time maintainer setup (required before the first tag)
+
+### 1. Configure the GitHub environment
+
+Open [Settings → Environments](https://github.com/mathisarends/fastapi-streams/settings/environments)
+and create an environment named **`pypi`**.
+
+- Under **Deployment branches and tags**, select **Selected branches and tags**
+  and add a **tag** rule for `v*`. Do not add a branch rule.
+- Recommended: add a required reviewer if you want a human to approve each PyPI
+  upload after the agent pushes a tag. Enable prevention of self-review if your
+  approval policy requires another person. Without required reviewers, a valid
+  tag publishes automatically after validation and tests pass.
+- Do not add a PyPI secret. The `publish` job requests `id-token: write`; the
+  separate GitHub Release job requests `contents: write` for its built-in
+  `GITHUB_TOKEN`. Repository or organization policies must allow these permissions
+  and the actions referenced in the workflows.
+
+Create and protect this environment explicitly before publishing; a workflow can
+otherwise create an environment without your intended protection rules.
+
+### 2. Register the PyPI Trusted Publisher
+
+Sign in to PyPI with the account that owns (or will own) `fastapi-streams`.
+For an existing project, open its
+[Publishing settings](https://pypi.org/manage/project/fastapi-streams/settings/publishing/).
+For a first publication, use
+[Add a new pending publisher](https://pypi.org/manage/account/publishing/).
+
+Select **GitHub** and enter these exact values:
+
+| Field | Value |
+| --- | --- |
+| PyPI project name (pending publishers only) | `fastapi-streams` |
+| Owner | `mathisarends` |
+| Repository name | `fastapi-streams` |
+| Workflow name | `release.yml` (filename only) |
+| Environment name | `pypi` |
+
+Confirm you control the package name. A pending publisher does not reserve a name;
+the project is created on the first successful upload. PyPI and TestPyPI have
+independent accounts and publisher registrations; this workflow publishes to
+production PyPI only.
+
+### 3. Protect the release inputs
+
+In [Settings → Rules → Rulesets](https://github.com/mathisarends/fastapi-streams/settings/rules),
+protect `main` with pull request reviews and the existing CI and compatibility
+checks. Review changes to the workflows, packaging configuration, and release
+scripts as carefully as library changes.
+
+Create a tag ruleset targeting `v*`. Restrict creation to authorized release
+maintainers or a dedicated release GitHub App, and prevent updates and deletion.
+Configure bypass access deliberately so the actor pushing a release tag can
+create it. An agent that only prepares release PRs does not need tag creation
+permission. An agent authorized to trigger releases does need that GitHub
+permission, but still needs no PyPI credentials.
+
+## Prepare and trigger a release
+
+1. Resolve known release blockers and decide which changes belong in this version.
+2. Prepare a PR against `main`. Update `project.version` in `pyproject.toml` and
+   `__version__` in `fastapi_streams/__init__.py`, then run `uv lock` and commit the
+   updated `uv.lock`. Keep all three versions identical. For the first `0.0.1`
+   release these files already agree; a version bump is only needed for a new
+   version. Describe user-facing changes in the PR; GitHub uses merged PRs to
+   generate release notes.
+3. Merge after review and passing checks. Then tag the intended commit on `main`:
+
+   ```sh
+   git fetch origin main --tags
+   git switch main
+   git pull --ff-only origin main
+   python scripts/check_release.py v0.0.1
+   git tag -a v0.0.1 -m "Release v0.0.1"
+   git push origin v0.0.1
+   ```
+
+   Substitute the intended version everywhere. For an older release candidate
+   already on `main`, check out that exact commit before validating and tagging.
+   An annotated tag is recommended; do not move or reuse a published tag.
+
+4. Follow the [Release workflow](https://github.com/mathisarends/fastapi-streams/actions/workflows/release.yml)
+   and approve the `pypi` deployment if required reviewers are configured.
+5. Verify the version on [PyPI](https://pypi.org/project/fastapi-streams/) and the
+   [GitHub Releases page](https://github.com/mathisarends/fastapi-streams/releases).
+   Consumers can then install `fastapi-streams[codegen]==0.0.1` from PyPI.
+
+Supported tags are `vX.Y.Z`, `vX.Y.ZaN`, `vX.Y.ZbN`, and `vX.Y.ZrcN`, using
+canonical numbers without leading zeroes. Prereleases are published to PyPI and
+marked as prereleases on GitHub. Development, local, and post-release versions
+are deliberately rejected.
+
+If a GitHub Actions agent pushes the tag, use an appropriately scoped GitHub App
+installation token or personal access token. Events caused by the repository's
+default `GITHUB_TOKEN` do not normally start another workflow. A locally running
+agent can use its authorized GitHub Git credentials. Neither approach requires
+PyPI credentials.
+
+## What the workflow guarantees
+
+`.github/workflows/release.yml` runs these stages in order:
+
+1. **Validate:** reject unsupported tags, mismatched versions in the project,
+   module or lockfile, and commits outside `origin/main`. Validation reads the
+   module with Python's AST parser instead of importing package code.
+2. **Test:** call the existing CI workflow (Python 3.12–3.14, lint, types, Python
+   and TypeScript coverage, generated-file drift and wheel smoke tests) and the
+   complete Linux/Windows dependency compatibility matrix. These run against the
+   tag's exact commit and must all pass.
+3. **Build:** check the lockfile, build an sdist and a wheel from it, check metadata
+   and the README with Twine, then smoke-test this wheel in isolated environments
+   for the core install and each Python HTTP backend. Upload the distributions as
+   one immutable workflow artifact.
+4. **Publish:** download that artifact in a fresh job, pass the `pypi` environment
+   restrictions, and publish through PyPI Trusted Publishing with attestations.
+   This job has no source checkout, build steps, or stored credentials. Only this
+   job can request an OIDC token.
+5. **GitHub Release:** after PyPI succeeds, attach the same wheel and sdist to a
+   GitHub Release with automatically generated release notes. Only this job has
+   repository write permission.
+
+Runs for the same tag are serialized without canceling an in-progress release.
+All external actions in the release and its called workflows are pinned to full
+commit SHAs; review and update those pins when adopting action updates.
+
+## Failures and retries
+
+- Validation, test or build failure: nothing is published. Fix the release inputs
+  through a PR and use a new version/tag for the corrected candidate.
+- Missing publisher or environment approval: complete the setup above and rerun
+  **failed jobs** on the original workflow run. This preserves the tested build
+  artifact. Artifacts are retained for 30 days.
+- PyPI succeeded but GitHub Release creation failed: rerun only the failed GitHub
+  Release job. Do not rerun successful publishing jobs or rebuild the same PyPI
+  version. If a GitHub Release already exists after a partial failure, inspect it
+  and attach the original run's missing assets manually.
+- Partial PyPI upload: inspect which files reached PyPI before retrying. The
+  workflow deliberately does not skip existing files; PyPI does not allow replacing
+  a published distribution. Publish a new version for changed package contents.
+
+The setup is implemented here without creating a tag or publishing a package.
+The first live upload also verifies your external PyPI and environment settings.
+
+## References
+
+- [PyPI: publishing with a Trusted Publisher](https://docs.pypi.org/trusted-publishers/using-a-publisher/)
+- [PyPI: creating a project with a pending publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [PyPI: security model](https://docs.pypi.org/trusted-publishers/security-model/)
+- [GitHub: OIDC with PyPI](https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-pypi)
+- [GitHub: triggering workflows from workflows](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow)