fix: harden release metadata and runtime

Author: CometAPI

.github/workflows/publish.yml

@@ -45,7 +45,7 @@ jobs:
     steps:
       - name: Open or update the release PR, or create its approved release
         id: release
-        uses: googleapis/release-please-action@5c625bfb5d1ff62eadeeb3772007f7f66fdcf071 # v4.4.1
+        uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0, node24
         with:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json

AGENTS.md

@@ -152,6 +152,16 @@ Post-stable invariants:
    direct dependency's `result` to equal `success`. A skipped, cancelled,
    failed, or missing dependency must never make build, live smoke,
    publication, or registry verification eligible.
+9. Keep Release Please pinned to the reviewed `v5.0.0` commit
+   `45996ed1f6d02564a971a2fa1b5860e934307cf7`, whose immutable action metadata
+   uses `node24`. The workflow semantic checker must reject any different pin.
+10. `README.md` is the distribution long description and must remain accurate
+    before and after publication. Use `python -m pip install cometapi`,
+    unversioned project links, and publication-neutral maintenance language.
+    Reject approval, unpublished, exact-version installation, and versioned
+    release-link text in both source and built artifact metadata, and require
+    each built long description to exactly match the source README. Post-release
+    evidence changes must not rewrite README release state.
 
 ## Repository independence
 
@@ -329,7 +339,9 @@ committed.
   evaluate skipped ancestry, reject cancellation and reruns, and require each
   direct dependency to succeed.
 - Keep README, roadmap, compatibility matrix, examples, and changelog aligned
-  with shipped behavior. Use currently supported model IDs.
+  with shipped behavior. README installation and availability guidance must be
+  publication-neutral because it is embedded in immutable distribution
+  metadata. Use currently supported model IDs.
 - All repository documentation is written in English.
 
 The Public Preview readiness record requires

ARCHITECTURE.md

@@ -128,6 +128,18 @@ local mocked/package evidence
     -> public registry digest, provenance, install, import, and mocked smoke
 ```
 
+The package metadata embeds `README.md` as its long description. Because wheel,
+sdist, and PyPI metadata are immutable, the README uses an unversioned install
+command and publication-neutral release language that remains accurate before
+and after a release. Source-document and artifact checks reject approval,
+unpublished, exact-version installation, and versioned release-link text; each
+artifact long description must also exactly match the source README.
+
+Release Please is pinned to the immutable `v5.0.0` commit whose action metadata
+uses `node24`. The workflow semantic contract fixes that SHA and runtime
+disposition so GitHub does not need to force a deprecated Node 20 action onto a
+newer runtime.
+
 This complete trust chain executed successfully in
 [release workflow run 30261746138](https://github.com/cometapi-dev/cometapi-python/actions/runs/30261746138)
 for release commit `31b68904141489ca04932edbf305ccf88af09372`, recovery tag

CHANGELOG.md

@@ -6,6 +6,13 @@ automation.
 
 ## [Unreleased]
 
+### Fixed
+
+- Pin Release Please to its reviewed Node 24 action and reject regressions to
+  the deprecated Node 20 runtime.
+- Keep the README and built distribution long description publication-neutral,
+  with an unpinned stable installation command and no transient approval state.
+
 ### Documentation
 
 - Record completed `0.1.1` publication, live, provenance, digest, and

README.md

@@ -1,6 +1,6 @@
 # CometAPI Python SDK
 
-> **Stable release:** `0.1.1` is available from PyPI.
+> **Stable release line:** `0.1.x` maintenance releases are available from PyPI.
 
 `cometapi` is a thin Python adapter over the official OpenAI SDK for the
 OpenAI-compatible CometAPI endpoint. It changes the default API key and base
@@ -29,16 +29,14 @@ Project links: [CometAPI](https://www.cometapi.com),
 
 ## Installation
 
-Install the independently verified stable release from PyPI with:
+Install the latest stable release from PyPI with:
 
 ```bash
