diff --git a/AGENTS.md b/AGENTS.md index d1245f0..9cb5654 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,23 +79,19 @@ 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 `0.1.1` established the runtime options boundary and repaired the release -path without expanding the 0.1 resource surface. Release Please created the -reviewed patch PR, immutable tag, and GitHub Release. Publication required a -disclosed one-time main-context recovery because the immutable tag predated the -repaired tag handoff. The recovery published only the exact previously verified -artifact through npm OIDC, then the repository restored its variables and -tag-only Environment policy. The current workflow contains no -publication-recovery input, fixed recovery run or artifact ID, -prior-package-artifact or live-evidence reuse, or branch-context publication -path. +Stable maintenance established the runtime options boundary without expanding +the 0.1 resource surface. Release-specific recovery history and immutable +evidence belong in `RELEASING.md`, not in this durable operating contract. The +permanent stable-patch path uses a reviewed Release Please PR, an immutable tag +and GitHub Release, an unprivileged tag handoff, fresh exact-artifact and bounded +live verification, and tag-bound npm OIDC publication. That path has completed +an end-to-end registry publication. Release Please remains disabled between explicitly authorized release -operations. Permanent stable patches follow only the tag-bound path in -`RELEASING.md`. The recovery provenance for stable `0.1.1` is historical -evidence and does not prove an execution of the permanent path. The next -explicitly authorized stable patch is that path's first end-to-end registry -execution. +operations. The current workflow contains no publication-recovery input, fixed +recovery run or artifact ID, prior-package-artifact or live-evidence reuse, or +branch-context publication path. Permanent stable patches follow only the +tag-bound path in `RELEASING.md`. ## Product Contract diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index c86bcc8..1f1834b 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -152,3 +152,18 @@ chain recorded in [RELEASING.md](./RELEASING.md#stable-011-release-evidence). Separate public-registry verification passed ESM, CommonJS, declarations, supported mocked calls, one effective OpenAI installation, official error identity, integrity, signature, and provenance. + +For stable `0.1.2`, the strict structural option declarations and packed +ESM/CommonJS fixtures passed +[source PR CI 30600555979](https://github.com/cometapi-dev/cometapi-node/actions/runs/30600555979) +and the action-authored release candidate passed +[CI run 30600746212 attempt 2](https://github.com/cometapi-dev/cometapi-node/actions/runs/30600746212/attempts/2). +Release Please created the immutable +[`v0.1.2` Release](https://github.com/cometapi-dev/cometapi-node/releases/tag/v0.1.2), +and +[Publish run 30601661643](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601661643) +completed the first permanent tag-bound release sequence. Its bounded live +smoke, OIDC publication, public-registry ESM/CommonJS and declaration checks, +single effective OpenAI installation, official error identity, integrity, +signature, and provenance evidence is recorded in +[RELEASING.md](./RELEASING.md#stable-012-release-evidence). diff --git a/RELEASING.md b/RELEASING.md index 0c4b200..978a916 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -672,6 +672,107 @@ Finally, commit-level `Release-As:` is rejected before the action because the GitHub documents that a `GITHUB_TOKEN`-created PR's opened or synchronize event [creates an approval-required workflow run](https://github.com/github/docs/blob/e1e4aa937308f21c411c248b4966873536bb0cba/data/reusables/actions/actions-do-not-trigger-workflows.md#L1-L6). +## Stable 0.1.2 release evidence + +Stable `0.1.2` completed on 2026-07-31 with these independently auditable +layers: + +- Source [PR #44](https://github.com/cometapi-dev/cometapi-node/pull/44) fixed + the structural TypeScript option bypass, made consumer documentation + release-neutral, and prepared the permanent release path without expanding + the supported resource surface. Final head + `c0934cc804fb5c23f0ff38e463cdfb00784da159` passed + [CI run 30600555979](https://github.com/cometapi-dev/cometapi-node/actions/runs/30600555979) + and merged as + [`1d62b52fc5ca2fc803c11fbc99cf9c5991c6c974`](https://github.com/cometapi-dev/cometapi-node/commit/1d62b52fc5ca2fc803c11fbc99cf9c5991c6c974). +- Manual Release Please preparation + [run 30600722163 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30600722163/attempts/1) + ran from that exact merge on `main`, logged `updating from 0.1.1 to 0.1.2`, + and created only the action-authored release PR below. This is remote evidence + that the repaired stable-patch configuration selected `0.1.2`, not `0.2.0`. +- The resulting four-file release + [PR #45](https://github.com/cometapi-dev/cometapi-node/pull/45) had final head + `c335f7081b9e8bb7cce7060c85c53d08947423d1` and changed only the manifest, + changelog, package lock, and package manifest. After the human workflow gate, + its complete blocking matrix passed in + [CI run 30600746212 attempt 2](https://github.com/cometapi-dev/cometapi-node/actions/runs/30600746212/attempts/2). + Human repository administrator `tensornull`, distinct from bot author + `github-actions[bot]`, submitted formal + [review 4825214156](https://github.com/cometapi-dev/cometapi-node/pull/45#pullrequestreview-4825214156) + with `state=APPROVED` against that exact head before merge. The reviewed merge + produced + [`e348f7800c6088e0349b67ce5927cd9ba50dde25`](https://github.com/cometapi-dev/cometapi-node/commit/e348f7800c6088e0349b67ce5927cd9ba50dde25). +- [Release Please run 30601626589 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601626589/attempts/1) + created the exact lightweight `v0.1.2` tag and immutable non-prerelease GitHub + Release ID `362834814`. The bot-authored + [`v0.1.2` Release](https://github.com/cometapi-dev/cometapi-node/releases/tag/v0.1.2) + targets the reviewed merge commit and was published at + `2026-07-31T03:27:59Z`. +- The unprivileged + [handoff run 30601651061 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601651061/attempts/1) + validated the Release Please result and immutable Release before dispatching + the exact tag. Tag-bound + [Publish run 30601661643 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601661643/attempts/1) + rebuilt the release commit, passed the full release checks and public + declarations/fixtures, and uploaded artifact ID `8782147591`, named + `npm-package-0.1.2-30601661643-1`, with ZIP digest + `sha256:59f840b182e2e7c74b237ba507ea725e76e60174ce817b8fc18d99c6631d0131`. + Its sole tarball has SHA-256 + `88923983b62cbeaf37f7aacdea4d89b9b9a55b81ab8f0748cf1a8d0135c74d58` + and is byte-identical to the public registry tarball. +- The same run's + [live job 91065744397](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601661643/job/91065744397) + checked out `refs/tags/v0.1.2` and passed exactly three sequential `gpt-5.4` + requests with a 16-token output cap, 60-second per-request timeout, + concurrency one, and stop-on-first-failure behavior. +- Attempt 1's protected npm job `91065788380` published through the tag-only npm + Environment and GitHub Actions OIDC at `2026-07-31T03:36:57.735Z`. Publication + succeeded, but the immediately following attestation fetch received the + registry's transient `404`, so the job failed after npm mutation. After the + attestations became readable, the sole authorized + [failed-job replay](https://github.com/cometapi-dev/cometapi-node/actions/runs/30601661643/attempts/2) + used npm job `91069383430`; it reported + `cometapi@0.1.2 already matches the verified artifact; resuming checks.` and + completed without a second `npm publish`. GitHub preserved the successful + exact-artifact job `91069398975` and bounded-live job `91069383750` from + attempt 1. +- At closeout, npm's stable channel resolved to `0.1.2`, while the prerelease + channel remained `0.1.0-alpha.3`. The package has SHA-1 + `2f3b1ec8c9149172fe52ac25b0a7658cdc102ed8` and integrity + `sha512-JmFFjOX9GBJqjp7I8XOrTvCHAxd8zYQjLKIX/CKE0wPQ+98HpzBXn4cuA/OUzRsW8/GtX2vfYBEsL588P1XWkw==`. + `npm audit signatures` passed. npm exposes its publish attestation at + [Sigstore index 2298372367](https://search.sigstore.dev/?logIndex=2298372367) + and SLSA provenance at + [index 2298372342](https://search.sigstore.dev/?logIndex=2298372342). The + provenance binds `cometapi@0.1.2` to `refs/tags/v0.1.2`, commit + `e348f7800c6088e0349b67ce5927cd9ba50dde25`, and Publish run + `30601661643/1`. +- Clean public-registry verification installed `cometapi@0.1.2` with one + effective `openai@6.47.0` installation and passed ESM, CommonJS, `.mts` and + `.cts` declarations, supported mocked calls, official `APIError instanceof` + identity, integrity, registry signatures, and both attestations. +- Post-publication hardening + [PR #46](https://github.com/cometapi-dev/cometapi-node/pull/46) made the + observed failed-job convergence finite and fail-closed. Final head + `05041c4080a57814a3d2e90122185951b9b84404` passed + [PR CI 30607413580](https://github.com/cometapi-dev/cometapi-node/actions/runs/30607413580) + and exact-head owner audit + [review 4825808534](https://github.com/cometapi-dev/cometapi-node/pull/46#pullrequestreview-4825808534), + recorded as `state=COMMENTED`, merged as + `d02b87da330d4b71d194f5c3a6df727b20dc9df3`, and passed + [default-branch CI 30607756481](https://github.com/cometapi-dev/cometapi-node/actions/runs/30607756481). + Final state was read back as `RELEASE_PLEASE_ENABLED=false`, + `LIVE_SMOKE_ENABLED=true`, and exactly one npm Environment deployment policy, + `tag:v*` (policy ID `55718965`). Post-merge + [Release Please run 30607756491](https://github.com/cometapi-dev/cometapi-node/actions/runs/30607756491) + and + [Publish handoff run 30607764192](https://github.com/cometapi-dev/cometapi-node/actions/runs/30607764192) + were skipped as required. + +This is the first completed end-to-end registry publication through the +permanent immutable-tag handoff. The earlier one-time main-context recovery +remains historical evidence only and is not a reusable release path. + ## Stable 0.1.1 release evidence Stable `0.1.1` completed on 2026-07-30 with these independently auditable @@ -754,12 +855,10 @@ layers: `LIVE_SMOKE_ENABLED=true`, and exactly one npm deployment policy, `tag:v*` (policy ID `55718965`). -The permanent immutable-tag handoff has passed static contract checks, -adversarial mutations, pull-request CI, and default-branch CI. Because the -immutable `v0.1.1` tag predates that final path, `0.1.1` publication used the -disclosed main-context exception above. The next explicitly authorized stable -patch remains the first end-to-end registry publication of the permanent -tag-bound route. +The permanent immutable-tag handoff later completed its first end-to-end +registry publication in the stable `0.1.2` evidence above. The `0.1.1` +publication remains evidence only for the disclosed main-context exception and +does not authorize that path again. ## Stable 0.1.0 release evidence diff --git a/ROADMAP.md b/ROADMAP.md index c66a062..4846107 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -5,9 +5,10 @@ Last updated: 2026-07-31 Repository contract: This roadmap is self-contained and is the public source of truth for this repository's release sequence. -Stable `0.1.1` completed the corrected options contract, immutable GitHub -Release, bounded live smoke, OIDC publication, provenance, signature, separate -public-install verification, and recovery-path cleanup on 2026-07-30. +Stable `0.1.2` completed the public options type contract, release-neutral +consumer documentation, the first permanent immutable-tag publication, bounded +live smoke, OIDC provenance, public-install verification, and replay hardening +on 2026-07-31. ## Product Target @@ -24,9 +25,10 @@ Release then failed before invoking npm because its publication guard rejected the fixed `actions/setup-node` authentication placeholder. `0.1.0-alpha.3` subsequently completed the OIDC, provenance, ownership, and public-install verification sequence. Stable `0.1.1` completed its separately -recorded release sequence on 2026-07-30. Stable 0.1.x packages use `latest`, and -Registry Alpha artifacts use `next`; query npm and GitHub rather than treating -this roadmap as current registry state. +recorded recovery sequence on 2026-07-30, and stable `0.1.2` completed the +permanent tag-bound sequence on 2026-07-31. Stable 0.1.x packages use `latest`, +and Registry Alpha artifacts use `next`; query npm and GitHub rather than +treating this roadmap as current registry state. ## Milestones @@ -38,6 +40,7 @@ this roadmap as current registry state. | 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 | Complete | Users can install a fully verified package from npm's default channel. | | 0.1.1 maintenance patch | Complete | Users receive the corrected options contract; the permanent tag-bound release architecture is installed and the one-time recovery is recorded. | +| 0.1.2 maintenance patch | Complete | Users receive strict public option types and release-neutral package documentation through the verified permanent tag-bound publication path. | | 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. | @@ -121,11 +124,10 @@ The permanent state is `RELEASE_PLEASE_ENABLED=false`, `LIVE_SMOKE_ENABLED=true`, and exactly one npm Environment deployment policy, `tag:v*`. Current stable publication uses an unprivileged Release Please handoff followed by an immutable-tag dispatch, fresh verification and live -smoke, and tag-bound npm OIDC. Stable `0.1.1` itself has main-bound provenance -from the disclosed recovery, so the next explicitly authorized stable patch is -the first end-to-end registry execution of the permanent tag-bound path. Full -evidence is recorded in -[RELEASING.md](./RELEASING.md#stable-011-release-evidence). +smoke, and tag-bound npm OIDC. Stable `0.1.2` completed the first end-to-end +registry execution of that permanent path. Full immutable evidence is recorded +in [RELEASING.md](./RELEASING.md#stable-012-release-evidence); the earlier +one-time recovery remains separately recorded as historical evidence. ## Private Remote Validation @@ -304,14 +306,38 @@ Completion evidence: recovery-path cleanup. The evidence is recorded in [RELEASING.md](./RELEASING.md#stable-011-release-evidence). +## 0.1.2: Public Contract and Tag-Bound Release Verification (Complete) + +Stable `0.1.2` redeclared `provider`, `workloadIdentity`, and +`dangerouslyAllowBrowser` as optional `never` fields on `CometAPIOptions`. +TypeScript negative tests now exercise variables, spreads, +`satisfies ClientOptions`, and constrained generics through both the constructor +and `withOptions`; the secret-free runtime guard remains authoritative for plain +JavaScript and casts. The patch also made the README release-neutral and kept +`package.json` as the sole candidate-version authority without changing the +supported resource surface. + +The action-authored, exact-head-approved Release Please PR produced the +immutable tag and GitHub Release. The unprivileged handoff then dispatched the +exact tag, rebuilt and verified the artifact, ran the bounded three-request live +smoke, and published through the tag-only npm Environment with OIDC provenance. +When npm's attestation endpoint briefly returned `404` after successful +publication, the single failed-job replay detected the byte-identical existing +version and completed verification without invoking `npm publish` again. + +Post-publication hardening made that observed recovery finite and executable: +handoff, exact-artifact verification, and live smoke are attempt-1-only; +publication permits only an attempt-2 existing-version convergence check; and +attempt 3 or later fails before entering the npm Environment. Release-specific +PR, review, run, artifact, registry, provenance, and final-state evidence is +recorded in [RELEASING.md](./RELEASING.md#stable-012-release-evidence). + ## Stable 0.1.x Maintenance Maintenance patches close contract and release-process gaps without expanding -the supported resource surface. The active maintenance work redeclares the -three reserved client controls as optional `never`, executes negative tests for -variables, spreads, `satisfies ClientOptions`, and constrained generics through -both the constructor and `withOptions`, and preserves the runtime guard for -plain JavaScript and casts. +the supported resource surface. Future maintenance must preserve the strict +reserved-option type and runtime boundary, the release-neutral consumer +documentation, and the immutable-tag publication contract established above. Durable README, agent, compatibility, roadmap, and release guidance uses 0.1.x capability and channel language instead of copying a mutable exact version from @@ -319,7 +345,7 @@ the registry. `package.json` is the sole candidate-version authority, the packed README must match the reviewed source byte-for-byte, and the release gates reject exact-version current, approval, unpublished, or in-progress claims. -This maintenance work is complete only after the normal four-file Release +Each maintenance patch is complete only after the normal four-file Release Please PR, immutable tag and GitHub Release, fresh bounded live smoke, tag-bound npm OIDC publication, and independent public-registry installation all pass. Release-specific evidence is recorded after publication rather than predicted @@ -394,11 +420,10 @@ The repository will maintain: registry verification. Only the tag-bound dispatch can reach verification, live, or publication authority. -All workflow files must pass local `actionlint`. The permanent tag-bound -publication contract has passed static, mutation, pull-request, and -default-branch CI, but `0.1.1` used the disclosed main-context recovery. Until a -later stable patch executes the permanent path through registry publication, -release reports must keep that remote end-to-end qualification explicit. +All workflow files must pass local `actionlint`. Stable `0.1.2` completed the +permanent tag-bound publication contract through registry verification. Its +post-publication replay hardening then passed static and mutation checks, +pull-request CI, exact-head owner audit, and default-branch CI. The initial manual alpha preparation starts with an empty version manifest and a temporary `release-as: 0.1.0-alpha.1` setting. Its reviewed pull request must