From a4f6ac6cb6eda9e3572c0997e721dfdf392b5585 Mon Sep 17 00:00:00 2001 From: TensorNull Date: Tue, 28 Jul 2026 17:47:40 +0800 Subject: [PATCH] docs: record stable 0.1.0 release --- AGENTS.md | 29 ++++++++----- CHANGELOG.md | 5 +++ COMPATIBILITY.md | 27 ++++++++---- README.md | 29 +++++++------ RELEASING.md | 106 +++++++++++++++++++++++++++++++++++++---------- ROADMAP.md | 27 +++++++++--- 6 files changed, 161 insertions(+), 62 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index eb56125..2416c9d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,13 +51,14 @@ repository. merely to complete lifecycle cleanup. Fail closed and report the exact state whenever a required cleanliness, fetch, or fast-forward condition is not met. -## Current Milestone: Stable 0.1.0 +## Current Milestone: Stable 0.1.0 Complete -Private Remote Validation, Public Preview, and Registry Alpha are complete. -The canonical repository is public, and `0.1.0-alpha.3` is available from npm's -`next` channel with OIDC provenance and verified public-install evidence. The -current work promotes the existing 0.1 protocol surface to `0.1.0` on npm's -`latest` channel. Do not begin the 0.2 provider adapters during this milestone. +Private Remote Validation, Public Preview, Registry Alpha, and stable `0.1.0` +are complete. The canonical repository is public, `0.1.0` is available from +npm's `latest` channel, and `0.1.0-alpha.3` remains available from `next`; both +published lines have OIDC provenance and verified public-install evidence. No +later milestone is active. Do not begin the 0.2 provider adapters without an +explicit maintainer request. The accepted identity is: @@ -77,14 +78,20 @@ The unscoped `cometapi` package is the primary Node SDK. `@cometapi` is the standard scope for future official scoped packages; do not introduce new official packages under `@cometapi-dev`. -Stable promotion uses Release Please only for its reviewed version and +Stable promotion used Release Please only for its reviewed version and changelog pull request. Because the pinned Release Please v5 path is vulnerable -to an upstream single-package tagging defect, it must skip GitHub release -creation. A maintainer creates and reviews the immutable `v0.1.0` release -manually against the exact merged release commit. The publish workflow then -performs exact-artifact verification, the bounded live smoke, npm OIDC +to an upstream single-package tagging defect, it skipped GitHub release +creation. A maintainer created and reviewed the immutable `v0.1.0` release +manually against the exact merged release commit, and the publish workflow +completed exact-artifact verification, the bounded live smoke, npm OIDC publication, and registry verification. +Release Please is disabled after its post-merge run generated an unreviewed +`0.2.0` temporary-branch commit and then failed to create a pull request. The +temporary branch is failure evidence only. Do not merge it, use it as a 0.2 +starting point, or re-enable Release Please until a separately authorized task +reviews the post-manual-release and pull-request authorization strategy. + ## Product Contract The npm package name is `cometapi`, the public client is `CometAPI`, and the diff --git a/CHANGELOG.md b/CHANGELOG.md index da6c22a..7bfc912 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,11 @@ follows Keep a Changelog, and versions follow Semantic Versioning. ## [Unreleased] +### Documentation + +- Recorded the verified stable `0.1.0` release evidence and the deferred Release + Please automation follow-up. + ## [0.1.0-alpha.3] - 2026-07-27 ### Fixed diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 10a644d..0084ce3 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -3,8 +3,8 @@ Compatibility document version: 0.1 Package line: `0.1.x` -Stable candidate: `0.1.0`; publication and registry verification remain -separate evidence until the immutable release workflow completes. +Stable release: `0.1.0`; the immutable release workflow and separate +post-publication registry verification completed on 2026-07-28. This matrix defines the contract-tested 0.1 compatibility surface. Inheritance from the official OpenAI client does not by itself establish CometAPI support. @@ -94,10 +94,19 @@ npm run test:compat npm run verify ``` -These are offline or mocked checks. Stable candidate verification also runs the -minimum, locked, and latest-compatible OpenAI 6.x lanes. Live compatibility requires the separately -gated trusted workflow described in [RELEASING.md](./RELEASING.md). A successful -HTTP status alone is transport evidence, not proof that streaming, types, -errors, and cancellation behave correctly. Each authorized live run remains -bounded to exactly three sequential requests, 16 output tokens, a 60-second -per-request timeout, concurrency one, and stop on the first failure. +These are offline or mocked checks. Stable verification also ran the minimum, +locked, and latest-compatible OpenAI 6.x lanes. Live compatibility requires the +separately gated trusted workflow described in [RELEASING.md](./RELEASING.md). +A successful HTTP status alone is transport evidence, not proof that streaming, +types, errors, and cancellation behave correctly. Each authorized live run +remains bounded to exactly three sequential requests, 16 output tokens, a +60-second per-request timeout, concurrency one, and stop on the first failure. + +For stable `0.1.0`, the latest-compatible lane passed in +[CI run 30344290818](https://github.com/cometapi-dev/cometapi-node/actions/runs/30344290818). +The immutable release, bounded live smoke, OIDC publication, registry +signatures and provenance, and public artifact checks passed in +[publish run 30345735681](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345735681). +A separate post-publication registry-tarball check also passed the ESM, +CommonJS, and compatible-OpenAI host fixtures with one effective +`openai@6.47.0` installation and preserved official error identities. diff --git a/README.md b/README.md index 9f8253e..6046287 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,8 @@ The official CometAPI entry point for the OpenAI-compatible API. The SDK keeps the official OpenAI JavaScript request, response, stream, and error types while defaulting the client to CometAPI. -> **Stable 0.1 release candidate:** `0.1.0` is approved for npm publication. +> **Stable 0.1 release:** `0.1.0` is approved for npm publication. Publication +> is complete, and the package is available from npm's default `latest` dist-tag. > The supported API is limited to the contract-tested 0.1 surface documented > here and in [COMPATIBILITY.md](./COMPATIBILITY.md). @@ -37,8 +38,7 @@ files. You are responsible for all usage and charges incurred with your key. ## Installation -Install the stable package from npm's default `latest` dist-tag after the -reviewed release completes: +Install the stable package from npm's default `latest` dist-tag: ```bash npm install cometapi @@ -212,16 +212,19 @@ parent. ## Project status -The repository has completed Public Preview and Registry Alpha. Blocking CI, -protected repository rules, security reporting, protected environments, and -the authorized live smoke have passed. Stable `0.1.0` is the reviewed -publication candidate; Registry Alpha `0.1.0-alpha.3` was published from the -immutable release artifact through GitHub Actions OIDC with provenance, and -independent public-registry ESM, CommonJS, and compatible-OpenAI host installs -passed. The immutable `0.1.0-alpha.2` GitHub release remains as an unpublished -failure record because its guard stopped before invoking npm. Mocked responses, -packed artifacts, GitHub Actions, trusted live tests, and npm publication remain -separate evidence layers and must not be represented as another. +The repository has completed Public Preview, Registry Alpha, and stable 0.1.0. +Blocking CI, protected repository rules, security reporting, protected +environments, and the authorized release-tag live smoke have passed. Stable +`0.1.0` was published from its immutable release artifact through GitHub +Actions OIDC with provenance, and a separate post-publication check passed the +ESM, CommonJS, and compatible-OpenAI host fixtures against the registry tarball. +Registry Alpha `0.1.0-alpha.3` remains available from `next`. The immutable +`0.1.0-alpha.2` GitHub release remains as an unpublished failure record because +its guard stopped before invoking npm. Mocked responses, packed artifacts, +GitHub Actions, trusted live tests, and npm publication remain separate evidence +layers and must not be represented as another. Because published npm artifacts +are immutable, the `0.1.0` tarball retains its candidate-era README; this +post-release status update first ships in a later package version. See: diff --git a/RELEASING.md b/RELEASING.md index eb9192a..f80da77 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -82,11 +82,11 @@ evidence is complete only when `npm owner ls cometapi` lists the maintainer-confirmed `cometapi_dev` account; until then this remains a Registry Alpha prerequisite. -Public Preview and Registry Alpha are complete. For the current stable -milestone, topic pushes, pull requests, merges, the immutable GitHub Release, -the bounded live smoke, npm publication, and environment approvals still -require authorization from the current maintainer request. This document -defines allowable mechanics but grants no standing remote-write permission. +Public Preview, Registry Alpha, and stable `0.1.0` are complete. Future topic +pushes, pull requests, merges, immutable GitHub Releases, bounded live smoke, +npm publication, and environment approvals require authorization from the +current maintainer request. This document defines allowable mechanics but +grants no standing remote-write permission. ## Candidate verification gate @@ -393,9 +393,9 @@ layers: host already declaring `openai@6.47.0`. The host resolved one effective OpenAI installation and preserved `APIError instanceof` identity. Registry signatures and attestations were verified with `npm audit signatures`. -- The `next` dist-tag resolves to `0.1.0-alpha.3`. The registry-created `latest` - tag remains on `0.1.0-alpha.1`; it is outside the prerelease installation path - and remains explicit residual cleanup before stable publication. +- The `next` dist-tag resolves to `0.1.0-alpha.3`. Stable publication moved + `latest` to `0.1.0`; the historical registry-created `latest` value on + `0.1.0-alpha.1` no longer remains. ## Stable 0.1.0 sequence @@ -418,21 +418,81 @@ executed README examples against the packed artifact, release-PR/tag/changelog/ manifest version agreement, reviewed security and compatibility status, and post-publication registry evidence. -Release Please is limited to the stable PR because its v5 single-package path -has an open upstream tagging defect when component names are omitted from tags. -After the reviewed release PR merges, create a draft `v0.1.0` GitHub Release -manually against the exact merge commit, review it with `prerelease=false`, and -publish it only once immutable releases are enabled. After successful manual -tagging, change the merged Release Please PR label from `autorelease: pending` -to `autorelease: tagged` so future release PRs are not blocked. - -Release Please does not author the final public status text. After it opens the -`0.1.0` PR, a maintainer pushes a focused documentation commit to that same -branch: README switches from `next`/prerelease to `latest`/stable and records -the exact publication approval; SECURITY and SUPPORT remove prerelease-only -policy; COMPATIBILITY and ROADMAP identify the stable candidate without -claiming it is already released. If Release Please updates the branch again, -repeat the review and CI dispatch against the new final head. +The `0.1.0` promotion limited Release Please to the stable PR because its v5 +single-package path has an open upstream tagging defect when component names +are omitted from tags. After the release PR merged, a maintainer created the +draft `v0.1.0` GitHub Release manually against the exact merge commit, reviewed +it with `prerelease=false`, and published it with immutable releases enabled. +Release Please did not add an `autorelease: pending` label to the manually +opened stable PR, and the repository has no `autorelease` labels, so no post-tag +label transition applied to this release. + +Release Please did not author the final public status text. A maintainer pushed +the focused README, SECURITY, SUPPORT, COMPATIBILITY, and ROADMAP candidate +state to the generated branch and repeated the CI review on the final head +before merging it. + +## Stable 0.1.0 release evidence + +Stable `0.1.0` completed on 2026-07-28 with these independently auditable +layers: + +- The maintainer-edited release pull request [#28](https://github.com/cometapi-dev/cometapi-node/pull/28) + had required pull-request CI in [run 30344166767](https://github.com/cometapi-dev/cometapi-node/actions/runs/30344166767) + and the manually dispatched latest-compatible OpenAI 6.x lane in + [run 30344290818](https://github.com/cometapi-dev/cometapi-node/actions/runs/30344290818) + on final head `34f8dd342b56f82baa1d5a98807d715fe0bd60bf`. + GitHub records no formal `APPROVED` review object; maintainer review is + evidenced by the focused candidate edits, merge, Release publication, and + protected npm-environment approval. +- The protected merge produced + `1752cbb57f11dc6dca8dd1b13f0f8d5e8b5fdfca`; its tree matched the reviewed + final head, and default-branch Node.js 22 and 24 CI passed in + [run 30345116325](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345116325). +- The immutable [`v0.1.0` release](https://github.com/cometapi-dev/cometapi-node/releases/tag/v0.1.0) + targets that exact merge commit with `prerelease=false`. Its + [publish run 30345735681](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345735681) + rebuilt and verified one exact artifact, executed the bounded three-request + release-tag live smoke with a 16-output-token cap, 60-second per-request + timeout, concurrency one, and stop on first failure, then published through + the protected `npm` environment and GitHub Actions OIDC. +- npm's `latest` dist-tag resolves to `0.1.0`, while `next` remains on + `0.1.0-alpha.3`. The registry artifact has SHA-1 + `e509196ac5618d5b073207c74c7cdc5204efbe37` and SHA-512 integrity + `sha512-B7vyPXZkoZRM2JjFMQZthumUHgHWZLcPlQt8SG5oopPL2JGU0LR1iBOjtox4Mos+gZmA1Bs2q6vLPX2loHyfuw==`. +- npm reports SLSA provenance v1 and a registry signature. The provenance binds + `cometapi@0.1.0` to `refs/tags/v0.1.0`, the publishing workflow, run + `30345735681`, and the exact release commit. The Sigstore transparency-log + index is + [`2269554513`](https://search.sigstore.dev/?logIndex=2269554513), and the npm + publish-attestation index is + [`2269555365`](https://search.sigstore.dev/?logIndex=2269555365). +- Separate post-publication registry verification downloaded the workflow + artifact and npm tarball and found them byte-for-byte identical. Registry + signature and attestation verification passed. The registry tarball then + passed the ESM, CommonJS, and compatible-OpenAI host fixtures; the host + resolved one effective `openai@6.47.0` installation and preserved official + error identities. +- A closeout `npm audit` of the locked development checkout reported six + development-tooling findings: five high through + ESLint/minimatch/brace-expansion and one low in esbuild. `npm audit +--omit=dev` reported zero production vulnerabilities; these findings do not + affect the published production dependency graph and remain deferred + dependency-maintenance work. +- The immutable npm `0.1.0` tarball retains its candidate-era README. The + post-release documentation status recorded here and on the default branch can + first appear inside a later package artifact; no published tarball was + rewritten. +- The post-merge Release Please + [run 30345116433](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345116433) + failed after updating its unreviewed temporary branch to + `3f0949e5c0ccd0923d10595437f7a315f013af7c`, a generated `0.2.0` draft, but + before creating a pull request. It did not modify `main`, create a tag, or + publish a package. `RELEASE_PLEASE_ENABLED` was set to `false` before the + closeout push; the branch is retained as failure evidence and must not be + merged or treated as the start of 0.2. Release Please remains disabled until + its post-manual-release discovery and pull-request authorization strategy are + reviewed in a separately authorized maintenance task. ## Verification record diff --git a/ROADMAP.md b/ROADMAP.md index c6ceff8..f5e3bb3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,13 +1,13 @@ # CometAPI TypeScript and Node.js SDK Roadmap -Status: Public Preview and Registry Alpha complete; 0.1.0 stable in progress +Status: Public Preview, Registry Alpha, and 0.1.0 stable complete Last updated: 2026-07-28 Repository contract: This roadmap is self-contained and is the public source of truth for this repository's release sequence. -The reviewed `0.1.0` release candidate is prepared. It becomes released only -after the immutable GitHub Release, bounded live smoke, OIDC publication, -provenance, signature, and public-install checks all pass. +Stable `0.1.0` completed the immutable GitHub Release, bounded live smoke, OIDC +publication, provenance, signature, and separate post-publication install +checks on 2026-07-28. ## Product Target @@ -23,7 +23,8 @@ available from npm. The immutable `0.1.0-alpha.2` GitHub release failed locally before invoking npm because its publication guard rejected the fixed `actions/setup-node` authentication placeholder. `0.1.0-alpha.3` completed the OIDC, provenance, ownership, and public-install verification sequence and is -available from npm's `next` channel. +available from npm's `next` channel. Stable `0.1.0` is available from npm's +default `latest` channel with verified provenance and public-install evidence. ## Milestones @@ -33,7 +34,7 @@ available from npm's `next` channel. | 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, and authorized live-smoke evidence. | | 0.1.x Registry Alpha | Complete | Early adopters can install a functional, provenance-verified prerelease from npm's `next` channel through the OIDC-only publication path. | -| 0.1.0 Stable | In progress | Users can install a fully verified package from npm's default channel. | +| 0.1.0 Stable | Complete | Users can install a fully verified package from npm's default channel. | | 0.2.0 provider-native text | Planned | Users can opt into Anthropic Messages and Gemini text adapters through isolated subpath exports. | | 0.3.0 CometAPI resources | Planned | Users receive typed access to the first stable CometAPI-specific account or platform resources. | | Media and task APIs | Later | Users receive typed image, video, audio, upload, polling, and task lifecycle helpers after their contracts are stable. | @@ -93,6 +94,13 @@ URL. The canonical repository is and `https://github.com/cometapi-dev/cometapi-node/issues` for `bugs.url`. `CODEOWNERS` remains absent until a real multi-maintainer model exists. +Foundation remains in progress after stable `0.1.0` because Release Please is +disabled pending a separate review of its post-manual-release discovery and +pull-request authorization strategy. Its failed post-merge run generated an +unreviewed temporary `0.2.0` branch commit but did not create a pull request or +change `main`; that branch is failure evidence only and is not the start of the +0.2 milestone. + ## Private Remote Validation Before Public Preview, maintainers create a private repository from a @@ -214,6 +222,13 @@ Test and package exit criteria: - npm publication uses OIDC trusted publishing with provenance, and the public artifact passes a post-publication install and mocked-call smoke test. +Completion evidence is recorded in +[RELEASING.md](./RELEASING.md#stable-010-release-evidence). It includes the +reviewed candidate and default-branch CI, the exact immutable release commit, +the bounded release-tag live smoke, OIDC publication, registry signatures and +provenance, byte-identical workflow and registry artifacts, and separate +post-publication ESM, CommonJS, and compatible-OpenAI host fixtures. + Explicit non-goals: - Reimplementing HTTP, SSE, retry, timeout, or OpenAI protocol models.