sweatstack 0.98.0__tar.gz → 0.99.0__tar.gz

{sweatstack-0.98.0 → sweatstack-0.99.0}/AGENTS.md

@@ -121,6 +121,9 @@ it automatically.
 
 ## Hard rules
 
+- **Work on `main`, never on a branch.** Every commit goes straight onto `main`; don't create
+  branches in this repository. Work that must wait for a server release stays uncommitted or
+  unpushed, or is committed without being published, rather than parked on a branch.
 - **`uv`, never `pip`.** Every command goes through `uv run` / `uv add`.
 - **`make check` before every commit.** Format, lint, types and tests; `make
   publish` runs it too. Don't silence a finding without a comment saying why.
@@ -137,9 +140,11 @@ it automatically.
 - **Enum-typed params accept `Enum | str`** and route through
   `_enums_to_strings`. Don't introduce strict-enum-only parameters.
 - **Open enums stay open.** When the server documents an enum as an open
-  set (metrics, scopes, daily measures, sources, status codes, capabilities),
+  set (metrics, scopes, daily measures, status codes, capabilities),
   register it with `_open_enum(...)` in `schemas.py` so unknown values
-  parse as pseudo-members. Leave closed sets strict.
+  parse as pseudo-members. Leave closed sets strict. `WriterKind` is closed
+  by the server's contract: a new writer is a breaking release, so keep it
+  strict and let the parse fail.
 - **Never retry a request the server can't safely repeat.** `_transport.RETRYABLE_METHODS`
   is `GET`, `PUT` and `DELETE`; a `POST` is sent once (no idempotency keys). Don't add
   per-method retry logic: everything goes through `_request`.

{sweatstack-0.98.0 → sweatstack-0.99.0}/CHANGELOG.md

@@ -11,6 +11,95 @@ for a coding agent, are in `UPGRADING.md` next to this file and at
 https://docs.sweatstack.no/learn/python/upgrading/.
 
 
+## [0.99.0] - 2026-11-09
+
+Records say who wrote them and which platform their data came from, as two separate answers.
+Breaking: `DailyResponse.source`, `SourceResponse.origin` and `DailySource` are gone; see
+**Upgrading** below, or hand the migration prompt to your coding agent.
+
+### Changed
+
+- Dailies, uploaded sources, markers and max efforts carry `writer` (`WriterKind`: `athlete`,
+  `application` or `sweatstack`), `application_id` (the app, when the writer is an app) and
+  `platform` (where the data came from: `"garmin_connect"`, `"strava"`, ..., or `None`). They
+  replace `DailyResponse.source` and `SourceResponse.origin`, which answered both at once. On a
+  daily, all three are `None` on an estimated or missing day.
+- The frames from `dailies.list()` have `writer`, `application_id` and `platform` columns instead
+  of `source`. In pandas, `writer` holds `WriterKind` members, as every enum column does; in
+  Polars and Arrow it holds strings.
+- `DailySource` is gone, and so is `SourceOrigin` from `sweatstack.openapi_schemas`.
+  `WriterKind` is a closed set: a value outside the three is an error, not a pseudo-member.
+
+### Added
+
+- `dailies.set()` and `activities.upload()` take `platform=` to say where the data came from.
+  SweatStack accepts it with a token from `authenticate()` or one issued to your app, and answers
+  `SweatStackBadRequestError` for a personal API key or a malformed name. It stores the canonical
+  spelling: `"garmin"` reads back as `"garmin_connect"`. One `platform` applies to every file in
+  an upload.
+- `activities.upload()` takes `external_id=`: your app's own ID for each file, one per file in
+  order, with a token issued to your app. Uploading again with the same IDs is safe: an unchanged
+  file returns its existing source, and a changed one is processed again under the same source ID,
+  with new activities. The source echoes the ID as `SourceResponse.external_id`.
+
+### Fixed
+
+- The `dailies.list()` docstring said a missing day has `source="missing"`; it has
+  `status="missing"`.
+
+<!-- --8<-- [start:upgrading-0-99] -->
+### Upgrading
+
+**Upgrade on the day SweatStack's API makes this change** (the platform changelog has the date).
+0.99 needs that API, and from that day SDKs before 0.99 behave like this:
+
+- `activities.upload()` raises a pydantic `ValidationError` *after* the server has accepted the
+  files. The files are uploaded, so don't retry the call.
+- `dailies.list()` keeps working, but **Silent:** `source` is `None` on every day.
+
+| 0.98 | 0.99 | Fails how |
+|---|---|---|
+| `daily.source == DailySource.manual` | `daily.writer == WriterKind.athlete` | `AttributeError` on `.source` |
+| `daily.source == DailySource.application` | `daily.writer == WriterKind.application`; `daily.application_id` names the app | `AttributeError` |
+| `daily.source == DailySource.garmin_connect` (or `intervals_icu`, `wahoo`) | `daily.writer == WriterKind.sweatstack and daily.platform == "garmin_connect"`. For "from Garmin, whoever wrote it": `daily.platform == "garmin_connect"` | `AttributeError` |
+| `daily.source is None` (an estimated or missing day) | `daily.writer is None`, or `daily.status != DailyStatus.stored` | `AttributeError` |
+| `source.origin == "manual_upload"` | `source.writer == WriterKind.athlete` | `AttributeError` on `.origin` |
+| `source.origin == "garmin_connect"` (or another sync) | `source.writer == WriterKind.sweatstack and source.platform == "garmin_connect"` | `AttributeError` |
+| `df["source"] == DailySource.manual` on a pandas frame from `dailies.list()` | `df["writer"] == WriterKind.athlete` | `KeyError` |
+| `pl.col("source") == "manual"` on a Polars frame from `dailies.list()` | `pl.col("writer") == "athlete"` | `ColumnNotFoundError` |
+| `.get("source")` on a `model_dump()` or a frame row | `.get("writer")`, `.get("platform")` | **Silent:** returns `None` |
+| `from sweatstack import DailySource` | `from sweatstack import WriterKind` | `ImportError` |
+| `from sweatstack.openapi_schemas import SourceOrigin` | `from sweatstack import WriterKind` | `ImportError` |
+
+**Migration prompt.** Paste this into your coding agent:
+
+```text
+Upgrade this codebase to sweatstack 0.99, which splits "who wrote a record" from "which
+platform its data came from". The upgrade table is the "Upgrading" section of the 0.99.0 entry
+in https://github.com/SweatStack/sweatstack-python/blob/main/CHANGELOG.md (also at
+https://docs.sweatstack.no/learn/python/upgrading/). Read it first.
+
+Find every read of `.source` on a daily, marker or max effort, of `.origin` on an uploaded
+source, every use of DailySource or SourceOrigin, and every "source" column or key on dailies
+data (frames, model_dump(), dicts). For each, decide which question the code asks:
+
+1. Who wrote it (the athlete, an app, or SweatStack's sync)? Use `.writer` and `WriterKind`;
+   `.application_id` names the app.
+2. Where did the data come from (Garmin, Strava, ...)? Use `.platform`, a plain string such as
+   "garmin_connect", or None.
+3. Both, as the old garmin_connect value did? Combine them:
+   writer == WriterKind.sweatstack and platform == "garmin_connect". Ask whether the code
+   really means "from Garmin, whoever wrote it": then platform alone.
+
+In pandas frames compare `writer` with WriterKind members (df["writer"] == WriterKind.athlete);
+comparing with the string "athlete" is always False. In Polars and Arrow, compare with strings.
+Code that checked `source is None` to find estimated or missing days should check
+`status != DailyStatus.stored`. Search for `.get("source")` and "source" in column lists: those
+return None or drop the column without an error. Then run the code and the tests.
+```
+<!-- --8<-- [end:upgrading-0-99] -->
+
+
 ## [0.98.0] - 2026-10-30
 
 ### Added