-python -m pip install 'cometapi==0.1.1'
+python -m pip install cometapi
 ```
 
-The immutable
-[GitHub release](https://github.com/cometapi-dev/cometapi-python/releases/tag/v0.1.1)
-and exact [PyPI release](https://pypi.org/project/cometapi/0.1.1/) record the
-published artifact.
+See the [CometAPI package on PyPI](https://pypi.org/project/cometapi/) for the
+current stable distribution and release history.
 
 ## Authentication and configuration
 

RELEASING.md

@@ -167,11 +167,26 @@ secret separation, and checkout-before-bundle-download ordering. Its git-backed
 tests exercise accepted and rejected release histories locally; they still do
 not emulate GitHub Actions.
 
+The Release Please step is pinned to
+`googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7`
+(`v5.0.0`), whose immutable action metadata selects `node24`. The semantic
+checker rejects any other pin so the workflow cannot silently regress to the
+deprecated Node 20 runtime.
+
 Release mode (`check_version.py --require-releasable-docs`) also fails closed
 until project authorship, the canonical GitHub repository URL, the copyright
-holder, security and support contacts, and the approved README/changelog
-release state are present. Public Preview validation reports all discovered
-violations in one run and still returns non-zero when any violation exists.
+holder, security and support contacts, a publication-neutral README, and a dated
+changelog release section are present. Public Preview validation reports all
+discovered violations in one run and still returns non-zero when any violation
+exists.
+
+`pyproject.toml` embeds `README.md` as the immutable distribution long
+description. The README therefore uses the unpinned
+`python -m pip install cometapi` command and unversioned project links. Release
+PRs and post-release evidence changes must not introduce approval, unpublished,
+or exact-version availability statements. Artifact inspection applies the same
+policy to wheel `METADATA` and sdist `PKG-INFO`, so source and registry-facing
+descriptions cannot drift.
 
 ## Workflow responsibilities
 
@@ -326,7 +341,7 @@ feature or fix pull request
     -> required offline CI
     -> merge to the default branch
     -> automated release pull request
-    -> human finalization of stable docs, metadata, and one-time bridge cleanup
+    -> human review of generated versions, changelog, and durable metadata
     -> required release-PR CI, review, and merge
     -> immutable tag and GitHub release
     -> bounded API verification of immutable tag and commit identity
@@ -340,15 +355,15 @@ feature or fix pull request
     -> roadmap milestone marked released
 ```
 
-Stable `0.1.0` additionally requires the complete blocking Python matrix,
+Stable `0.1.0` additionally required the complete blocking Python matrix,
 executed README examples against the built package, trusted live evidence, and
-reviewed release-PR and changelog agreement. Before the stable release PR is
-merged, its finalization commit must state that `0.1.0` is approved for PyPI
-publication, use the stable installation command and classifier, and remove the
-one-time `last-release-sha` plus prerelease-versioning controls. The manifest,
+reviewed release-PR and changelog agreement. Its one-time finalization removed
+the `last-release-sha` and prerelease-versioning controls. Later maintenance
+releases keep those controls absent and must retain publication-neutral README
+metadata throughout the release and post-release sequence. The manifest,
 project metadata, lock file, and changelog must remain at the exact generated
-`0.1.0` version. If GitHub requires approval before checks run on the automated
-pull request, approve only that reviewed workflow execution and wait for every
+version. If GitHub requires approval before checks run on the automated pull
+request, approve only that reviewed workflow execution and wait for every
 blocking check.
 
 ## Immutable release publication recovery

ROADMAP.md

@@ -346,8 +346,9 @@ Public Preview remains ready only while:
   self-review.
 - Default-branch CI is rerun successfully after the public configuration.
 - The fail-closed content gate reports all violations together and then passes,
-  repository self-containment and package gates pass, and the README accurately
-  states prerelease and registry availability.
+  repository self-containment and package gates pass, and the README uses
+  publication-neutral stable installation guidance suitable for immutable
+  distribution metadata.
 - An explicitly authorized protected live smoke passes within the four-request,
   16-output-token, 30-second-per-request, concurrency-one, stop-on-first-failure
   budget.

scripts/_checks.py

@@ -8,6 +8,7 @@
 import sys
 from collections.abc import Iterable
 from email.message import Message
+from email.parser import Parser
 from pathlib import Path
 from typing import cast
 
@@ -31,6 +32,26 @@
     "Support": f"{CANONICAL_REPOSITORY}/blob/main/SUPPORT.md",
     "Security": CANONICAL_SECURITY,
 }
