artesian-sdk 4.4.0b1__tar.gz → 5.0.0.dev2__tar.gz

artesian_sdk-5.0.0.dev2/.gitattributes

@@ -0,0 +1 @@
+.github/workflows/*.sh text eol=lf

artesian_sdk-5.0.0.dev2/.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,20 @@
+name: Copilot Setup Steps
+
+on:
+  workflow_dispatch:
+  push:
+    paths: [.github/workflows/copilot-setup-steps.yml]
+  pull_request:
+    paths: [.github/workflows/copilot-setup-steps.yml]
+
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.23"
+          python-version: "3.14"
+          enable-cache: false

artesian_sdk-5.0.0.dev2/.github/workflows/python-tests.yml

@@ -0,0 +1,404 @@
+name: "Artesian SDK Python"
+
+on:
+  push:
+    branches: [master]
+    tags:
+      - "v[0-9]*.[0-9]*.[0-9]*"
+  pull_request:
+    branches: [main, master, develop, develop-beta]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test-matrix:
+    name: "Python ${{ matrix.python-version }} / ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    # Test artifacts use a fixed version regardless of the release tag.
+    env:
+      SETUPTOOLS_SCM_PRETEND_VERSION: "0.0.0"
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+        os: ["ubuntu-latest", "windows-latest", "macos-latest"]
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv / Python ${{ matrix.python-version }}
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        id: install
+        run: uv sync --locked
+
+      - name: Run Ruff and Pyrefly
+        shell: bash
+        run: |
+          uv run --no-sync ruff check --target-version "py${PYTHON_VERSION//./}" --output-format github .
+          uv run --no-sync ruff format --check --target-version "py${PYTHON_VERSION//./}" .
+          uv run --no-sync pyrefly check --python-version "$PYTHON_VERSION" --output-format github
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
+
+      - name: Test Pytest
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: |
+          uv run --no-sync pytest --junitxml=junit/test-results-${{ matrix.python-version }}-${{ matrix.os }}.xml
+
+      - name: Build package
+        if: ${{ !cancelled() && steps.install.outcome == 'success' }}
+        run: uv build
+
+      - name: Upload pytest test results
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        if: always()
+        with:
+          name: test-results-build-${{ matrix.python-version }}-${{ matrix.os }}
+          path: junit/test-results-${{ matrix.python-version }}-${{ matrix.os }}.xml
+
+      - name: Upload build coverage
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        if: always()
+        with:
+          name: coverage-build-${{ matrix.python-version }}-${{ matrix.os }}
+          include-hidden-files: true
+          path: |
+            .coverage
+            coverage.xml
+
+  checks:
+    name: "Checks"
+    runs-on: ubuntu-latest
+    needs: [test-matrix]
+    if: always()
+
+    permissions:
+      contents: read
+      checks: write
+      code-quality: write
+      pull-requests: read
+    env:
+      SETUPTOOLS_SCM_PRETEND_VERSION: "0.0.0"
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          fetch-depth: 0
+
+      - name: "Set up uv"
+        if: ${{ needs.test-matrix.result == 'success' }}
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.14"
+
+      - name: "Install coverage tooling"
+        if: ${{ needs.test-matrix.result == 'success' }}
+        run: uv sync --locked --no-dev --group test
+
+      - name: "Download coverage artifacts"
+        if: ${{ needs.test-matrix.result == 'success' }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          pattern: coverage-build-*
+          path: coverage
+
+      - name: "Create code coverage report"
+        if: ${{ needs.test-matrix.result == 'success' }}
+        shell: bash
+        run: |
+          uv run --no-sync coverage combine coverage/coverage-build-*/.coverage
+          uv run --no-sync coverage xml
+          uv run --no-sync coverage html
+          uv run --no-sync coverage report --format=markdown >> "$GITHUB_STEP_SUMMARY"
+
+      - name: "Upload combined coverage"
+        if: ${{ needs.test-matrix.result == 'success' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: coverage-combined
+          path: |
+            coverage.xml
+            htmlcov/
+
+      - name: "Upload coverage to GitHub"
+        if: >
+          needs.test-matrix.result == 'success' &&
+          ((github.event_name == 'pull_request' &&
+            github.event.pull_request.head.repo.full_name == github.repository) ||
+           (github.event_name == 'push' && github.ref == 'refs/heads/master'))
+        uses: actions/upload-code-coverage@2b21a77928be8d5168c2b9581a67f2adbebacc52 # v1
+        with:
+          file: coverage.xml
+          language: Python
+          label: code-coverage/pytest
+
+      - name: "Download test result artifacts"
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        if: always()
+        with:
+          pattern: test-results-build-*
+          path: test-results
+          merge-multiple: true
+
+      - name: "Test Report"
+        uses: dorny/test-reporter@d1b5dff021aa968b288b02285a8bf47471c5928a # v3
+        if: always() && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)
+        with:
+          name: Python Tests
+          path: "test-results/**/*.xml"
+          reporter: java-junit
+          fail-on-error: "true"
+          use-actions-summary: "true"
+
+      - name: "Require successful matrix"
+        if: always()
+        env:
+          MATRIX_RESULT: ${{ needs.test-matrix.result }}
+        run: test "$MATRIX_RESULT" = success
+
+  # Stable: v4.3.0 -> 4.3.0; tag commit must be contained in master.
+  # Development / RC: v5.0.0.dev1 / v5.0.0rc2; tag commit must be contained in master.
+  # Beta: v4.3.0b1 / v5.0.0b1; tag commit must be contained in develop-beta.
+  # The beta version must be the next minor or major after the latest master GA.
+  # PR preview: v4.3.0a69.post1 / v4.3.0a69.post2. The base version
+  # must match the latest master GA version; 69 is the PR number, and
+  # 1 / 2 are preview iterations. The tag must point to the unmerged PR
+  # head containing current master, not to a synthetic merge commit.
+  build-release:
+    name: "Build release"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    needs: [checks]
+
+    if: >
+      (github.event_name == 'push' || github.event_name == 'workflow_dispatch') &&
+      startsWith(github.ref, 'refs/tags/v') &&
+      needs.checks.result == 'success'
+
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ github.sha }}
+          fetch-depth: 0
+
+      - name: "Validate release tag"
+        id: tag
+        shell: bash
+        run: |
+          TAG="$GITHUB_REF_NAME"
+          if [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+a[0-9]+\.post[0-9]+$ ]]; then
+            KIND=preview
+          elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+b[0-9]+$ ]]; then
+            KIND=beta
+          elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+\.dev[0-9]+$ ]]; then
+            KIND=dev
+          elif [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+rc[0-9]+$ ]]; then
+            KIND=rc
+          else
+            KIND=ga
+          fi
+          bash .github/workflows/validate_tag.sh "$TAG" "$KIND"
+          echo "kind=$KIND" >> "$GITHUB_OUTPUT"
+          echo "version=${TAG#v}" >> "$GITHUB_OUTPUT"
+
+      - name: "Validate release commit is contained in master"
+        if: steps.tag.outputs.kind == 'ga' || steps.tag.outputs.kind == 'dev' || steps.tag.outputs.kind == 'rc'
+        shell: bash
+        run: bash .github/workflows/validate_branch.sh "master"
+
+      - name: "Validate release commit is contained in develop-beta"
+        if: steps.tag.outputs.kind == 'beta'
+        shell: bash
+        run: bash .github/workflows/validate_branch.sh "develop-beta"
+
+      - name: "Validate next minor or major version"
+        if: steps.tag.outputs.kind == 'beta'
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+
+          git fetch origin master --tags
+
+          MASTER_VERSION=$(
+            git tag --merged origin/master --sort=-version:refname |
+            grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' |
+            head -n 1 |
+            sed 's/^v//'
+          )
+
+          BETA_VERSION=$(echo "$TAG" | sed -E 's/^v([0-9]+\.[0-9]+\.[0-9]+)b[0-9]+$/\1/')
+
+          echo "Master GA version: $MASTER_VERSION"
+          echo "Beta version:      $BETA_VERSION"
+
+          if [[ -z "$MASTER_VERSION" ]]; then
+            echo "::error::Could not determine the latest GA version on master."
+            exit 1
+          fi
+
+          MASTER_MAJOR=$(echo "$MASTER_VERSION" | cut -d. -f1)
+          MASTER_MINOR=$(echo "$MASTER_VERSION" | cut -d. -f2)
+          NEXT_MINOR="$((10#$MASTER_MINOR + 1))"
+          NEXT_MAJOR="$((10#$MASTER_MAJOR + 1))"
+
+          if [[ "$BETA_VERSION" != "${MASTER_MAJOR}.${NEXT_MINOR}.0" &&
+                "$BETA_VERSION" != "${NEXT_MAJOR}.0.0" ]]; then
+            echo "::error::Beta version $BETA_VERSION is not the next minor or major version after master GA $MASTER_VERSION."
+            echo "::error::Expected: ${MASTER_MAJOR}.${NEXT_MINOR}.0bN or ${NEXT_MAJOR}.0.0bN"
+            exit 1
+          fi
+
+          echo "Beta version $BETA_VERSION is the next minor or major version after master GA $MASTER_VERSION."
+
+      - name: "Validate preview source"
+        if: steps.tag.outputs.kind == 'preview'
+        shell: bash
+        run: |
+          git fetch origin master
+
+          if ! git merge-base --is-ancestor origin/master HEAD; then
+            echo "::error::PR Preview tag does not contain the current master."
+            exit 1
+          fi
+
+          PR_NUMBER="${GITHUB_REF_NAME#*a}"
+          PR_NUMBER="${PR_NUMBER%%.*}"
+          git fetch origin "refs/pull/$PR_NUMBER/head"
+
+          if git merge-base --is-ancestor HEAD origin/master ||
+             [[ "$(git rev-parse HEAD)" != "$(git rev-parse FETCH_HEAD^{commit})" ]]; then
+            echo "::error::PR Preview tag must point to the unmerged head of PR $PR_NUMBER."
+            exit 1
+          fi
+
+      - name: "Validate preview version"
+        if: steps.tag.outputs.kind == 'preview'
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+
+          git fetch origin master --tags
+
+          MASTER_VERSION=$(
+            git tag --merged origin/master --sort=-version:refname |
+            grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' |
+            head -n 1 |
+            sed 's/^v//'
+          )
+
+          PREVIEW_VERSION=$(echo "$TAG" | sed -E 's/^v([0-9]+\.[0-9]+\.[0-9]+)a[0-9]+\.post[0-9]+$/\1/')
+
+          echo "Master GA version: $MASTER_VERSION"
+          echo "Preview version:   $PREVIEW_VERSION"
+
+          if [[ -z "$MASTER_VERSION" ]]; then
+            echo "::error::Could not determine the latest GA version on master."
+            exit 1
+          fi
+
+          if [[ "$PREVIEW_VERSION" != "$MASTER_VERSION" ]]; then
+            echo "::error::PR Preview version $PREVIEW_VERSION does not match current master GA version $MASTER_VERSION."
+            exit 1
+          fi
+
+          echo "PR Preview version matches current master GA version: $MASTER_VERSION"
+
+      - name: "Record release source"
+        id: source
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: "Set up uv"
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          python-version: "3.14"
+
+      - name: "Build package"
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.tag.outputs.version }}
+        run: uv build
+
+      - name: "Record distribution hashes"
+        run: |
+          echo "Source commit: ${{ steps.source.outputs.sha }}" >> "$GITHUB_STEP_SUMMARY"
+          sha256sum dist/*.whl dist/*.tar.gz >> "$GITHUB_STEP_SUMMARY"
+
+      - name: "Upload release distributions"
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: release-dist
+          path: |
+            dist/*.whl
+            dist/*.tar.gz
+          if-no-files-found: error
+
+  # See https://docs.astral.sh/uv/guides/integration/github/#publishing-to-pypi
+  # Only this job can obtain a publishing identity; do not check out or build here.
+  publish:
+    name: "Attest and publish to PyPI"
+    runs-on: ubuntu-latest
+    needs: [build-release]
+    if: >
+      (github.event_name == 'push' || github.event_name == 'workflow_dispatch') &&
+      startsWith(github.ref, 'refs/tags/v') &&
+      needs.build-release.result == 'success'
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+    concurrency:
+      group: pypi-${{ github.ref }}
+      cancel-in-progress: false
+    steps:
+      - name: "Download release distributions"
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: release-dist
+          path: dist
+
+      - name: "Check release filenames"
+        shell: python
+        run: |
+          import os
+          import re
+          from pathlib import Path
+
+          match = re.fullmatch(r"v\d+\.\d+\.\d+(?:b\d+|rc\d+|\.dev\d+|a\d+\.post\d+)?", os.environ["GITHUB_REF_NAME"])
+          if not match:
+              raise SystemExit("Invalid release tag")
+          version = match.group()[1:]
+          expected = {f"artesian_sdk-{version}-py3-none-any.whl", f"artesian_sdk-{version}.tar.gz"}
+          if {path.name for path in Path("dist").iterdir()} != expected:
+              raise SystemExit("Release distributions do not match the tag")
+
+      - name: "Set up pinned uv"
+        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        with:
+          version: "0.12.23"
+          enable-cache: false
+
+      - name: "Generate PEP 740 publish attestations"
+        uses: astral-sh/attest-action@f589a42a7efb6fe400b4f400de60b4bc90390027 # v0.0.6
+        with:
+          paths: |
+            dist/*.whl
+            dist/*.tar.gz
+
+      - name: "Publish with required Trusted Publishing"
+        run: uv publish --no-config --trusted-publishing always --publish-url https://upload.pypi.org/legacy/

artesian_sdk-5.0.0.dev2/.github/workflows/validate_tag.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -ne 2 ]]; then
+  echo "::error::Usage: $0 <tag> <ga|beta|dev|rc|preview>"
+  exit 2
+fi
+
+TAG="$1"
+TYPE="$2"
+
+case "$TYPE" in
+  ga)
+    PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$'
+    EXPECTED='vX.Y.Z'
+    ;;
+
+  beta)
+    PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)b(0|[1-9][0-9]*)$'
+    EXPECTED='vX.Y.ZbN'
+    ;;
+
+  dev)
+    PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.dev(0|[1-9][0-9]*)$'
+    EXPECTED='vX.Y.Z.devN'
+    ;;
+
+  rc)
+    PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)rc(0|[1-9][0-9]*)$'
+    EXPECTED='vX.Y.ZrcN'
+    ;;
+
+  preview)
+    PATTERN='^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)a(0|[1-9][0-9]*)\.post(0|[1-9][0-9]*)$'
+    EXPECTED='vX.Y.Za{PR_NUMBER}.post{ITERATION}'
+    ;;
+
+  *)
+    echo "::error::Unknown tag type: $TYPE"
+    exit 1
+    ;;
+esac
+
+if [[ ! "$TAG" =~ $PATTERN ]]; then
+  echo "::error::Invalid $TYPE release tag: $TAG"
+  echo "Expected format: $EXPECTED"
+  exit 1
+fi
+
+if [[ "${GITHUB_REF:-}" == refs/tags/* ]]; then
+  git fetch --no-tags origin "$GITHUB_REF"
+  if [[ "$(git rev-parse FETCH_HEAD^{commit})" != "$(git rev-parse HEAD)" ]]; then
+    echo "::error::Release tag no longer points to the checked-out commit."
+    exit 1
+  fi
+fi
+
+echo "Valid $TYPE release tag: $TAG"

{artesian_sdk-4.4.0b1 → artesian_sdk-5.0.0.dev2}/.gitignore

@@ -47,6 +47,8 @@ coverage.xml
 *.cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
+src/Artesian/_version.py
 
 # Translations
 *.mo

artesian_sdk-5.0.0.dev2/.vscode/extensions.json

@@ -0,0 +1,9 @@
+{
+    "recommendations": [
+        "charliermarsh.ruff",
+        "github.vscode-github-actions",
+        "meta.pyrefly",
+        "ms-python.python",
+        "ms-python.debugpy"
+    ]
+}

{artesian_sdk-4.4.0b1 → artesian_sdk-5.0.0.dev2}/.vscode/launch.json

@@ -2,7 +2,7 @@
     "configurations": [
         {
             "name": "Python: Current File",
-            "type": "python",
+            "type": "debugpy",
             "request": "launch",
             "program": "${file}",
             "console": "integratedTerminal",
@@ -11,7 +11,7 @@
         },
         {
             "name": "Python: Debug Tests",
-            "type": "python",
+            "type": "debugpy",
             "request": "launch",
             "program": "${file}",
             "purpose": ["debug-test"],

artesian_sdk-5.0.0.dev2/.vscode/settings.json

@@ -0,0 +1,21 @@
+{
+  "python.testing.pytestEnabled": true,
+  "python.testing.unittestEnabled": false,
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv",
+  "python.languageServer": "None",
+  "pyrefly.pyreflyExecutable": "from-environment",
+  "python.pyrefly.diagnosticMode": "workspace",
+  "python.analysis.inlayHints": {
+    "callArgumentNames": "all",
+    "functionReturnTypes": true,
+    "variableTypes": true
+  },
+  "ruff.importStrategy": "fromEnvironment",
+  "editor.fontSize": 16,
+  "editor.formatOnPaste": true,
+  "editor.formatOnSave": true,
+  "[python]": {
+    "editor.defaultFormatter": "charliermarsh.ruff",
+    "editor.inlayHints.enabled": "on"
+  }
+}

artesian_sdk-5.0.0.dev2/CONTRIBUTING.md

@@ -0,0 +1,126 @@
+# How to Contribute
+
+## 1. Set up the environment
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) using the
+version in `[tool.uv].required-version` in `pyproject.toml`, then:
+
+```sh
+uv sync --locked --python 3.14
+```
+
+This creates `.venv` and installs the SDK, test dependencies, Ruff, and Pyrefly
+from `uv.lock`. Select `.venv` as the Python interpreter in VS Code and
+install the recommended extensions. Use Ruff for linting and formatting and
+Pyrefly for type checking.
+The [Pyrefly VS Code extension](https://pyrefly.org/en/docs/IDE/#vscode-extension-settings)
+uses the locked environment binary, workspace diagnostics, and inlay hints for
+argument names, inferred return types, and variable types.
+
+Python 3.11 is the minimum supported **package** version. CI tests and lints
+3.11–3.14 on Linux, Windows, and macOS; development defaults to 3.14.
+Development tools are defined only in the `dev` and `test`
+dependency groups and installed from `uv.lock`.
+
+## 2. Run checks
+
+```sh
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked pyrefly check
+uv run --locked pytest
+uv build
+```
+
+Tests use mocked HTTP responses; no live tenant or API key is needed. Pytest
+discovers `Test*.py` files and writes JUnit XML, terminal coverage, `coverage.xml`
+(Cobertura), and `htmlcov/`. Branch coverage is enabled; generated version code
+is excluded.
+
+To check compatibility on an older supported interpreter (including polyfills
+and syntax/type compatibility), switch interpreters and run the same checks as CI:
+
+```sh
+uv sync --locked --python 3.11
+uv run --no-sync ruff check --target-version py311 .
+uv run --no-sync ruff format --check --target-version py311 .
+uv run --no-sync pyrefly check --python-version 3.11
+uv run --no-sync pytest
+```
+
+Repeat with 3.12 and 3.13 (and matching Ruff/Pyrefly flags); don't assume that
+passing checks on 3.14 guarantees compatibility with earlier supported versions.
+Run `uv sync --locked --python 3.14` to restore the development environment.
+To update dependencies intentionally, use `uv lock --upgrade` (or
+`uv lock --upgrade-package NAME`) and commit the resulting lockfile with any
+`pyproject.toml` changes. Tool upgrades must also update their pinned constraints.
+
+## 3. Formatting and typing
+
+Use Ruff's format-on-save integration or `uv run ruff format PATH` for edited
+Python files. CI enforces formatting and linting for SDK source and tests;
+samples remain excluded. Explicit `Any` is limited to the JSON wire-schema
+compiler's runtime annotations and the test decorators' dynamic unittest instances.
+
+`uv run --locked pyrefly check` checks the SDK and tests on the development Python
+version without a diagnostic baseline. CI also checks each supported version.
+Keep annotations accurate without
+changing public method names, parameters, or runtime behavior.
+Use `TypeVar` and `Generic[T]` for generic classes until the minimum supported
+Python is 3.12; PEP 695's `class Name[T]` syntax cannot be parsed by Python 3.11.
+DTOs use PEP 604 `T | None` annotations; the msgspec wire-schema compiler
+resolves them on every supported Python version.
+Unknown responses use `object` rather than `Any`, and nullable service results
+include `None`. Preserve public import paths and wire formats when
+changing internal typing.
+
+## 3.1 JSON wire format
+
+`Artesian._ClientsExecutor.ArtesianJsonSerializer` maps DTO dataclasses to the
+Artesian JSON wire format with msgspec: PascalCase keys, omitted `None` fields,
+enums by name, and RFC 3339 datetimes (naive stays naive, UTC ends in `Z`,
+zero microseconds are omitted). A `dict` field is sent as a JSON object unless
+it is declared with `keyValueArrayField()`, which sends it (and every dict
+nested in it) as `[{"Key": k, "Value": v}]`. Decoding into any `dict` accepts
+both shapes. `benchmark/bench_serde.py` measures large payloads; see
+`benchmark/README.md`.
+
+## 4. CI and coverage
+
+The OS/Python matrix builds the package and runs Ruff, Pyrefly, and pytest for
+every event. The single **Checks** job is the required PR check: it combines
+coverage data, publishes test results, HTML/XML artifacts and a job summary,
+and fails if the matrix or reporting fails. Native GitHub coverage uses a
+job-scoped `code-quality: write` permission. PR checks run on GitHub's merge
+commit; pushes to `master` establish the comparison baseline. Fork PRs still
+run tests and produce coverage artifacts/summaries, but skip uploads
+requiring write access. Preview tags use the same matrix and report their
+tagged commit.
+
+## 5. Release tags
+
+Use a `v` prefix and canonical, unpadded numeric components. The package
+version on PyPI is the tag without `v`; no version remapping is performed.
+
+- **Stable:** `vX.Y.Z` (for example, `v4.3.0`). The tagged commit must be
+  contained in `master`.
+- **Development and release candidate:** `vX.Y.Z.devN` and `vX.Y.ZrcN`
+  (for example, `v5.0.0.dev1` and `v5.0.0rc2`). The tagged commit must be
+  contained in `master`. Standalone alpha tags such as `v5.0.0a1` are not
+  accepted.
+- **Beta:** `vX.Y.ZbN` (for example, `v4.3.0b1` or `v5.0.0b1`). The tagged
+  commit must be contained in `develop-beta`. Compared with the latest stable
+  tag on `master`, the base version must be either the next minor
+  (`X.(Y+1).0`) or the next major (`(X+1).0.0`).
+- **PR preview:** `vX.Y.ZaPR.postITER` (for example, `v4.3.0a69.post2`).
+  `X.Y.Z` must match the latest stable tag on `master`; `PR` is the pull
+  request number and `ITER` is the preview iteration. The tag must point
+  to that PR's current, unmerged head commit, which must contain current
+  `master`—not GitHub's synthetic PR merge commit.
+
+Only a pushed release tag or a manual workflow dispatch **on a tag ref** can
+build a release and publish, after the matrix and **Checks** job pass. The
+release build verifies that the remote tag still points at the checked-out
+commit. PRs and branch dispatches cannot publish. The protected publisher
+checks that the wheel and sdist filenames match the release tag before upload;
+review the build source SHA and distribution hashes before approving it.