From 16847a535b7069390b2fbaecacfc4d9d06d954f9 Mon Sep 17 00:00:00 2001 From: CometAPI Date: Tue, 28 Jul 2026 20:50:02 +0800 Subject: [PATCH] docs: record stable release evidence --- AGENTS.md | 39 ++++++++++++++++++++++---------- ARCHITECTURE.md | 8 +++++++ CHANGELOG.md | 5 +++++ README.md | 10 ++++----- RELEASING.md | 38 +++++++++++++++++++++++++++---- ROADMAP.md | 59 +++++++++++++++++++++++++++++++++---------------- 6 files changed, 119 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 48b6b5f..806d9c3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,20 +48,33 @@ proves only its own evidence layer. Never invent or mock missing evidence. Never reset, rebase, discard work, force-update refs, delete or recreate an existing `dev`, or push `dev` to recover. Report the exact state instead. -## Current milestone: Registry Alpha +## Current milestone: Stable 0.1 -Registry Alpha is complete: `cometapi==0.1.0a1` is publicly available and its -release and registry trust chain has been verified. +Stable 0.1 is complete: `cometapi==0.1.0` is publicly available and its release +and registry trust chain has been verified. Do not begin 0.2 provider adapters +without a separate maintainer request that authorizes that milestone. Private Remote Validation, the sanitized first history, private initialization, -pre-visibility closeout, public visibility configuration, Public Preview, and -the first Registry Alpha release are completed historical steps and must not be -repeated. The canonical repository is public with protected branch and -version-tag rules, Private Vulnerability Reporting, immutable releases, +pre-visibility closeout, public visibility configuration, Public Preview, +Registry Alpha, and the first stable release are completed historical steps and +must not be repeated. The canonical repository is public with protected branch +and version-tag rules, Private Vulnerability Reporting, immutable releases, protected environments, public default-branch CI, and protected release and registry evidence. -The accepted release evidence is: +The accepted stable release evidence is: + +| Field | Value | +| --- | --- | +| Release commit and tag target | `6f42981edcc6c252f8db997606671c3da84d1dd8` | +| Release tag | `v0.1.0` | +| GitHub release | `https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0` | +| Release workflow | `https://github.com/cometapi-dev/cometapi-python/actions/runs/30359383715` | +| PyPI release | `https://pypi.org/project/cometapi/0.1.0/` | +| Wheel SHA256 | `8eae758688bb6c98274e48d8d81f882eeae760f69cfd2f5e125004881d60e90f` | +| Source SHA256 | `e9308b44f6091200b5121e24d1a0e1b9ea3e6bcccc109d6de87554b1ab2a8bca` | + +The accepted Registry Alpha evidence is: | Field | Value | | --- | --- | @@ -88,7 +101,7 @@ The accepted identity is: | Support and conduct | `support@cometapi.com` | | Security | `https://github.com/cometapi-dev/cometapi-python/security/advisories/new` | -Post-alpha invariants: +Post-stable invariants: 1. Treat the dependency dispositions recorded in `ROADMAP.md` as authoritative for the listed pull requests. Process newly opened dependency pull requests @@ -101,14 +114,16 @@ Post-alpha invariants: bridge was used once to generate the stable release PR and must remain absent after its human finalization. Keep `RELEASE_RECOVERY_TAG` and `RELEASE_RECOVERY_SHA` absent outside an explicitly authorized recovery of - that exact existing immutable release identity. + that exact existing immutable release identity, and delete them as soon as + recovery identity verification succeeds or the run stops. 4. Treat the recorded public rules, security reporting, immutable releases, and protected environments as readiness invariants. Any drift invalidates the readiness claim until it is explicitly authorized, restored, and verified. 5. Keep the `pypi` environment approval assigned to the current release approver with self-review allowed; the reviewer is GitHub configuration and must not be hardcoded in repository files. -6. Treat the recovery tag, GitHub release, and PyPI distributions as immutable. +6. Treat every recorded release tag, GitHub release, and PyPI distribution as + immutable. Any later live request, tag, release, Trusted Publisher change, publication, or other registry mutation requires separate explicit maintainer authorization. @@ -139,7 +154,7 @@ Post-alpha invariants: ## Product contract -The PyPI package name is `cometapi`. Version `0.1.0a1` exports only the public +The PyPI package name is `cometapi`. Version `0.1.0` exports only the public clients `CometAPI` and `AsyncCometAPI`; `CometClient` and `AsyncCometClient` must not exist as aliases. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index efc0e31..adbe842 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -128,6 +128,14 @@ source distribution matched the retained pre-publication digests, Trusted Publisher provenance was verified, and the clean registry install/import/mocked smoke passed. +The same trust chain executed successfully for stable `0.1.0` in +[release workflow run 30359383715](https://github.com/cometapi-dev/cometapi-python/actions/runs/30359383715). +The immutable `v0.1.0` tag resolves to release commit +`6f42981edcc6c252f8db997606671c3da84d1dd8`; the protected live suite, direct +top-level OIDC publication, public digest and provenance comparison, and clean +registry install all passed. The selector-descendant conditions were therefore +verified in GitHub's hosted scheduler, not only by local static checks. + The scheduled/manual default-branch smoke is an operational canary only; it does not prove the release commit. `COMETAPI_KEY` is exposed only to the protected exact-release live job. OIDC permission is exposed only to the diff --git a/CHANGELOG.md b/CHANGELOG.md index f89ef07..42ba364 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,11 @@ automation. release chain after a successful selector, while continuing to reject cancellation, reruns, and every non-successful direct dependency. +### Documentation + +- Record completed stable publication, provenance, digest, and clean-install + evidence for `cometapi==0.1.0`. + ## [0.1.0] - 2026-07-28 ### Features diff --git a/README.md b/README.md index f051db3..b23e0df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # CometAPI Python SDK -> **Stable release:** `0.1.0` is approved for PyPI publication. +> **Stable release:** `0.1.0` is approved for PyPI publication and is available +> from PyPI. `cometapi` is a thin Python adapter over the official OpenAI SDK for the OpenAI-compatible CometAPI endpoint. It changes the default API key and base @@ -29,16 +30,15 @@ Project links: [CometAPI](https://www.cometapi.com), ## Installation -After the protected publication workflow and public-registry verification -succeed, install the stable release from PyPI with: +Install the independently verified stable release from PyPI with: ```bash python -m pip install 'cometapi==0.1.0' ``` -After those gates succeed, the immutable +The immutable [GitHub release](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0) -and exact [PyPI release](https://pypi.org/project/cometapi/0.1.0/) for the +and exact [PyPI release](https://pypi.org/project/cometapi/0.1.0/) record the published artifact. ## Authentication and configuration diff --git a/RELEASING.md b/RELEASING.md index 3d35302..983ca41 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -95,7 +95,7 @@ uv run python scripts/check_repository_independence.py uv run python scripts/run_actionlint.py ``` -Build output must contain exactly the intended `0.1.0a1` wheel and source +Build output must contain exactly the current project version's wheel and source distribution. Do not use an older artifact already present in `dist/`. Each exact artifact must be installed independently outside the source tree; the check must assert installed metadata, public exports, absence of legacy aliases, @@ -362,7 +362,8 @@ gh workflow run publish.yml --ref main \ The run must rebuild and verify the exact tag, pass the credential preflight and bounded four-request live suite, wait for protected `pypi` approval, publish by OIDC, verify provenance and public digests, and pass the registry clean-install -smoke. Delete the gate immediately after the run succeeds or stops: +smoke. Delete the gate as soon as `verify-recovery` succeeds; if verification +never succeeds, delete it immediately when the run stops: ```bash gh variable delete RELEASE_RECOVERY_TAG @@ -393,6 +394,35 @@ plain downstream job conditions. Build, live smoke, publication, and registry verification were all skipped while the overall workflow incorrectly reported success. No live request or PyPI upload occurred, and `cometapi==0.1.0` remained absent. The permanent correction explicitly evaluates every selector descendant -and requires all of its direct dependencies to succeed. Do not dispatch another -recovery until that fix reaches `main` and a new recovery is explicitly +and requires all of its direct dependencies to succeed. A further recovery +remained blocked until that fix reached `main` and a new recovery was explicitly authorized. + +### Completed stable release evidence + +- The immutable non-draft [GitHub release](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.0) + and lightweight tag `v0.1.0` resolve to release commit + `6f42981edcc6c252f8db997606671c3da84d1dd8` on protected `main`. +- Selector-descendant fix [PR #23](https://github.com/cometapi-dev/cometapi-python/pull/23) + passed [pull-request CI run 30358662050](https://github.com/cometapi-dev/cometapi-python/actions/runs/30358662050), + squash-merged as `9cd60419130533d6920083e2f4bf295a3b5a4fd7`, and passed + [default-branch CI run 30358990834](https://github.com/cometapi-dev/cometapi-python/actions/runs/30358990834). +- Fresh first-attempt + [recovery run 30359383715](https://github.com/cometapi-dev/cometapi-python/actions/runs/30359383715) + passed immutable identity verification, the shared selector, an exact rebuild, + the bounded four-request live suite, protected `pypi` approval, direct + top-level OIDC publication with attestations, public digest and provenance + verification, and the isolated public-registry install and mocked-call smoke. +- The exact [PyPI release](https://pypi.org/project/cometapi/0.1.0/) has wheel + SHA256 `8eae758688bb6c98274e48d8d81f882eeae760f69cfd2f5e125004881d60e90f` + and source-distribution SHA256 + `e9308b44f6091200b5121e24d1a0e1b9ea3e6bcccc109d6de87554b1ab2a8bca`. + Both public files matched the retained pre-publication digest record and + Trusted Publisher provenance independently verified against this repository. +- The immediate one-attempt local simple-index install encountered PyPI CDN + propagation and still saw only `0.1.0a1`. The documented bounded retry then + installed `cometapi==0.1.0`, verified the public imports and version, and + passed all README mocked-call examples. +- `RELEASE_RECOVERY_TAG` and `RELEASE_RECOVERY_SHA` were deleted immediately + after recovery identity verification. `LIVE_SMOKE_ENABLED=false` is the only + remaining release-related repository variable. diff --git a/ROADMAP.md b/ROADMAP.md index a86f21e..41d1402 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,10 +1,10 @@ # CometAPI Python SDK Roadmap -Status: `0.1.0a1` released; `0.1.0` recovery in progress +Status: `0.1.0` stable released Last updated: 2026-07-28 Repository contract: this roadmap is self-contained. -Current gate: land and remotely verify the selector-descendant control-flow -fix, then complete a newly authorized `0.1.0` recovery. +Current gate: maintain the verified stable 0.1 surface. Begin 0.2 only after a +separate maintainer request authorizes its provider schemas and live contracts. ## Product target @@ -12,12 +12,13 @@ The SDK provides the shortest reliable path from an OpenAI Python integration to CometAPI while preserving official request, response, error, retry, timeout, sync, async, and streaming behavior. -Private Remote Validation, Public Preview, and the functional `0.1.0a1` -Registry Alpha are complete for the sanitized public repository. Protected -repository configuration, public default-branch CI, exact-release live smoke, -PyPI OIDC publication, provenance, digest comparison, and public-registry smoke -provide separate evidence layers. Support and release claims remain limited to -the evidence defined in this roadmap and `COMPATIBILITY.md`. +Private Remote Validation, Public Preview, the functional `0.1.0a1` Registry +Alpha, and stable `0.1.0` are complete for the sanitized public repository. +Protected repository configuration, public default-branch CI, exact-release +live smoke, PyPI OIDC publication, provenance, digest comparison, and +public-registry smoke provide separate evidence layers. Support and release +claims remain limited to the evidence defined in this roadmap and +`COMPATIBILITY.md`. ## Milestones @@ -27,7 +28,7 @@ the evidence defined in this roadmap and `COMPATIBILITY.md`. | Private Remote Validation | Complete | The sanitized private repository passes real credential-free default-branch CI; public-only controls and live tests remain disabled. | | Public Preview | Complete | The public repository has blocking CI, repository rules, security reporting, protected environments, immutable releases, and authorized live-smoke evidence. | | `0.1.0a1` Registry Alpha | Complete | Early adopters can install the functional prerelease from PyPI; every release and registry gate passed. | -| `0.1.0` stable | Recovery in progress | Complete runtime, release-PR, example, provenance, and registry gates pass. | +| `0.1.0` stable | Complete | Complete runtime, release-PR, example, provenance, and registry gates passed. | | `0.2.0` provider-native text | Planned | Optional official Anthropic and Gemini adapters. | | `0.3.0` CometAPI resources | Planned | First schema-backed typed CometAPI-specific resource. | | Media and task APIs | Planned | Coherent task lifecycle precedes individual media helpers. | @@ -456,12 +457,12 @@ the attestation certificate's Build Config URI named expected `publish.yml`. This is a platform constraint: reusable workflows are [unsupported by the PyPA publisher action](https://github.com/pypa/gh-action-pypi-publish/issues/166), and [Warehouse requires the attestation identity to match the publisher](https://github.com/pypi/warehouse/issues/19814). -The permanent correction consolidates release creation, recovery, selection, -build, protected live smoke, direct PyPI publication, and registry verification -in the single top-level `publish.yml` identity. It keeps attestations and the -existing Trusted Publisher intact. Stable remains unreleased until this change -passes pull-request CI, reaches `main`, and a newly authorized recovery passes -OIDC, provenance, and registry gates. +The first permanent correction consolidated release creation, recovery, +selection, build, protected live smoke, direct PyPI publication, and registry +verification in the single top-level `publish.yml` identity. It kept +attestations and the existing Trusted Publisher intact and reached `main` as +`ec420af2966ef683660b58acff8d125e916fc623` through +[PR #22](https://github.com/cometapi-dev/cometapi-python/pull/22). [Recovery run 30357111315](https://github.com/cometapi-dev/cometapi-python/actions/runs/30357111315) verified the exact immutable release and passed the shared selector from the @@ -472,8 +473,27 @@ the overall run incorrectly reported success. No live request or registry side effect occurred, and PyPI still returned 404 for `cometapi==0.1.0`. The permanent control-flow fix makes every selector descendant explicitly evaluate skipped ancestry while rejecting cancellation and reruns and requiring every -direct dependency to succeed. Another recovery remains blocked until that fix -passes review and reaches `main`, followed by fresh explicit authorization. +direct dependency to succeed. + +[PR #23](https://github.com/cometapi-dev/cometapi-python/pull/23) pinned those +conditions in the semantic checker and mutation tests, passed +[pull-request CI run 30358662050](https://github.com/cometapi-dev/cometapi-python/actions/runs/30358662050), +squash-merged as `9cd60419130533d6920083e2f4bf295a3b5a4fd7`, and passed +[default-branch CI run 30358990834](https://github.com/cometapi-dev/cometapi-python/actions/runs/30358990834). +Fresh first-attempt +[recovery run 30359383715](https://github.com/cometapi-dev/cometapi-python/actions/runs/30359383715) +then passed the selector, exact artifact rebuild, bounded four-request live +suite, protected `pypi` approval, direct OIDC publication with attestations, +public digest and provenance checks, and the isolated PyPI install and mocked +smoke. The exact [PyPI release](https://pypi.org/project/cometapi/0.1.0/) is +public with wheel SHA256 +`8eae758688bb6c98274e48d8d81f882eeae760f69cfd2f5e125004881d60e90f` +and source-distribution SHA256 +`e9308b44f6091200b5121e24d1a0e1b9ea3e6bcccc109d6de87554b1ab2a8bca`. +Both files matched retained pre-publication evidence and independently verified +Trusted Publisher provenance. Recovery variables were removed immediately +after identity verification; `LIVE_SMOKE_ENABLED=false` is the only remaining +release-related repository variable. ## `0.2.0`: Provider-native text adapters @@ -526,7 +546,8 @@ must resolve an unset or empty `COMETAPI_LIVE_MODEL` to `gpt-5.4` rather than attempt a request with an empty model. Immutable-release recovery additionally requires `RELEASE_RECOVERY_TAG` and `RELEASE_RECOVERY_SHA` to equal the exact dispatch inputs; keep both variables absent except for one explicitly authorized -identity and delete them immediately after success or failure. Recovery and +identity and delete them immediately after recovery identity verification or a +stopped run. Recovery and publication jobs reject rerun attempts. Every job downstream of the mutually exclusive selector must explicitly evaluate skipped ancestry, reject cancellation, and require every direct dependency's result to equal `success`.