+PUBLIC_README_INSTALL_COMMAND = "python -m pip install cometapi"
+PUBLIC_README_FORBIDDEN_PATTERNS = (
+    (r"(?i)\bpending[\s-]+owner(?:ship|s)?\b", "pending owner identity"),
+    (r"(?i)\bapproved\s+for\s+pypi\s+publication\b", "publication approval state"),
+    (r"(?i)\b(?:candidate|unreleased|unpublished)\b", "unpublished release state"),
+    (r"(?i)\bno\s+pypi\s+publication\b", "missing PyPI publication"),
+    (r"(?i)\b(?:has\s+)?not\s+been\s+published\b", "unpublished release state"),
+    (
+        r"(?i)\bdo\s+not\s+treat\b[^\n]*\bcurrently\s+available\b",
+        "temporary availability warning",
+    ),
+    (r"(?i)\blocal\s+candidate\b", "local-candidate narrative"),
+    (r"(?i)\b0\.1\.\d+(?:a\d+)?\s+is\s+(?:available|approved)\b", "versioned release state"),
+    (r"(?i)cometapi==\d+\.\d+\.\d+(?:a\d+)?", "version-pinned installation command"),
+    (r"https://pypi\.org/project/cometapi/\d", "versioned PyPI release link"),
+    (
+        r"https://github\.com/cometapi-dev/cometapi-python/releases/tag/v\d",
+        "versioned GitHub release link",
+    ),
+)
 
 
 class CheckError(RuntimeError):
@@ -96,25 +117,37 @@ def sha256_file(path: Path) -> str:
 
 def parse_metadata(raw: bytes, source: str) -> Message:
     """Parse package core metadata and require its identity fields."""
