diff --git a/AGENTS.md b/AGENTS.md index ec32281..f126c3c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -51,14 +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 Complete +## Current Milestone: Stable 0.1.1 and Repository Foundation Complete -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. +Private Remote Validation, Public Preview, Registry Alpha, stable `0.1.0`, and +the `0.1.1` maintenance patch are complete. The canonical repository is public, +`0.1.1` is available from npm's `latest` channel, and `0.1.0-alpha.3` remains +available from `next`; the published lines have verified provenance and +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: @@ -78,25 +78,21 @@ 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 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 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 remains disabled between release operations after its post-0.1.0 -run generated an unreviewed `0.2.0` temporary-branch commit and then failed to -create a pull request. That branch was verified as failure-only evidence before -the authorized 0.1.1 operation replaced it with the action-owned patch branch. -Do not use either branch as a 0.2 starting point. The 0.1.1 maintenance task -repairs the workflow around the current read-only-default Actions baseline with -action-created pull requests enabled; any later enablement still requires an -explicit maintainer request and the fail-closed checks in `RELEASING.md`. -For this repair, merge the anchor-removal finalization PR first, then use a new -first-attempt manual dispatch to refresh the same action-owned 0.1.1 PR before -its final CI and human-owner review. +Stable `0.1.1` corrected the public options boundary 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. + +Release Please remains disabled between explicitly authorized release +operations. Permanent stable patches follow only the tag-bound path in +`RELEASING.md`. The `0.1.1` recovery provenance is historical evidence, not +proof that the current permanent tag path has completed a registry publication; +the next explicitly authorized stable patch is its first end-to-end execution. ## Product Contract @@ -256,6 +252,32 @@ repository root. - The legal copyright holder and official security and support contacts must be maintainer-confirmed and must never be invented. +### Stable patch workflow + +- Follow the stable-patch route in `RELEASING.md`: Release Please prepares the + reviewed patch PR and immutable Release, an unprivileged handoff dispatches + `publish.yml` from the exact immutable tag, and only that tag-bound run may + verify, run the bounded live smoke, enter the npm Environment, or request OIDC. +- Before requesting review, compare the PR author login with the intended + reviewer login. A PR author cannot approve the same PR even when that author + is a repository administrator. +- Under a zero-required-approval ruleset, a same-author exact-head `COMMENTED` + review is an owner audit only and must never be described as `APPROVED`. Any + required approval must be a formal exact-head `APPROVED` review from a + different human. An action-authored Release Please PR always requires that + distinct-human administrator approval. +- GitHub's **Approve and run workflows** control authorizes a workflow run for + CI; it is separate from the PR review gate and satisfies no review requirement. +- Prepare or refresh a release PR with a new first-attempt manual Release Please + dispatch. Do not rerun a preparation dispatch. Release Please same-run Release + reconciliation is allowed only under the exact conditions in `RELEASING.md`. +- Never bypass a failed stable release with a manual or auxiliary tag, a + branch-context publish, a temporary `main` npm Environment policy, reused + artifact or live evidence, an arbitrary rerun, or a different patch version. +- After registry verification, immediately restore + `RELEASE_PLEASE_ENABLED=false`, keep `LIVE_SMOKE_ENABLED=true`, and require the + npm Environment deployment-policy set to contain only `tag:v*`. + Before Public Preview, run `npm run check:public-preview`. The gate must fail after reporting all violations until canonical identity, contacts, repository metadata, and durable public-facing content are complete. diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 1ef4b80..7b4112c 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -108,9 +108,10 @@ tag and GitHub release agreement. The publish workflow is the sole source of npm dist-tag selection: prereleases use `next`, stable versions use `latest`. The package manifest must not carry a static dist-tag because that would make stable and prerelease policy diverge. -Trusted Publishing remains the default authentication path. The only token -path is an explicitly enabled protected-environment fallback that rejects every -version except `0.1.0-alpha.1` and every dist-tag except `next`. +Trusted Publishing is the only executable authentication path. The protected- +environment token bootstrap used for `0.1.0-alpha.1` is historical evidence; +current workflows contain no token publication path and reject registry-token +credentials. For normal stable patches, Release Please owns the reviewed version/changelog PR and the immutable tag and GitHub Release. The configuration uses an explicit @@ -119,20 +120,23 @@ maintenance window cannot enter 0.2 implicitly and a root package does not fall into the single-package tag-discovery ambiguity encountered during 0.1.0. The workflow also rejects commit-level `Release-As:` notes before mutation because Release Please applies those overrides before its patch versioning strategy. -Because a -GitHub Release created with the default `GITHUB_TOKEN` does not start a separate -`release.published` workflow, publication is chained from the successful -Release Please workflow. The handoff accepts only the canonical repository's -successful attempt-qualified `push` run for `main` at the still-current exact -`main` SHA. The release workflow records normalized action outcome, recovery -state, pre-action Release presence, the exact Release-producing attempt, SHA, -tag, version, URL, repository, workflow identity, run ID, and attempt in a -schema-v2 exact-run artifact. Publication -downloads and validates only that attempt's artifact before checking the tag and -immutable Release. A first-attempt manual run is explicitly release-inert and -must succeed only after independently validating one canonical action-created -patch PR; its event cannot enter publication. Any successful `push` run without -the exact result artifact, tag, and immutable Release fails before live or +Because a GitHub Release created with the default `GITHUB_TOKEN` does not start +a separate `release.published` workflow, publication is chained from the +successful Release Please workflow. The handoff accepts only the canonical +repository's successful attempt-qualified `push` run for `main` at the +still-current exact `main` SHA. The release workflow records normalized action +outcome, same-run Release reconciliation state, pre-action Release presence, +the exact Release-producing attempt, SHA, tag, version, URL, repository, +workflow identity, run ID, and attempt in a schema-v2 exact-run artifact. An +unprivileged `workflow_run` handoff validates only that attempt's artifact, +exact tag, immutable Release, and current `main`, then dispatches `publish.yml` +with `ref=v`. Only that tag-bound `workflow_dispatch` can reach fresh +artifact verification, bounded live smoke, the npm Environment, or OIDC. A +first-attempt manual run is explicitly release-inert and must succeed only after +independently validating one canonical action-created patch PR; its event cannot +enter publication. A successful `push` preparation run whose result-upload step +was skipped is also release-inert. Any purported release handoff with missing or +mismatched result, tag, or immutable Release evidence fails before live or registry access. The release outcome and package artifact are verified independently. @@ -143,17 +147,19 @@ fail-closed on exact tag, artifact, dist-tag, integrity, and provenance state. Manual preparation rejects attempt 2 or later; restart uses a new dispatch with Release creation disabled. A `push` rerun is bounded to the same run ID, SHA, candidate, and final-head review. It may retry while the tag and Release remain -absent. If an earlier attempt already created the Release, recovery accepts only -the exact bot-authored immutable Release at that SHA whose publication time -falls inside exactly one earlier Release Please step from the same run. +absent. If an earlier attempt already created the Release, same-run +reconciliation accepts only the exact bot-authored immutable Release at that +SHA whose publication time falls inside exactly one earlier Release Please step +from that run. Release-mode action failure is tolerated only long enough to prove that postcondition, reconcile the release PR to `autorelease: tagged`, and write the attempt-qualified artifact. The authorized Actions setting lets the default token create the PR; the resulting approval-required CI still needs a human with write access to authorize execution, and bot review cannot satisfy -the release gate. A merged -release PR is accepted for tagging only after a distinct repository -administrator approved its final head. The workflow checks the triggering SHA, +the release gate. A head change invalidates both a prior `COMMENTED` owner audit +and a formal approval. A merged release PR is accepted for tagging only after a +distinct human repository administrator formally approved its exact final +head. The workflow checks the triggering SHA, release-branch snapshot, all open and closed PR identities, current review, and tag/Release state immediately before Release Please mutation, then rechecks `main`, the release branch, the complete PR snapshot, exact final-head approval, @@ -164,6 +170,17 @@ additional PR cannot be tagged. Manual dispatch is therefore release-inert: it may prepare one canonical action-created PR only when no merged release PR is awaiting a tag. +Stable `0.1.1` used a one-time main-context publication recovery after its +immutable tag predated the permanent tag-bound workflow. It reused only the +previously verified exact artifact and bounded live evidence, so npm provenance +names the reviewed recovery control commit on `refs/heads/main` rather than the +tag. [PR #41](https://github.com/cometapi-dev/cometapi-node/pull/41) removed +every fixed recovery identifier, prior-evidence reuse branch, and temporary +`main` deployment-policy path. The permanent npm Environment policy set is +exactly `tag:v*`; branch-context publication is not part of the architecture. +The exception is historical evidence and must never be reconstructed. See +[Stable 0.1.1 release evidence](./RELEASING.md#stable-011-release-evidence). + ## Testing layers Evidence is separated by layer: diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 50e63e0..65ed0b6 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -3,11 +3,9 @@ Compatibility document version: 0.1 Package line: `0.1.x` -Stable release: `0.1.0`; the immutable release workflow and separate -post-publication registry verification completed on 2026-07-28. - -Maintenance candidate: `0.1.1`; the options-contract and Release Please repair -is not a release claim until its remote release and registry evidence completes. +Stable release: `0.1.1`; the immutable Release, bounded live smoke, npm OIDC +publication, and separate public-registry verification completed on 2026-07-30. +Registry Alpha `0.1.0-alpha.3` remains available from npm's `next` channel. This matrix defines the contract-tested 0.1 compatibility surface. Inheritance from the official OpenAI client does not by itself establish CometAPI support. @@ -136,3 +134,15 @@ signatures and provenance, and public artifact checks passed in 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. + +For stable `0.1.1`, the final release-PR head passed the blocking, minimum, +locked, latest-compatible, Node.js 26 advisory, package, workflow, and +standalone lanes in +[CI run 30468358086](https://github.com/cometapi-dev/cometapi-node/actions/runs/30468358086). +Release Please created the immutable +[`v0.1.1` Release](https://github.com/cometapi-dev/cometapi-node/releases/tag/v0.1.1), +and the bounded live smoke plus OIDC publication completed in the evidence +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. diff --git a/README.md b/README.md index 7b0a262..e8ca5e7 100644 --- a/README.md +++ b/README.md @@ -4,15 +4,12 @@ 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:** `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). -> -> **Approved maintenance candidate:** `0.1.1` is approved for npm publication -> through the reviewed Release Please path. This approval is not a release -> claim: `0.1.1` remains unpublished until the immutable release, npm OIDC -> publication, and public-registry verification complete. +> **Stable 0.1 release:** `0.1.1` is published on npm's default `latest` +> dist-tag. Its immutable GitHub Release, bounded live smoke, npm OIDC +> publication, provenance, signature, and separate public-registry installation +> verification are complete. The supported API remains limited to the +> contract-tested 0.1 surface documented here and in +> [COMPATIBILITY.md](./COMPATIBILITY.md). ## Supported 0.1 surface @@ -232,23 +229,24 @@ parent. ## Project status -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. - -The `0.1.1` options-contract and Release Please repair is in progress. Until its -full release sequence completes, npm `latest` remains `0.1.0` and this candidate -must not be described as published. No 0.2 provider adapter work is included. +The repository has completed Public Preview, Registry Alpha, stable `0.1.0`, +the `0.1.1` maintenance patch, and Repository foundation. Blocking CI, +protected repository rules, security reporting, protected environments, and +the authorized bounded live smoke have passed. Stable `0.1.1` is available from +`latest`; Registry Alpha `0.1.0-alpha.3` remains available from `next`. A +separate public-registry check passed ESM, CommonJS, declarations, supported +mocked calls, the compatible-OpenAI host fixture with one effective OpenAI +installation, official error identity, integrity, signature, and provenance. + +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. Published npm +artifacts are immutable, so the `0.1.1` tarball retains its candidate-era +README; this post-release status first ships in a later package version. The +one-time `0.1.1` publication recovery is documented as historical evidence in +[RELEASING.md](./RELEASING.md); the current permanent release workflow is +immutable-tag-bound. No 0.2 provider adapter work is included. See: diff --git a/RELEASING.md b/RELEASING.md index 610f605..a757897 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -4,16 +4,16 @@ Release status is evidence-based: -| State | Required evidence | -| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Local code-complete | Required source, tests, documentation, metadata, fixtures, and workflows exist, and every applicable offline check passes. | -| Private Remote Validation ready | Local gates pass, the sanitized history and maintainer-confirmed identity are complete, and real credential-free private default-branch CI passes. | -| Public Preview ready | After visibility changes, public-only repository rules, security reporting, environments, default-branch CI, the content gate, and authorized protected live smoke all pass. | -| Registry Alpha candidate | The exact `0.1.0-alpha.3` artifact passes package and clean-install gates after preserving the unpublished immutable alpha.2 failure record. | -| Registry Alpha released | The public npm artifact installs from the `next` channel, passes post-publication verification, and has verified provenance plus any documented one-time bootstrap evidence. | -| Stable released | Every stable 0.1.0 local, remote, live, review, provenance, and registry gate has recorded evidence. | -| Stable patch candidate | An action-created Release Please PR has the exact version, changelog, manifest, temporary-anchor removal, complete CI matrix, and human-owner review. | -| Stable patch released | The immutable Release Please tag and GitHub Release, bounded live smoke, npm OIDC publication, and independent public-registry verification all pass. | +| State | Required evidence | +| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Local code-complete | Required source, tests, documentation, metadata, fixtures, and workflows exist, and every applicable offline check passes. | +| Private Remote Validation ready | Local gates pass, the sanitized history and maintainer-confirmed identity are complete, and real credential-free private default-branch CI passes. | +| Public Preview ready | After visibility changes, public-only repository rules, security reporting, environments, default-branch CI, the content gate, and authorized protected live smoke all pass. | +| Registry Alpha candidate | The exact `0.1.0-alpha.3` artifact passes package and clean-install gates after preserving the unpublished immutable alpha.2 failure record. | +| Registry Alpha released | The public npm artifact installs from the `next` channel, passes post-publication verification, and has verified provenance plus any documented one-time bootstrap evidence. | +| Stable released | Every applicable stable local, remote, live, review, provenance, and registry gate has recorded evidence. | +| Stable patch candidate | An action-created Release Please PR has the exact version, changelog, manifest, complete CI matrix, and formal exact-head `APPROVED` review from a distinct human administrator. | +| Stable patch released | The immutable Release Please tag and GitHub Release, bounded live smoke, npm OIDC publication, and independent public-registry verification all pass. | A build, mock, valid workflow file, successful upload, or HTTP 200 proves only its own layer. Never use it to claim a later state. @@ -84,7 +84,8 @@ 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, Registry Alpha, and stable `0.1.0` are complete. Future topic +Public Preview, Registry Alpha, stable `0.1.0`, stable `0.1.1`, and Repository +foundation 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 @@ -110,6 +111,12 @@ PRs remain different: the release workflow requires a formal, exact-head `APPROVED` review from a human repository administrator whose login differs from the bot author. +Any head change invalidates an earlier exact-head `COMMENTED` audit or formal +approval. Release and publication trust-boundary PRs require a new exact-head +human record before merge. GitHub's **Approve and run workflows** control is a +separate authorization for CI created by an action-authored PR; it is not a PR +review and satisfies no approval requirement. + ## Candidate verification gate Run from the repository root on a clean checkout: @@ -225,12 +232,15 @@ then returns non-zero if any violation exists. It must require `git+https://github.com/cometapi-dev/cometapi-node.git` as `repository.url`, the same value required by publish validation. -Maintainers perform this transition in the reviewed release PR before creating -or publishing the immutable release. Validate the exact committed state with: +Maintainers perform this transition in the reviewed implementation or +finalization PR before Release Please preparation; the generated release PR +remains limited to its four release files. Validate the exact committed state +with: ```bash +release_version="$(node -p "require('./package.json').version")" node scripts/validate-release.mjs \ - --tag v0.1.0 \ + --tag "v${release_version}" \ --release-prerelease false \ --require-final \ --require-releasable-docs @@ -283,8 +293,8 @@ The repository maintains four independently auditable workflows: introduce a PAT or GitHub App credential. Component identity remains internal to release discovery: `include-component-in-tag=false` requires the exact public `v` tag. - The workflow has contents, pull-request, and issue permissions only for those - repository operations; it has no npm OIDC permission. + Its write permissions are limited to `contents`, `pull-requests`, and + `issues`; it also has `actions: read` and no npm OIDC permission. - `publish.yml`: separates release discovery from registry authority. A successful trusted Release Please `workflow_run` can enter only the `handoff` job. That job has no Environment and no OIDC permission. It validates the @@ -505,99 +515,61 @@ PR body. Release validators still require the exact dated stable-patch section, the four-file candidate shape, and exact PR-body note equality; secret, standalone-content, and public-preview checks continue to scan the file. -The 0.1.1 repair used one explicit `last-release-sha` boundary at the immutable -0.1.0 release commit, `1752cbb57f11dc6dca8dd1b13f0f8d5e8b5fdfca`, only for -the initial preparation dispatch. That dispatch proved the normal action-owned -0.1.1 PR without rediscovering pre-0.1.0 features. A normal topic PR then removes -the temporary override and records final candidate approval on `main`; a fresh -preparation dispatch refreshes the action-owned release PR from that state. The -finalization commit must use a releasable `fix:` subject so Release Please -updates the generated notes and cannot treat the old branch as unchanged. -Future releases discover the Release Please-created `v0.1.1` boundary normally. - -Before enabling the repaired workflow, create the standard -`autorelease: pending` and `autorelease: tagged` labels if they are still -absent. The configuration names both labels explicitly, and the action-created -release PR must receive `autorelease: pending` automatically. Stop if the action -cannot create or label that PR; do not replace the normal flow with a manually -authored PR. Release Please performs the normal tagged transition with its -scoped `issues: write` permission. - -Confirm through the repository Actions API that -`default_workflow_permissions=read` and -`can_approve_pull_request_reviews=true`. The latter is the explicitly authorized -0.1.1 baseline solely so the default token can create the Release Please PR. -The release workflow must never change either setting, and any later drift is a -stop condition. - -After enabling `RELEASE_PLEASE_ENABLED`, start a new manual dispatch on `main`; -do not rerun the skipped workflow from the repair merge. Only attempt 1 of a -manual dispatch may call Release Please; an unchanged PR is restarted with a -new dispatch, not a rerun. The workflow rejects any dispatch whose triggering -ref is not `refs/heads/main`, and all preparation and release runs share one -main-scoped concurrency group. The manually dispatched preparation run cannot -trigger npm publication or create a Release: the action receives explicit -`skip-github-release=true`, it is accepted only when no merged -`autorelease: pending` PR exists, and `publish.yml` accepts only an upstream -`push` event. It must succeed after independently validating the one canonical -action-created 0.1.1 PR, including the unchanged-PR case where the action emits -no `prs` output. Before mutation, the workflow also rejects any open PR whose -head name could be mistaken for the canonical release branch, including a -same-named fork branch. -The `GITHUB_TOKEN`-created PR's `pull_request` CI starts in GitHub's -approval-required state. A human with write access must explicitly authorize -those workflow runs before their results can satisfy required checks; this is -separate from the final-head administrator review. -After the finalization topic PR removes the one-cycle `last-release-sha` and -completes the release-ready documentation on `main`, start a new first-attempt -manual dispatch. Require it to refresh the same action-owned release PR with -only the four generated release files and release notes identical to the -generated CHANGELOG section. Require the refreshed release commit to have the -post-finalization `main` commit as its direct parent; an unchanged older head is -not a refreshed candidate. Run the full matrix on that final head and obtain -approval from a different human repository administrator. The release-PR merge -creates the `push` run that may tag and publish. A later push cannot tag an older -outstanding release PR; its merge SHA must equal the triggering SHA before -Release Please runs. A rerun may retry that same candidate while no tag or -Release exists. If Release Please created the immutable Release but failed -before producing outputs, only the same run may recover it, and only after -proving its exact SHA, tag, bot author, immutable state, target, URL, notes, and -publication inside exactly one earlier Release Please step time window. Recovery -then idempotently removes `autorelease: pending`, -adds `autorelease: tagged`, and writes a schema-v2 artifact for that attempt. -Immediately before the irreversible Release Please call, every attempt also -reconfirms `main`, the release-branch snapshot, all PR collisions, the candidate -and final-head review, final release metadata and public documentation, and the -exact tag/Release state, including removal of the one-cycle `last-release-sha`. -Because workflow concurrency does not lock `main` or PR metadata against other -actors, the maintainer must hold a short mutation freeze from the release-PR -merge until the Release Please run reaches its post-action validation. Do not -merge another `main` PR, edit the release PR, change its labels or review, or -mutate the release branch during that window. The workflow repeats those checks -after the action and stops publication on any drift, but it cannot delete or -replace an immutable Release created during an external race. - -The stale branch at `3f0949e5c0ccd0923d10595437f7a315f013af7c` was revalidated -as the failed run's generated 0.2.0 evidence, with no associated open PR or -independent work, then deleted. Release Please recreated the canonical -`release-please--branches--main--components--cometapi` branch for the -action-owned 0.1.1 PR. Do not use that branch as a 0.2 starting point or delete -or rewrite any other branch. - -For 0.1.1, `always-bump-patch` keeps every releasable Conventional Commit on the -0.1.x maintenance line; changing that strategy requires a separately authorized -later milestone. A normal `fix:` commit after 0.1.0 must produce exactly one -patch PR. Stop if the branch contains 0.2.0, if any -version/manifest/changelog value is not 0.1.1, or if the generated PR is not -attributable to the explicit `cometapi` component. Merge is forbidden until -Node.js 22 and 24 blocking checks, the Node.js 26 advisory lane, -minimum/locked/latest OpenAI 6.x compatibility, -package and declaration checks, and human-owner review complete on the final -head. After registry verification, restore `RELEASE_PLEASE_ENABLED=false` and -keep the already enabled scheduled-smoke policy at `LIVE_SMOKE_ENABLED=true`. -Use a separate post-release documentation PR to record the ROADMAP and -RELEASING evidence; only that verified closeout may mark Repository foundation -Complete. +Before a stable patch operation, verify the standard `autorelease: pending` and +`autorelease: tagged` labels, `default_workflow_permissions=read`, Actions +pull-request creation authorization, no canonical-branch collision, and the +current external Environment and Trusted Publisher state. The workflow never +changes those settings; drift is a stop condition. Enable +`RELEASE_PLEASE_ENABLED`, start a new attempt-1 manual dispatch on `main`, and +never rerun a preparation dispatch. An unchanged candidate is revalidated by a +new dispatch. Manual preparation uses `skip-github-release=true` and is release- +and publication-inert. + +The action-created PR must contain only the four release files and exact +generated notes. A human with write access separately authorizes its CI through +**Approve and run workflows** when GitHub requires that gate. After all final- +head checks pass, a human repository administrator whose login differs from the +bot author must submit a formal exact-head `APPROVED` review. That +administrator's latest review must remain exact-head `APPROVED` through merge +and post-action validation; a later `COMMENTED` or `CHANGES_REQUESTED` review, +or any head change, invalidates the approval. + +The release-PR merge creates the only `push` run that may call Release Please in +release mode. From that merge through post-action validation, do not edit the +release PR, change its labels or review, or mutate its branch. Keep `main` frozen +at the release commit through successful registry verification and the final +variable and Environment-policy readback; every handoff, tag, and pre-publish +gate requires that exact identity. Do not start or rerun any other Release +Please workflow from the tag handoff through registry verification and final +readback because publication freezes the complete Release Please run set. A +rerun may retry the same release candidate only while no tag or Release exists. +If an earlier attempt of that same run already created the Release, same-run +reconciliation is allowed only after proving the exact run ID, SHA, tag, bot +author, immutable state, target, URL, notes, and publication time inside one +earlier Release Please step. It may only reconcile labels and write the +attempt-qualified result artifact. + +The successful Release Please `workflow_run` enters an unprivileged handoff, +which validates the exact result and immutable Release before dispatching +`publish.yml` with `ref=v`. Only the tag-bound dispatch may rebuild and +verify the artifact, run the fresh bounded live smoke, enter the npm +Environment, request OIDC, or verify the registry. The permanent npm Environment +policy set is exactly `tag:v*`. After registry verification, immediately restore +`RELEASE_PLEASE_ENABLED=false` and keep `LIVE_SMOKE_ENABLED=true`. + +Never substitute a manually authored release PR, manual or auxiliary tag, +branch-context publication, temporary `main` Environment policy, reused artifact +or live evidence, arbitrary rerun, or different patch version. An ambiguous npm +result requires exact registry integrity, signature, and provenance inspection; +it never authorizes an automatic retry. + +The `0.1.1` repair used the immutable `0.1.0` commit as a one-cycle +`last-release-sha` only for its initial preparation, then removed the anchor. +The failed run's exact generated `0.2.0` branch was verified as failure-only +evidence with no open PR or independent work before replacement by the +canonical action-owned `0.1.1` branch. Neither branch is a 0.2 starting point. +The one-time main-context npm recovery is historical evidence only; its complete +record appears below and its executable path was removed by PR #41. The `0.1.0` promotion limited Release Please to the stable PR because the pinned v5.0.0 action bundles Release Please 17.6.0 and its single-package path @@ -608,8 +580,8 @@ 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. +opened stable PR, and the repository had no `autorelease` labels at the time, 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 @@ -633,8 +605,8 @@ PRs, and normal Release Please tag and GitHub Release creation. Repository Actions pull-request authorization is now enabled for that scoped job; the workflow still uses only its default token and job-local permissions. -The recovery rules follow the pinned implementation rather than assuming the -action is atomic. Release Please 17.6.0 +The same-run Release reconciliation rules follow the pinned implementation +rather than assuming the action is atomic. Release Please 17.6.0 [creates the Release before PR comments and label changes](https://github.com/googleapis/release-please/blob/712fcf01effd08d7b0e7b1fd3861f2cb388bc8d1/src/manifest.ts#L1258-L1319), while the pinned action emits release outputs only after that call returns. An unchanged release PR may also return @@ -644,6 +616,94 @@ 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.1 release evidence + +Stable `0.1.1` completed on 2026-07-30 with these independently auditable +layers: + +- The action-authored release pull request + [#33](https://github.com/cometapi-dev/cometapi-node/pull/33) had final head + `132d158c5bc4b83d582dd0a3c7677b05b46d471b`. Its complete final-head matrix + passed in [CI run 30443300601 attempt 2](https://github.com/cometapi-dev/cometapi-node/actions/runs/30443300601/attempts/2) + and the latest-compatible/manual matrix passed in + [run 30468358086](https://github.com/cometapi-dev/cometapi-node/actions/runs/30468358086). + Human repository administrator `tensornull`, distinct from bot author + `github-actions[bot]`, submitted formal + [review 4810328062](https://github.com/cometapi-dev/cometapi-node/pull/33#pullrequestreview-4810328062) + with `state=APPROVED` against that exact head before merge. +- The reviewed merge produced + [`c98b514227858cd183c781270a7f78f65b577e82`](https://github.com/cometapi-dev/cometapi-node/commit/c98b514227858cd183c781270a7f78f65b577e82). + [Release Please run 30469181724 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30469181724/attempts/1) + created, rather than recovered, the exact lightweight `v0.1.1` tag and + immutable non-prerelease GitHub Release ID `361883325`. The + [`v0.1.1` Release](https://github.com/cometapi-dev/cometapi-node/releases/tag/v0.1.1) + is bot-authored, targets that merge commit, and was published at + `2026-07-29T16:07:15Z`. +- The initial + [Publish run 30469240186](https://github.com/cometapi-dev/cometapi-node/actions/runs/30469240186) + failed before packing, live smoke, OIDC, or npm mutation. Its downloaded + `release-please-result/result.json` was inside the workspace scanned by + `npm run format:check`, and Prettier correctly returned non-zero for that + runtime JSON file. +- [Run 30471665743 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30471665743/attempts/1) + then completed all offline and exact-artifact checks. Its + [live job 90643725110](https://github.com/cometapi-dev/cometapi-node/actions/runs/30471665743/job/90643725110) + checked out the exact release commit and passed 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. The npm job received no + runner and no OIDC token: GitHub's check annotation states that branch `main` + was not allowed by the tag-only npm Environment policy. +- That failed run retained artifact ID `8731956162`, named + `npm-package-0.1.1-30471665743-1`, with ZIP digest + `sha256:567b00f1ec32168d5c5be7d0b553542441920d3bb401959bcc2d6e157f35d08b`. + It contains only `cometapi-0.1.1.tgz`; the tarball has SHA-256 + `3c926a2b15be99fbba92e1e100c2ee254ff866da27496a5c31824c542cccbf91`. + Artifact metadata names recovery-control head `22c313d4f80c53ba01672dd35cc27b621d5ec9ce`, + while Actions logs prove that packaging and live validation checked out + release commit `c98b514227858cd183c781270a7f78f65b577e82`. +- The authorized one-time control + [PR #40](https://github.com/cometapi-dev/cometapi-node/pull/40) merged as + `37b811c54773295487aa4200f349ec3edd30d729`. + [Publish run 30533520823 attempt 1](https://github.com/cometapi-dev/cometapi-node/actions/runs/30533520823/attempts/1) + revalidated and published the exact retained artifact while reusing the + already successful bounded-live evidence rather than spending another live + request budget. Its + [npm job 90841672147](https://github.com/cometapi-dev/cometapi-node/actions/runs/30533520823/job/90841672147) + used GitHub Actions OIDC and completed the public-registry gates. +- npm now resolves `latest=0.1.1` and `next=0.1.0-alpha.3`. The registry tarball + is byte-identical to the source artifact and has SHA-1 + `00edad522c9ffaf937facbe5a35ef211869551c1` and integrity + `sha512-uYo573XD+ITsa8F4GbYLAlXMrj9SA1Qc4KBgvoRbnwwTvfX+Ye8QVo7xgSNOl9AoYpoglQCW8lEo9cvjwan+7Q==`. + `npm audit signatures` passed. npm exposes both its publish attestation + ([Sigstore index 2289305373](https://search.sigstore.dev/?logIndex=2289305373)) + and SLSA provenance + ([index 2289305033](https://search.sigstore.dev/?logIndex=2289305033)). + The provenance binds `cometapi@0.1.1` to `refs/heads/main`, control commit + `37b811c54773295487aa4200f349ec3edd30d729`, and Publish run + `30533520823/1`; it does not claim tag-bound publication. +- A separate clean public-registry installation on Node.js `24.18.1` passed ESM, + CommonJS, `.mts` and `.cts` declarations, all three supported mocked + operations including streaming and errors, one effective OpenAI installation, + official `APIError instanceof` identity, integrity, signature, and both + attestations. +- [Cleanup PR #41](https://github.com/cometapi-dev/cometapi-node/pull/41) + removed every one-time recovery input, fixed evidence identifier, + prior-artifact/live reuse branch, and temporary `main` policy path. Its final + head `c5566246abce065a39f1f66ed2b6e2d4bc89e62f` passed + [PR CI 30538011343](https://github.com/cometapi-dev/cometapi-node/actions/runs/30538011343), + merged as `c319503684b371ad4a4f1ce78a156978de86072e`, and passed + [default-branch CI 30538123153](https://github.com/cometapi-dev/cometapi-node/actions/runs/30538123153). + Post-release state was read back as `RELEASE_PLEASE_ENABLED=false`, + `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. + ## Stable 0.1.0 release evidence Stable `0.1.0` completed on 2026-07-28 with these independently auditable @@ -668,8 +728,8 @@ layers: 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 +- At the `0.1.0` closeout, npm's `latest` dist-tag resolved to `0.1.0`, while + `next` remained 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 diff --git a/ROADMAP.md b/ROADMAP.md index 0bd7d79..bc74e34 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,13 +1,13 @@ # CometAPI TypeScript and Node.js SDK Roadmap -Status: 0.1.1 options-contract and Release Please maintenance in progress -Last updated: 2026-07-29 +Status: Stable 0.1.1 and Repository foundation complete +Last updated: 2026-07-30 Repository contract: This roadmap is self-contained and is the public source of truth for this repository's release sequence. -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. +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. ## Product Target @@ -23,22 +23,22 @@ 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. Stable `0.1.0` is available from npm's +available from npm's `next` channel. Stable `0.1.1` is available from npm's default `latest` channel with verified provenance and public-install evidence. ## Milestones -| Milestone | Status | User outcome | -| -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| Repository foundation | In progress | The repository has reproducible development, contribution, security, and release processes. | -| 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 | Complete | Users can install a fully verified package from npm's default channel. | -| 0.1.1 maintenance patch | In progress | Users receive the corrected public options contract through the repaired, reviewed normal release 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. | +| Milestone | Status | User outcome | +| -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| Repository foundation | Complete | The repository has reproducible development, contribution, security, and release processes. | +| 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 | 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.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. | ## Repository Foundation @@ -95,48 +95,35 @@ 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`. The post-merge Release -Please [run 30345116433](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345116433) -ran after a draft `v0.1.0` Release had been created but before that draft was -published or had a tag. With no discoverable Release Please release boundary, -it scanned older Conventional Commits, including the initial feature, and -generated an unrequested `0.2.0` temporary branch commit. Pull-request creation -then failed independently because the repository did not authorize GitHub -Actions to create or approve pull requests at that time. The run did not change -`main`, create a tag or published Release, or publish to npm. - -The 0.1.1 maintenance work makes the component and stable-patch policy -explicit, used the exact 0.1.0 release commit to anchor only the initial repair -dispatch, and restores Release Please ownership of the reviewed -version/changelog PR plus the immutable tag and GitHub Release. A normal topic -PR removes that temporary anchor and records final candidate approval before a -fresh preparation dispatch refreshes the action-owned release PR. The scoped -Release Please job now uses the repository's enabled Actions PR authorization -to create and label the normal PR; -a human owner reviews its exact final head. Default workflow permissions remain -read-only, bot approval is never accepted, and the workflow does not modify the -repository setting. Patch-only versioning prevents an implicit 0.2 bump during -this maintenance window. The explicit component identifies the temporary -branch but, for this root package, does not enter the Release Please title or public tag; -the only accepted patch tag is `v0.1.1`. Publication is triggered from the -successful attempt-qualified Release Please push run and independently verifies -that run's schema-v2 result artifact, default-branch commit, tag, immutable -Release, and package artifact before the existing bounded live smoke and npm -OIDC steps. A push rerun is bounded to the same run ID, SHA, candidate, -Release-producing -attempt, and exact Release state; manual preparation remains attempt-1-only. -The Release notes must equal the reviewed `CHANGELOG` entry. The post-merge run -also requires an administrator's approval on the release PR's final head. - -The exact stale 0.2 branch was revalidated as failure-only evidence with no -associated PR or independent work, then deleted. Release Please recreated the -canonical branch for the action-owned 0.1.1 PR; it must never be treated as the -start of 0.2. Repository foundation may become Complete only after the real -0.1.1 release flow, public -registry installation, and a separate post-release documentation PR recording -ROADMAP and RELEASING evidence succeed. Until then, -`RELEASE_PLEASE_ENABLED` remains a temporary release-operation control, -`latest` remains `0.1.0`, and `next` remains `0.1.0-alpha.3`. +The failed post-`0.1.0` Release Please +[run 30345116433](https://github.com/cometapi-dev/cometapi-node/actions/runs/30345116433) +had no published tag boundary to discover, generated an unrequested `0.2.0` +temporary-branch commit, and then encountered a separate Actions pull-request +authorization failure. The `0.1.1` repair made the `cometapi` component and +patch-only versioning explicit, anchored only its initial preparation to the +immutable `0.1.0` commit, and restored Release Please ownership of the reviewed +version/changelog PR, tag, and immutable GitHub Release. The stale branch was +verified as failure-only evidence before replacement; it is not a 0.2 base. + +Release Please created the action-authored, exact-head-approved `0.1.1` release +PR and immutable `v0.1.1` Release. Two publication runs then stopped before npm +mutation: one because a downloaded result file entered the formatting scan, and +one because a main-context deployment could not enter the tag-only npm +Environment. The explicitly authorized one-time recovery reused only the exact +already verified artifact and bounded live evidence, then published through npm +OIDC. [PR #41](https://github.com/cometapi-dev/cometapi-node/pull/41) removed +every fixed recovery input, prior-evidence reuse branch, and temporary `main` +policy path. + +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). ## Private Remote Validation @@ -274,41 +261,44 @@ Explicit non-goals: - Provider-neutral message translation. - Image, video, audio, batch, fine-tuning, and realtime APIs. -## 0.1.1: Options Contract and Release Repair +## 0.1.1: Options Contract and Release Repair (Complete) -This maintenance patch aligns the declarations with the supported 0.1 runtime +Stable `0.1.1` aligns the declarations with the supported 0.1 runtime boundary. `CometAPIOptions` and `withOptions` exclude `provider`, `workloadIdentity`, and `dangerouslyAllowBrowser`; runtime objects that bypass the declarations receive a secret-free official `OpenAIError`. Existing transport, observability, organization, project, webhook, and admin-key options remain available. The supported resource list does not change. -The patch also restores a normal stable Release Please path with explicit -component identity, patch versioning, pull-request configuration, one-cycle -0.1.0 history anchoring, normal `v0.1.1` tag and immutable GitHub Release -creation, and a trusted `workflow_run` handoff to the existing exact-artifact, -bounded-live, and npm OIDC gates. Regression tests must reject stale manifest -state, a 0.2 bump, missing PR configuration, an unrelated stale branch, hostile -workflow events, unsafe or mismatched recovery attempts, mismatched action -outputs, missing final-head approval, and declaration or runtime option -bypasses. +The patch also installs the permanent stable Release Please path with explicit +component identity, patch versioning, pull-request configuration, normal +`v0.1.1` tag and immutable GitHub Release creation, and a trusted `workflow_run` +handoff to immutable-tag-only exact-artifact, bounded-live, and npm OIDC gates. +Its initial preparation used and then removed a one-cycle `0.1.0` history +anchor; that anchor is not part of the permanent configuration. Regression +tests reject stale manifest state, a 0.2 bump, missing PR configuration, an +unrelated stale branch, hostile workflow events, unsafe or mismatched same-run +Release reconciliation attempts, mismatched action outputs, missing final-head +approval, and declaration or runtime option bypasses. -Exit criteria: +Completion evidence: - Source and packed ESM/CommonJS declarations pass executed TypeScript negative tests, while runtime bypass tests preserve official error identity and do not expose option values. -- The repair PR and generated 0.1.1 release PR pass required CI on their exact - final heads, and the release PR receives human-owner review. -- Release Please creates the exact immutable `v0.1.1` Release; the existing - three-request live smoke and npm OIDC publication pass without changing - `next=0.1.0-alpha.3`. +- The repair PR and generated `0.1.1` release PR passed required CI on their + exact final heads, and a distinct human administrator formally approved the + action-authored release PR's final head. +- Release Please created the exact immutable `v0.1.1` Release. The bounded + three-request live smoke and npm OIDC publication completed through the + disclosed one-time recovery without changing `next=0.1.0-alpha.3`. - A public-registry install verifies ESM, CommonJS, declarations, supported mocked calls, one effective OpenAI installation, API error identity, integrity, signatures, and provenance. -- After publication, maintainers restore `RELEASE_PLEASE_ENABLED=false` while - keeping `LIVE_SMOKE_ENABLED=true`. A separate post-release documentation PR - records the evidence and only then marks Repository foundation Complete. +- After publication, maintainers restored `RELEASE_PLEASE_ENABLED=false`, kept + `LIVE_SMOKE_ENABLED=true`, restored the sole `tag:v*` policy, and merged the + recovery-path cleanup. The evidence is recorded in + [RELEASING.md](./RELEASING.md#stable-011-release-evidence). ## 0.2.0: Provider-Native Text Adapters @@ -373,14 +363,17 @@ The repository will maintain: - `release-please.yml` for the reviewed version and changelog PR and the corresponding immutable tag and GitHub Release. - `publish.yml` for trusted Release Please completion, immutable-release and - `main`-ancestry enforcement, exact - tarball verification, a protected release-tag live smoke, npm OIDC - publication, and dist-tag, integrity, provenance, signature, and registry - verification. - -All workflow files must pass local `actionlint`. Until each workflow executes -successfully in the actual GitHub repository, release reports must state that -remote Actions behavior remains unverified. + `main`-ancestry enforcement, an unprivileged handoff to the exact immutable + tag, exact tarball verification, a fresh protected release-tag live smoke, + npm OIDC publication, and dist-tag, integrity, provenance, signature, and + 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. 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 @@ -411,12 +404,19 @@ versioning and the `cometapi` component, an action-created and human-reviewed Release Please PR, and automated immutable tag and GitHub Release creation after merge. Because the default `GITHUB_TOKEN` cannot cause a second workflow through a `release.published` event, `publish.yml` starts from successful Release Please -workflow completion and re-establishes trust from exact repository state. -Failed pull-request preparation runs are filtered out; any successful run -without a schema-v2 attempt-bound release result, the exact tag, and immutable -Release fails before live or registry access. Only a successful canonical -attempt-qualified `push` run for the still-current exact `main` SHA can enter -artifact verification. A push retry may recover only the same run ID, SHA, +workflow completion and re-establishes trust from exact repository state. The +main-context `workflow_run` can enter only an unprivileged handoff, which +validates the attempt-bound result, immutable Release, tag, and current `main`, +then dispatches the same workflow with `ref=v`. Verification, live +smoke, the npm Environment, and OIDC are reachable only from that tag-bound +`workflow_dispatch`. +Failed pull-request preparation runs are filtered out, while a successful +preparation run whose result-upload step was skipped remains release-inert. Any +purported release handoff without a schema-v2 attempt-bound result, the exact +tag, and immutable Release fails before live or registry access. Only a +successful canonical +attempt-qualified `push` run for the still-current exact `main` SHA can create +the tag handoff. A push retry may reconcile only the same run ID, SHA, candidate, and exact bot-authored immutable Release published inside one earlier Release Please step; manual preparation reruns remain forbidden.