{sweatstack-0.98.0 → sweatstack-0.99.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sweatstack
-Version: 0.98.0
+Version: 0.99.0
 Summary: The official Python client for SweatStack
 Project-URL: Homepage, https://sweatstack.no
 Project-URL: Documentation, https://docs.sweatstack.no/learn/python/

sweatstack-0.99.0/plans/012_writer_and_platform.md

@@ -0,0 +1,391 @@
+# Plan 012: Who wrote a record, and which platform it came from
+
+## Status
+
+- **READY, 2026-11-09.** Mirrors a server release that is planned but not yet live. Every server
+  fact below was checked against the server's public contract as it will be after that release,
+  not as it is today. Where today's production differs, both are given.
+- **Ships as 0.99.0**, a breaking minor, on the day of the server release and after it. See
+  [Release](#release).
+- **Effort:** under a day, plus a short release-day step.
+- **Progress, 2026-11-09.** Commit 1 is on `main`. Commit 2 is complete on `writer-and-platform`,
+  regenerated from the server's finished code (see [Checked before release](#checked-before-release)).
+  What's left is the release: commit 3 and [Release](#release).
+- **Process:** red-green. Write the tests in [Tests](#tests) first.
+- **The server dropped the upload's `replace` flag** and tells a retry from a correction by the
+  file's bytes (see [Relaying files](#relaying-files)), so S11's first branch applies: there is
+  nothing to mirror.
+
+> **Public repository.** This file is published with the code. It describes the server by its
+> public contract (the OpenAPI document and docs.sweatstack.no) and names no app, no user and
+> nothing learned from server traffic (AGENTS.md, "Public repository").
+
+## Summary
+
+Until now one field answered two questions. `DailyResponse.source` and `SourceResponse.origin`
+said `manual`, `application` or `garmin_connect`, and the last value meant both "SweatStack's sync
+wrote it" and "it came from Garmin". That works until an app relays Garmin data: the writer is then
+the app and the platform is Garmin, and one field cannot hold both.
+
+After the server release, every record a writer creates carries the same three fields:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `writer` | `WriterKind`: `athlete`, `application`, `sweatstack` | Who is accountable for the write. Comes from the token; no request can set it. **A closed set.** |
+| `application_id` | `str \| None` | Which app, when the writer is `application`. |
+| `platform` | `str \| None` | The platform the data came from: `garmin_connect`, `strava`, ... or none. **An open set**: a plain string, stored and echoed in one canonical spelling. |
+
+The five cases this model distinguishes (today's model can express three of them):
+
+| Case | `writer` | `application_id` | `platform` |
+|---|---|---|---|
+| The athlete types a value or uploads a file | `athlete` | `None` | `None` |
+| SweatStack's own Garmin sync | `sweatstack` | `None` | `"garmin_connect"` |
+| An app relays Garmin data | `application` | `"app_123"` | `"garmin_connect"` |
+| An app computes its own value | `application` | `"app_123"` | `None` |
+| The athlete imports a Strava export through this SDK's sign-in | `athlete` | `None` | `"strava"` |
+
+## The server contract this mirrors
+
+The server's next release is breaking. As it will appear in its OpenAPI document:
+
+**Responses.** `DailyResponse`, `SourceResponse`, `MarkerRowResponse` and `MaxEffortRowResponse`
+carry `writer`, `application_id` and `platform`. `source`, `origin` and `provider` disappear from
+them, and `DailySource` and `SourceOrigin` disappear from the document. On `DailyResponse`, `writer`
+is optional and is set only on a stored day. An `estimated` or `missing` day has no writer, so all
+three fields are `null`, just as `source` was. On the other three models, `writer` is required.
+
+**Requests.** These writes take an optional `platform`: the upload form (`POST /activities/upload`),
+`POST /dailies/{measure}` and its `/batch`, `POST /profile/markers` and `POST /profile/max-efforts`.
+Who may send it:
+
+| The client's token | Writer recorded | `platform` |
+|---|---|---|
+| Issued to an app (a client ID of the developer's own) | `application`, with that app's ID | accepted |
+| Issued to one of SweatStack's own clients: this SDK's `authenticate()` sign-in | `athlete` | accepted |
+| A personal API key from SweatStack's settings, or a web session | `athlete` | **`422`**, never ignored |
+
+A platform name must match `^[a-z][a-z0-9_]{0,39}$`, or the server returns a `422` whose message
+states that rule. A known alias resolves to its canonical name, so `"garmin"` is stored and read
+back as `"garmin_connect"`. An unknown name of the right shape is stored as given. The upload
+form's `provider` field goes away with no alias, and `platform` replaces it.
+
+### Relaying files
+
+The upload also takes `external_id`, which production already accepts and the SDK doesn't send
+yet. It is for an app that relays files it received from another platform: the app's own ID for
+each file, one per file in the files' order. It needs a token issued to an app, and any other token
+gets a `400`. The number of IDs must equal the number of files, or the server returns a `422`. The
+source echoes the ID back as `SourceResponse.external_id`.
+
+When a file comes again with an `external_id` the server has seen from that app:
+
+- **Same bytes**: it is a retry. The existing source comes back untouched.
+- **Different bytes**: it is a correction. The server processes the new file under the same source
+  ID. The source's old activities are deleted (each with an `activity_deleted` webhook) and new
+  ones, with new IDs, take their place.
+
+So retrying a lost upload is always safe. Before the release, production keeps the source unless
+the request also sends `replace=true`. The release removes that flag.
+
+### What a writer may replace
+
+**It does not change.** The athlete and an app may replace anything. A sync
+replaces only what a sync wrote. The platform never affects this. So the `dailies.set()` docstring
+"A value you set is never overwritten by an integration import" stays true.
+
+## Where the SDK starts from
+
+The bundled `openapi_schemas.py` is older than today's production as well as the coming release.
+Regenerating from today's production document gives about 180 changed lines that have nothing to
+do with this plan: `DailySource.application`, `SourceOrigin.application`,
+`SourceResponse.application_id`, `external_id` and `provider`, `DailyResponse.application_id`, the
+upload form's `external_id`, `provider` and `replace`, the daily batch models, app-managed users,
+connection declarations, and more. That backlog must not land inside this plan's diff
+(DEVELOPMENT.md, "Regenerating", step 5), so it lands first as its own commit. See
+[Commits](#commits).
+
+Two consequences of starting from an old schema:
+
+- **0.98 never had `SourceResponse.provider` or `DailySource.application` as typed fields.** No SDK
+  user can have code that reads them through the model, so the Upgrading table has no rows for
+  them.
+- **0.98's `DailySource` is an open enum** (`schemas.py`, `_open_enum`). An `application` value in
+  production today parses as a pseudo-member. That registration goes along with the enum.
+
+## Decisions
+
+| | Decision | Why |
+|---|---|---|
+| S1 | **Mirror the three fields as generated. No derived `source`, no shim.** | AGENTS.md: "Don't add compatibility shims". A derived field would keep two vocabularies alive in users' code and in the docs, which is exactly what the server release removes. |
+| S2 | **`WriterKind` is closed: not registered with `_open_enum`.** `DailySource` leaves the open-enum list. | The server documents `WriterKind` as closed. Three principals is a fact of the model, and a fourth would be a breaking release, not a routine addition. AGENTS.md: "Leave closed sets strict." `platform` is a `str` and is open by type, so it needs nothing. |
+| S3 | **`platform=` on the two write methods the SDK has**: `dailies.set(measure, *, date, value, platform=None)` and `activities.upload(files, *, platform=None)`. Keyword-only, wire name, and `None` sends nothing (R8). | They are the SDK's only methods for the writes that take it. The batch, marker and max-effort writes have no SDK method today, and adding them is a separate change (see [Not doing](#not-doing)). |
+| S4 | **The SDK does not validate or normalise a platform name.** It sends the string as given, and the server's `422` is the message. | The server owns the pattern and the alias table, and both will grow. A client-side copy would drift from them, and an SDK that refuses a name the server accepts is worse than no check. |
+| S5 | **On upload, one `platform` per call covers every file.** It is sent once, as a multipart form field next to the files, in the call's single request. | That is the wire shape: one form field per request. Files from different platforms need separate calls, and the docstring says so. |
+| S6 | **Docstrings describe the token, not the `Client` argument.** In this SDK, `api_key=` holds whatever access token the client was given, so "an API key is refused" would mislead. They say instead: accepted with a token from `authenticate()` or one issued to your app, refused with a personal API key from SweatStack's settings. | The outcome depends on where the token came from, and a user knows that, not which argument they passed it through. |
+| S7 | **A `_renames` entry for `DailySource` only, not for `SourceOrigin`.** | `_renames` turns a removed *public* name into an error that names its replacement. `sweatstack.DailySource` was public (exported since 0.98). `SourceOrigin` was never exported, only reachable through `sweatstack.openapi_schemas`, so a hint for `sweatstack.SourceOrigin` would describe a name that never existed. The CHANGELOG covers it. |
+| S8 | **The SDK never retries an upload by itself, even with `external_id`.** The docstring tells the caller that retrying with the same IDs is safe. | AGENTS.md: a `POST` is sent once, with no per-method retry logic. Whether a retry is wanted is the caller's decision. The server's contract makes that decision safe. |
+| S9 | **Nothing is released while the SDK carries a schema production doesn't serve.** (This plan parked the work on a branch; the repository has since ruled that out, AGENTS.md: work stays on `main`, unpublished, until the server is live.) | 0.99's `SourceResponse` requires `writer`, so it cannot parse today's production. A patch release cut from `main` in between would break every upload. |
+| S10 | **`external_id=` on `activities.upload()`: one string or a list, matched to `files` by position.** It goes through `_wire` and is sent as a repeated form field, and only when given. The SDK doesn't check that the counts match: the server's `422` says so (as S4). | R8: a repeatable parameter takes one value or a list under the wire name. A single string for a single file reads naturally: `upload("ride.fit", external_id="12345")`. It ships with `platform=` because a relaying app needs both. |
+| S11 | **`replace` follows whichever contract ships.** If commit 2's regen shows the upload form without `replace` (the expected outcome), there is nothing to mirror. If the form still has it, mirror it: `replace: bool = False`, keyword-only, sent only when `True`. Its docstring says it applies only with `external_id`, and that it deletes the source's activities and creates new ones with new IDs. The [Relaying files](#relaying-files) wording then becomes "a known ID returns the existing source unless `replace=True`". | The SDK mirrors the API (AGENTS.md) and does not redesign it. The client-side burden this flag creates is the server's to remove, and that has been proposed. Hiding a parameter the server still has would make a correction impossible from the SDK. |
+
+## Changes
+
+### Commit 1: regenerate from today's production (lands now, on `main`)
+
+1. `uv run generate-response-models` against a server that serves **today's production document**
+   (DEVELOPMENT.md). Production's document as of 2026-11-09 is version 0.154.2.
+2. Wire-name check: `SWEATSTACK_OPENAPI_JSON=... uv run pytest tests/test_wire_names.py`. Against
+   that document it reports two methods:
+   - `Activities.upload`: `external_id`, `provider`, `replace`. Add
+     `"Activities.upload": {"external_id", "replace", "provider"}` to `NOT_EXPOSED`, with the
+     comment "file relay: mirrored in plan 012, commit 2". The entry is temporary, and commit 2
+     removes it.
+   - `OAuth.authorization_url`: `login_hint`. **Not this plan.** Mirror it in its own small
+     change before or after. It must not ride along here.
+3. `make check`. The existing tests must pass unchanged. If one fails, the backlog contains a
+   breaking change that needs its own CHANGELOG line. Stop and write that line; don't fix the test
+   quietly.
+4. CHANGELOG under `## [Unreleased]`, **Added**: `DailyResponse.application_id` (also a new
+   column of the `dailies.list()` frames, which `tests/test_dailies.py` and `tests/test_output.py`
+   pin), `SourceResponse.application_id` and `SourceResponse.external_id`. That keeps `main`
+   accurate if anything is released before commit 2. Commit 2 folds these lines into its own entry.
+   `provider` and `DailySource.application` get no line: commit 2 removes them.
+
+### Commit 2: writer and platform (branch `writer-and-platform`)
+
+1. **Regenerate** from a local server running the release's code. The expected diff is exactly the
+   contract above:
+   - `WriterKind` (`athlete`, `application`, `sweatstack`) appears. `DailySource` and
+     `SourceOrigin` go.
+   - `DailyResponse` gains `writer: WriterKind | None = None` and
+     `platform: str | None = None` (it already has `application_id`) and loses `source`.
+   - `SourceResponse` gains `writer: WriterKind` (required) and `platform` and loses `origin` and
+     `provider`.
+   - `MarkerRowResponse` and `MaxEffortRowResponse` gain `writer` and `platform` and lose `source`.
+   - The upload form, `DailyCreate`, `DailyBatchCreate`, `MarkerWrite` and `MaxEffortWrite` gain
+     `platform`. The upload form loses `provider`, and (expected, S11) `replace`.
+
+   Anything else in the diff is a server change outside this plan. Commit it separately, as in
+   commit 1.
+2. **Exports.** `schemas.py` and `client.py` (its import and `__all__`) re-export `WriterKind`
+   where they now re-export `DailySource`. Remove `DailySource` from `_open_enum`'s list in
+   `schemas.py`, and change that function's docstring from "sources of a value" to the open sets
+   that remain. Check that nothing re-exports `SourceOrigin` (true on 2026-11-09).
+3. **`_renames.REMOVED_IN`**, under a `# 0.99` comment:
+   `"DailySource": ("0.99", "sweatstack.WriterKind (a record's writer) and its platform field (where the data came from)")`.
+   The hint names `sweatstack.` literally rather than `{c}.`, because `WriterKind` is a
+   module-level name, never `client.WriterKind`. Know the limit: the hint reaches
+   `sweatstack.DailySource`, while `from sweatstack import DailySource` raises Python's plain
+   `ImportError` without it. UPGRADING.md, step 4, already says so, and the Upgrading table has the
+   row.
+4. **`dailies.set(..., platform=None)`.** The body is
+   `{"date": ..., "value": ..., "platform": platform}`, with `"platform"` present only when it is
+   not `None`. Docstring:
+   - `Args: platform:` "Where the value came from, when another platform measured it:
+     `"garmin_connect"`, `"strava"`, ... Leave it out for a value you measured or entered yourself.
+     It is accepted with a token from `authenticate()` (the value's writer is then `athlete`) or one
+     issued to your app (`application`), and refused with a personal API key from SweatStack's
+     settings. The server stores the canonical spelling: `"garmin"` reads back as
+     `"garmin_connect"`."
+   - `Returns:` "The stored value, with its `writer`, `application_id` and `platform`."
+   - `Raises: SweatStackBadRequestError:` "If `platform` is not a platform name (a lower-case
+     letter, then up to 39 lower-case letters, digits or underscores), or the token may not name
+     one."
+   - Keep the `Examples:` block as it is: a plain call is the common case.
+5. **`activities.upload(files, *, platform=None, external_id=None)`**, with
+   `external_id: str | Sequence[str] | None`. Build `data` from the parameters given:
+   `"platform": platform` when it is not `None`, and `"external_id": self._wire(external_id)` when
+   it is not `None`. Send `data=` next to `files=` only when it is non-empty. Docstring:
+   - `platform`: the `dailies.set` wording, plus "One platform per call: it applies to every file;
+     upload files from different platforms in separate calls."
+   - `external_id`: "Your app's own ID for each file, one per file in the same order (a single
+     string for a single file). Needs a token issued to your app. A file sent again with an ID
+     SweatStack has seen from your app returns the existing source if the file is unchanged, so
+     retrying a lost upload is safe. If the file changed, SweatStack processes it again under the
+     same source ID: the old activities are deleted and new ones, with new IDs, take their place."
+   - `Returns:` "One entry per file, each with its `writer`, `platform` and `external_id`."
+   - `Raises: SweatStackBadRequestError:` "If `platform` is not a platform name or the token may
+     not name one, if `external_id` is sent with a token not issued to an app, or if the number of
+     IDs differs from the number of files."
+   - A second `Examples:` snippet for the relaying app:
+     `client.activities.upload(["a.fit", "b.fit"], platform="garmin_connect", external_id=["1001", "1002"])`.
+6. **`tests/test_wire_names.py`**: delete the `NOT_EXPOSED["Activities.upload"]` entry
+   (`{"provider", "replace"}` since `external_id=` landed). Every upload field is now a parameter: `platform` and `external_id`, plus `replace` if
+   S11's fallback applies.
+7. **The release in progress is checkable before it has a version** (`tests/test_renames.py`,
+   `tests/test_changelog.py`). Both tests look for a `## [0.99.0] - <date>` heading, but the entry
+   sits under `## [Unreleased]` until release day. Without this step, `make check` fails on commit 2
+   and on every commit until the release.
+   `test_changelog`'s parser counts `## [Unreleased]` as the next minor release, so its
+   "breaking", its `### Upgrading` and its `upgrading-0-99` markers are held to the same rules
+   before release. `test_renames` reads its entries from that parser instead of keeping its own
+   regex. (Done.)
+8. **Skills.** `skills/sweatstack-python/data-models.md`:
+   - **DailyResponse**: `date`, `value`, `status`, `writer` (`WriterKind`: `athlete`,
+     `application`, `sweatstack`; `None` on an estimated or missing day), `application_id`,
+     `platform` (a string such as `garmin_connect`, or `None`). Markers and max efforts carry the
+     same three fields.
+   - **SourceResponse**: replace `origin` with `writer`, `application_id`, `platform`; add
+     `external_id`.
+
+   In `api.md`, the `upload` and `dailies.set` lines show `platform="strava"` and
+   `platform="garmin_connect"` in a trailing comment, with a single line saying who may send it.
+   A line for the relay: `upload(files, platform=..., external_id=[...])`, an app's token, and
+   "retry with the same IDs is safe".
+9. **AGENTS.md**, "Open enums stay open": drop "sources" from the example list, and add "`WriterKind`
+   is closed by the server's contract; keep it strict." The next person to regen should not
+   "fix" it.
+10. **CHANGELOG** under `## [Unreleased]`: the entry in [CHANGELOG entry](#changelog-entry).
+
+Nothing else changes: no client-side derivation of the old `source` (S1), and no validation of the
+name (S4).
+
+## Tests
+
+Red-green: write these first. All offline (AGENTS.md).
+
+**New**
+- `dailies.set(..., platform="garmin_connect")` puts `"platform": "garmin_connect"` in the JSON
+  body. Without `platform=`, the body has no `"platform"` key, not one set to `None`.
+- `activities.upload(fit, platform="strava")` sends `data={"platform": "strava"}` next to the files,
+  in one request for two files. Without `platform=`, it passes no `data`.
+- `activities.upload([a, b], external_id=["1001", "1002"])` sends
+  `data={"external_id": ["1001", "1002"]}` in one request. `upload(a, external_id="1001")` sends
+  `["1001"]`. With both parameters, both keys are present. A mismatched count is sent as given:
+  the SDK doesn't check it (S10).
+- A relayed `SourceResponse` with `writer: "application"`, `application_id: "app_123"`,
+  `platform: "garmin_connect"` and `external_id: "1001"` parses, and `external_id` reads back.
+- Parsing, one row per case in [Summary](#summary): a recorded `DailyResponse` and `SourceResponse`
+  for `athlete`/`None`/`None`, `application`/`"app_123"`/`"garmin_connect"` and
+  `sweatstack`/`None`/`"garmin_connect"`. An estimated and a missing `DailyResponse` parse with
+  `writer`, `application_id` and `platform` all `None`.
+- **`WriterKind` is closed**, parametrised over `DailyResponse`, `SourceResponse`,
+  `MarkerRowResponse` and `MaxEffortRowResponse`: `writer: "coach"` raises `ValidationError`. This
+  replaces `test_source_is_an_open_set` (`tests/test_dailies.py`) and its rows, which carry over.
+- **`platform` is open**: `platform: "a_platform_added_later"` parses as that string on all four
+  models.
+- **Frames**: `dailies.list(output="polars")` and `"pandas"` have the columns `writer`,
+  `application_id` and `platform`, and no `source`. Polars and Arrow hold `writer` as the string
+  `"athlete"`; pandas holds the `WriterKind` member, as for every enum column, so
+  `df["writer"] == "athlete"` is always `False` there. The CHANGELOG and the migration prompt say
+  so. `tests/test_frames.py` already turns a `FrameSchemaWarning` into a failure for every public
+  model, so the regen's new enum is covered.
+- `tests/test_renames.py` picks up the `DailySource` entry by its parametrisation, against the
+  `[Unreleased]` entry (commit 2, step 7).
+
+**Updated**, because they construct or read the removed fields:
+- `tests/test_dailies.py`: imports `DailySource`, builds dailies with `source=`, asserts
+  `source == DailySource.manual` (lines 12–107), and has the open-set test above.
+- `tests/test_frames.py:190`, `tests/test_output.py:295`: `source=` becomes `writer=`.
+- `tests/test_resources.py:114`: the upload fixture's `"origin": "manual_upload"` becomes
+  `"writer": "athlete", "application_id": None, "platform": None`.
+
+**Against the document, by hand.** `tests/test_wire_names.py` with `SWEATSTACK_OPENAPI_JSON`
+pointing at the new document: green except `OAuth.authorization_url`'s `login_hint`, which has its
+own change (commit 1, step 2).
+
+`tests/test_public_hygiene.py` runs in `make check` and covers this plan and the CHANGELOG entry.
+
+## CHANGELOG entry
+
+The entry is in `CHANGELOG.md` under `## [Unreleased]`, renamed to `## [0.99.0] - <date>` on
+release day. It is the only copy: a draft here would drift from it. Two things in it differ from
+this plan's first draft, both found against the generated code:
+
+- **pandas frames hold `WriterKind` members**, Polars and Arrow hold strings. The table has a row
+  for each, and the prompt says which comparison works where.
+- **0.99 against an older server doesn't fail on dailies.** `DailyResponse.writer` is optional, so
+  dailies parse with `writer=None`; only the upload fails. The entry says "0.99 needs that API"
+  and doesn't claim more.
+
+The text names no release date ("the platform changelog has the date"), so there is no
+placeholder to forget. `tests/test_changelog.py` wants every "silent" in the section written as
+`**Silent:**` in bold.
+
+## Checked before release
+
+On 2026-11-09, against the server's finished code, before production served it:
+
+- **The document was rendered in-process** by the server's test image, with throwaway keys (no
+  secrets, no telemetry) and a tmpfs `/data`, under a compose project of its own. The same method
+  on the server's last release produced production's document exactly (deep equality), so the
+  render is a faithful preview.
+- **The regen's diff is the [contract](#the-server-contract-this-mirrors) and nothing else**:
+  `WriterKind` with three members; `DailySource` and `SourceOrigin` gone; the three fields on all
+  four response models (`writer` optional only on `DailyResponse`); `platform` on the upload,
+  `DailyCreate`, `DailyBatchCreate`, `MarkerWrite` and `MaxEffortWrite`; `provider` and `replace`
+  gone from the upload.
+- **The wire-name test** against that document reports only `login_hint` (its own change).
+- **`make check`** is green on the branch.
+- **Release, 2026-11-09.** The server's release has both changes asked after the check (column
+  order, the `external_id` description), and nothing else: the render of its released code
+  regenerates to exactly those two differences (commit 3).
+
+One thing was settled at the server before release: **the column order of a daily**. The server
+first added the three fields through a base class, so they came first, and `dailies.list()` frames
+started `writer, application_id, platform, date, value, status`. The SDK doesn't reorder a model's
+columns (AGENTS.md, "Never add a per-model special case"), so the fix went into the server's model
+(the record's own fields first). Its release has it, and commit 3 pins the order in the tests.
+
+## Commits
+
+| # | Where | What | Done when |
+|---|---|---|---|
+| 1 | `main`, now | Regenerate from today's production, plus the temporary `NOT_EXPOSED` entry for the upload | `make check` green; the wire test reports only `login_hint` |
+| 2 | branch `writer-and-platform` | Everything in [Commit 2](#commit-2-writer-and-platform-branch-writer-and-platform), regenerated from the server's finished code | Done 2026-11-09: `make check` green; the wire test reports only `login_hint` |
+| 3 | the same branch, release day | Regenerate from production (see Release), bump `pyproject.toml` to 0.99.0, rename the heading | The regen shows only the two expected differences (Release, step 2) |
+
+## Release
+
+The server ships first, and the SDK follows the same day.
+
+1. **Wait until the server release is live**: production's `/openapi.json` has `WriterKind` and no
+   `DailySource`. Until then, nothing is released from this branch, and nothing that needs it is
+   released from `main` (S9).
+2. **Regenerate from production** (commit 3). Two differences from commit 2 are expected, both
+   asked of the server after the check: the record's own fields before `writer`, `application_id`
+   and `platform` in the four models, and a corrected description of the upload's `external_id`.
+   With the first, pin the column order in `tests/test_dailies.py` (`DAILY_COLUMNS` becomes a list
+   starting `date, value, status`). Anything else means the server changed after commit 2:
+   reconcile it like a regen diff (DEVELOPMENT.md), and don't release until the branch matches what
+   production serves.
+3. Rebase onto `main`, rename `## [Unreleased]` to `## [0.99.0] - <release date>`, bump the version,
+   then run `make check` and `make publish`.
+4. **Docs**: on the docs site's Upgrading page, add a `## 0.99` section with the
+   `upgrading-0-99` include, above `## 0.94`. The generated reference follows the regen.
+5. Check against production with a token from `authenticate()`:
+   - `client.dailies.list("body_mass", start=..., end=...)` parses, and `writer` is set on the
+     stored days. With `output="polars"`, the columns start `date, value, status`. If they start
+     with `writer`, the server's order fix hasn't shipped: release anyway (nothing breaks), and
+     pin the order in `tests/test_dailies.py` once it does.
+   - `client.dailies.set(..., platform="garmin")` reads back `platform == "garmin_connect"` and
+     `writer == WriterKind.athlete`. Then delete that test value.
+
+## Not doing
+
+- **A derived `source` or `origin`** (S1).
+- **Client-side platform validation, an alias table or a `Platform` enum** (S4). The server owns
+  all three, and `platform` is open.
+- **SDK methods for `POST /dailies/{measure}/batch`, `POST /profile/markers` and
+  `POST /profile/max-efforts`.** They take `platform` too, but the SDK has no methods for them yet.
+  Adding them is an endpoint change with its own plan, named by R1–R8.
+- **Automatic retries of an upload** (S8).
+- **A client-side check that `external_id` and `files` have the same length** (S10). The server's
+  `422` names both counts.
+- **`login_hint` on `oauth.authorization_url()`**: found while regenerating; its own change.
+
+## Maintainer's notes
+
+- **`writer` is a fact about the token, `platform` is a claim.** The SDK sends a platform only when
+  the caller passes one. It never sends a default and never infers one from a file.
+- **If the server ever adds a fourth `WriterKind`, that is a breaking server release, and this
+  SDK's parse will fail on purpose.** Regenerate, add the member to the Upgrading table, and keep
+  the enum closed. Opening it would hide a change in who is accountable for data.
+- **New platforms need no SDK change.** If a regen ever turns `platform` into an enum, the server's
+  contract has changed. Open it with `_open_enum` and ask why.
+- **`external_id` is what makes an upload safe to repeat.** If the server's rule for a known ID
+  ever changes (for example, back to a flag), the docstring's retry sentence is the first thing to
+  check. It is a promise users build retry loops on.
+- **A new write endpoint that takes `platform`** gets the same parameter, docstring wording and
+  tests as `dailies.set()`. Copy them; don't re-derive them.

{sweatstack-0.98.0 → sweatstack-0.99.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sweatstack"
-version = "0.98.0"
+version = "0.99.0"
 description = "The official Python client for SweatStack"
 readme = "README.md"
 license = "MIT"

{sweatstack-0.98.0 → sweatstack-0.99.0}/skills/sweatstack-python/api.md

@@ -21,6 +21,7 @@ client.activities.data("act_123", segmentation_on=None, metrics=None, output=Non
 client.activities.mean_max("act_123", metric="power", durations=None, output=None)  # best average per duration
 client.activities.awd("act_123", metric=None, output=None)  # accumulated work duration
 client.activities.upload(["ride.fit"])                  # list[SourceResponse]; a CSV needs a sport column
+client.activities.upload(["1001.fit"], platform="garmin_connect", external_id=["1001"])  # relay: app token; same IDs again are safe
 client.activities.backfill_status()                      # BackfillStatus
 client.activities.watch_backfill_status(auto_reconnect=False)  # generator of BackfillStatus
 client.activities.app_metadata.set("act_123", data={"k": "v"})  # app token only; replaces the dict
@@ -68,9 +69,14 @@ client.tests.app_metadata.delete("test_123")
 ```python
 client.dailies.list("hrv", start=date(2026, 4, 1), end=date(2026, 5, 1), interpolate=True, output=None)
 client.dailies.set("body_mass", date=date(2026, 5, 1), value=71.4)  # upsert
+client.dailies.set("hrv", date=date(2026, 5, 1), value=62, platform="garmin_connect")  # measured elsewhere
 client.dailies.delete("body_mass", date=date(2026, 5, 1))
 ```
 
+`platform=` on `dailies.set()` and `activities.upload()` names where the data came from. It is
+accepted with a token from `authenticate()` or one issued to your app, and refused
+(`SweatStackBadRequestError`) with a personal API key.
+
 ## profile: the user the client acts as
 
 ```python

{sweatstack-0.98.0 → sweatstack-0.99.0}/skills/sweatstack-python/data-models.md

@@ -48,14 +48,19 @@ taxonomy is preserved (`is_standard` is `False`) instead of failing.
   `end_local`, `results` (`TestResults`: thresholds `lt1`, `lt2`, `vt1`, `vt2`, `mlss`, `fatmax`
   as `Marker`s, plus `vo2max`, `critical_power`, `w_prime`, ...), `tags`, `created_by`;
   `TestDetails` adds the resolved `traces` and overlapping `activities`.
-- **DailyResponse**: `date`, `value`, `status`, `source` (`DailySource`, an open set: `manual`,
-  `garmin_connect`, ...; markers and max efforts carry it too).
+- **DailyResponse**: `date`, `value`, `status`, and on a stored day who wrote it and where it came
+  from: `writer` (`WriterKind`, closed: `athlete`, `application`, `sweatstack`), `application_id`
+  (the app, when the writer is one) and `platform` (an open string such as `garmin_connect`, or
+  `None`). All three are `None` on an estimated or missing day. `SourceResponse`, markers and max
+  efforts carry the same three fields. In a pandas frame `writer` holds `WriterKind` members;
+  in Polars and Arrow, strings.
 - **UserSummary** (`users.list()`): `id`, `first_name`, `last_name`, `display_name`, `scopes`,
   `is_managed`.
 - **UserResponse** (`users.create()`, `retrieve()`, `update()`): `id`, `first_name`,
   `last_name`, `display_name`, `admin`, `is_managed`, `registered_at`.
-- **SourceResponse** (`activities.upload()`): `id`, `type`, `origin`, `filename`, `status`
-  (`processing`, `processed`, `failed`), `error`, `activity_ids`, `created_at`.
+- **SourceResponse** (`activities.upload()`): `id`, `type`, `filename`, `status` (`processing`,
+  `processed`, `failed`), `error`, `activity_ids`, `created_at`, `writer`, `application_id`,
+  `platform`, `external_id` (set on a file an app relayed).
 - **UserInfoResponse** (`oauth.userinfo()`): `sub`, `name`, `given_name`, `family_name`,
   `email`, `registered_at`, `issue`.
 - **AccountStatusResponse** (`profile.status()`, beta): `issue` (`StatusIssueResponse | None`:

{sweatstack-0.98.0 → sweatstack-0.99.0}/src/sweatstack/_renames.py

@@ -11,6 +11,8 @@ used. Entries are permanent; removing one turns a helpful error back into a bare
 from __future__ import annotations
 
 REMOVED_IN = {
+    # 0.99: who wrote a record and where its data came from are two fields (plan 012).
+    "DailySource": ("0.99", "the record's writer field (sweatstack.WriterKind) and platform field"),
     # 0.91: flat methods became resource namespaces (plan 009, M3).
     "get_activities": ("0.91", "{c}.activities.list()"),
     "get_activity": ("0.91", "{c}.activities.retrieve(activity_id)"),

{sweatstack-0.98.0 → sweatstack-0.99.0}/src/sweatstack/client.py

@@ -59,7 +59,6 @@ from .schemas import (
     CapabilityStatus,
     DailyMeasure,
     DailyResponse,
-    DailySource,
     IssueStatus,
     Marker,
     Metric,
@@ -82,6 +81,7 @@ from .schemas import (
     UserInfoResponse,
     UserResponse,
     UserSummary,
+    WriterKind,
 )
 from .utils import decode_jwt_body, make_dataframe_streamlit_compatible
 
@@ -1223,7 +1223,6 @@ __all__ = sorted(
         "CapabilityStatus",
         "DailyMeasure",
         "DailyResponse",
-        "DailySource",
         "IssueStatus",
         "Marker",
         "Metric",
@@ -1246,6 +1245,7 @@ __all__ = sorted(
         "UserInfoResponse",
         "UserResponse",
         "UserSummary",
+        "WriterKind",
         *_SINGLETON_METHODS,
         *RESOURCES,
     ]