-    message = Message()
-    text = raw.decode("utf-8")
-    for line in text.splitlines():
-        if not line.strip():
-            break
-        if line[0].isspace():
-            current = message.get_payload()
-            message.set_payload(f"{current}\n{line}" if current else line)
-            continue
-        name, separator, value = line.partition(":")
-        if separator:
-            message[name] = value.strip()
+    try:
+        message = Parser().parsestr(raw.decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as exc:
+        raise CheckError(f"{source}: invalid metadata: {exc}") from exc
     if message.get("Name") != DIST_NAME:
         raise CheckError(f"{source}: expected Name: {DIST_NAME!r}")
     if message.get("Version") is None:
         raise CheckError(f"{source}: missing Version metadata")
     return message
 
 
+def metadata_description(message: Message, source: str) -> str:
+    """Return the rendered long description from a distribution metadata message."""
+    payload = message.get_payload()
+    if not isinstance(payload, str) or not payload.strip():
+        raise CheckError(f"{source}: missing long description metadata")
+    return payload
+
+
+def public_readme_release_violations(text: str) -> list[str]:
+    """Return transient or version-specific release statements in public README text."""
+    return [
+        label for pattern, label in PUBLIC_README_FORBIDDEN_PATTERNS if re.search(pattern, text)
+    ]
+
+
+def public_readme_has_install_command(text: str) -> bool:
+    """Return whether the public README contains the exact unpinned install command."""
+    return any(line.strip() == PUBLIC_README_INSTALL_COMMAND for line in text.splitlines())
+
+
 def require_equal_versions(items: Iterable[tuple[str, str]]) -> str:
     """Require all named version values to normalize to the same version."""
     normalized = [(name, normalize_version(value)) for name, value in items]

scripts/check_artifacts.py

@@ -9,15 +9,36 @@
 import zipfile
 from pathlib import Path, PurePosixPath
 
-from _checks import (
-    CANONICAL_AUTHOR,
-    CANONICAL_PROJECT_URLS,
-    CheckError,
-    normalize_version,
-    parse_metadata,
-    read_project_version,
-    sha256_file,
-)
+try:
+    from ._checks import (
+        CANONICAL_AUTHOR,
+        CANONICAL_PROJECT_URLS,
+        PROJECT_ROOT,
+        PUBLIC_README_INSTALL_COMMAND,
+        CheckError,
+        metadata_description,
+        normalize_version,
+        parse_metadata,
+        public_readme_has_install_command,
+        public_readme_release_violations,
+        read_project_version,
+        sha256_file,
+    )
+except ImportError:  # Direct execution from the repository root.
+    from _checks import (
+        CANONICAL_AUTHOR,
+        CANONICAL_PROJECT_URLS,
+        PROJECT_ROOT,
+        PUBLIC_README_INSTALL_COMMAND,
+        CheckError,
+        metadata_description,
+        normalize_version,
+        parse_metadata,
+        public_readme_has_install_command,
+        public_readme_release_violations,
+        read_project_version,
+        sha256_file,
+    )
 
 REQUIRED_PACKAGE_FILES = {
     "cometapi/__init__.py",
@@ -88,7 +109,12 @@ def _safe_path(name: str, source: Path) -> PurePosixPath:
     return path
 
 
-def _check_metadata(raw: bytes, source: str, expected_version: str) -> None:
+def check_metadata(
+    raw: bytes,
+    source: str,
+    expected_version: str,
+    expected_description: str,
+) -> None:
     metadata = parse_metadata(raw, source)
     actual_version = normalize_version(str(metadata["Version"]))
     if actual_version != expected_version:
@@ -114,9 +140,23 @@ def _check_metadata(raw: bytes, source: str, expected_version: str) -> None:
     for label, expected in CANONICAL_PROJECT_URLS.items():
         if project_urls.get(label) != expected:
             raise CheckError(f"{source}: expected Project-URL {label}, {expected}")
+    description = metadata_description(metadata, source)
+    if description != expected_description:
+        raise CheckError(f"{source}: long description does not exactly match source README.md")
+    violations = public_readme_release_violations(description)
+    if violations:
+        raise CheckError(
+            f"{source}: long description contains publication-specific release text: "
+            + ", ".join(sorted(set(violations)))
+        )
+    if not public_readme_has_install_command(description):
+        raise CheckError(
+            f"{source}: long description must contain the unpinned stable install command "
+            f"{PUBLIC_README_INSTALL_COMMAND!r}"
+        )
 
 
-def _check_wheel(path: Path, expected_version: str) -> None:
+def _check_wheel(path: Path, expected_version: str, expected_description: str) -> None:
     expected_fragment = f"cometapi-{expected_version}-"
     if expected_fragment not in path.name:
         raise CheckError(f"{path.name}: filename does not contain {expected_fragment!r}")
@@ -142,16 +182,19 @@ def _check_wheel(path: Path, expected_version: str) -> None:
         metadata_names = [name for name in names if name.endswith(".dist-info/METADATA")]
         if len(metadata_names) != 1:
             raise CheckError(f"{path.name}: expected exactly one .dist-info/METADATA")
-        _check_metadata(
-            archive.read(metadata_names[0]), f"{path.name}:{metadata_names[0]}", expected_version
+        check_metadata(
+            archive.read(metadata_names[0]),
+            f"{path.name}:{metadata_names[0]}",
+            expected_version,
+            expected_description,
         )
         for source_name in ("cometapi/__init__.py", "cometapi/client.py"):
             text = archive.read(source_name).decode("utf-8")
             if re.search(r"\b(?:CometClient|AsyncCometClient)\b", text):
                 raise CheckError(f"{path.name}:{source_name}: legacy public client name remains")
 
 
-def _check_sdist(path: Path, expected_version: str) -> None:
+def _check_sdist(path: Path, expected_version: str, expected_description: str) -> None:
     expected_root = f"cometapi-{expected_version}"
     if path.name != f"{expected_root}.tar.gz":
         raise CheckError(f"{path.name}: expected sdist filename {expected_root}.tar.gz")
@@ -182,7 +225,12 @@ def _check_sdist(path: Path, expected_version: str) -> None:
         stream = archive.extractfile(metadata_members[0])
         if stream is None:
             raise CheckError(f"{path.name}: cannot read PKG-INFO")
-        _check_metadata(stream.read(), f"{path.name}:PKG-INFO", expected_version)
+        check_metadata(
+            stream.read(),
+            f"{path.name}:PKG-INFO",
+            expected_version,
+            expected_description,
+        )
 
 
 def _artifacts(arguments: list[str]) -> list[Path]:
@@ -206,12 +254,16 @@ def main() -> int:
     parser.add_argument("--expected-version", default=read_project_version())
     args = parser.parse_args()
     expected_version = normalize_version(args.expected_version)
+    try:
+        expected_description = (PROJECT_ROOT / "README.md").read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise CheckError(f"cannot read source README.md: {exc}") from exc
     paths = _artifacts(args.artifacts)
     for path in paths:
         if path.suffix == ".whl":
-            _check_wheel(path, expected_version)
+            _check_wheel(path, expected_version, expected_description)
         else:
-            _check_sdist(path, expected_version)
+            _check_sdist(path, expected_version, expected_description)
         print(f"{sha256_file(path)}  {path}")
     print(f"artifact checks passed for cometapi {expected_version}")
     return 0