From 85cb466892f8af71c4eeb0ea5c4f622721f52413 Mon Sep 17 00:00:00 2001 From: sammiller Date: Tue, 22 Sep 2026 03:06:21 -0700 Subject: [PATCH 1/2] docs: record complete WP03.00 publication and OIDC transition [skip ci] --- .github/PULL_REQUEST_TEMPLATE.md | 2 +- docs/consuming.md | 41 +++++++++++------- docs/releasing.md | 72 ++++++++++++++++++++++++-------- 3 files changed, 80 insertions(+), 35 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e38f1bd..cdbf7cd 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -9,7 +9,7 @@ List the checks actually run and link relevant CI evidence. - [ ] Generated output and dependency locks are current. - [ ] Wire/API compatibility and licence declarations were checked. - [ ] New reused/generated material has a reviewed ten-field provenance record, exact file inventory and retained notices; used records were not edited. -- [ ] Package or CI changes passed the isolated archive consumer checks. +- [ ] Package or CI changes passed the necessary candidate packaging, targeted offline checks and publication-handoff identity checks. Runtime consumers remain optional local diagnostics under P2-017. - [ ] Documentation reflects any consumer or release setup changes. Mark non-applicable items explicitly. Do not equate CI artifacts with a registry diff --git a/docs/consuming.md b/docs/consuming.md index f42886b..b5a171a 100644 --- a/docs/consuming.md +++ b/docs/consuming.md @@ -1,10 +1,13 @@ # Installing and using the packages Choose a version whose main CI candidate and relevant registry job both passed. -The release manifest supplies the exact common version. An Actions artifact named -candidate is a tested archive; it becomes a registry package only after upload. -Versions such as `1.0.0-ci.12.1` below are illustrative, not an assertion that -this version exists. +The release manifest supplies the exact NuGet/npm version and the separate +Maven channel version. An Actions artifact named candidate is a tested archive; +it becomes a registry package only after upload. Versions such as +`1.0.0-ci.12.1` and the formal Maven version `1.0.0` below are illustrative, not +assertions that those releases exist. The +[accepted WP03.00 publication](releasing.md#wp0300-accepted-publication) +records the complete published set and its channel identities. ## C# @@ -60,10 +63,13 @@ service implementation, TLS endpoint and authentication. ## TypeScript / Web The default npm package page and a fresh install without a version follow -`latest`, which CI advances to the newest published main build. Check that both -npm publication results passed and use their common version; registry uploads -are not an atomic operation across packages. Moving `latest` does not rewrite an -existing application's dependency version or lock file. +`latest`. Before the first stable release, CI advances it to the newest published +main build; afterwards, stable releases own `latest` and main builds use `ci`. +Check that publication succeeded for every package in the producer catalog and +use the accepted common version for the packages your application consumes; +registry uploads are not atomic across packages. Moving a tag does not rewrite +an existing application's dependency version or lock file. Public Web clients +must not import the private AI or operator packages. Install exact package versions and commit the application's lock: @@ -90,13 +96,16 @@ Generated service descriptors also work with the caller's compatible transport. ### gRPC-Web for the Worker ingress -Use `contracts-connect-client` with the exact version from a successful Maven -publication containing that module. The version shown here is an example, not -an already published Connect client release. Add `mavenCentral()`: +Use `contracts-connect-client` with an exact formal version from a successful +Maven Central publication containing that module. The version shown here is an +example, not an already published formal release. Main currently publishes +`1.0.0-SNAPSHOT` through the separate [development channel](maven-central.md); +its NuGet/npm CI version is not a Maven Central release coordinate. For a +published formal release, add `mavenCentral()`: ```kotlin dependencies { - implementation("io.github.arcforges:contracts-connect-client:1.0.0-ci.12.1") + implementation("io.github.arcforges:contracts-connect-client:1.0.0") implementation("com.connectrpc:connect-kotlin-okhttp:0.9.0") implementation("com.connectrpc:connect-kotlin-google-javalite-ext:0.9.0") } @@ -137,10 +146,10 @@ suspend fun hello(): String = client.sayHello( ).getOrThrow().message ``` -The URL illustrates the Worker route intended for the next Cloud/Mobile -integration step. This PR tests a loopback C# service, including the `/api` prefix; -it does not establish that deployment or Android device behavior. Do not use the -Connect protocol default against ASP.NET gRPC. Keep request compression disabled +The URL illustrates the public Worker ingress. Historical local loopback +diagnostics covered the `/api` prefix; this producer candidate does not establish +current Cloud deployment or Android device behavior. Do not use the Connect +protocol default against ASP.NET gRPC. Keep request compression disabled (the default) for the current Hello ingress. The application owns credentials, TLS, coroutine cancellation and transport cleanup. Use JDK/JVM target 17 or newer and Kotlin 2.4.20 or a compatible compiler; Android also needs INTERNET permission. diff --git a/docs/releasing.md b/docs/releasing.md index 3c26a31..9717391 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -38,9 +38,11 @@ in branch protection before merging. These GitHub-side settings are configured for this repository, including the CI/security checks (including Java/Kotlin CodeQL) and PR requirement on main (zero required review -approvals). Initial setup used disabled publisher switches. Normal operation now -uses `NUGET_PUBLISH_ENABLED=true` and `NPM_PUBLISH_MODE=oidc`; check the current -repository variables before diagnosing a skipped publication. +approvals). Normal operation uses `NUGET_PUBLISH_ENABLED=true` and +`NPM_PUBLISH_MODE=oidc`; the WP03.00 first publication temporarily used bootstrap +mode for new npm identities. See the [accepted publication and OIDC transition](#wp0300-accepted-publication) +for the recorded state, and check current repository variables before diagnosing +a skipped publication. ## 2. NuGet: authorize every registered package family @@ -83,10 +85,11 @@ be able to publish under `@arcforges`; do not silently rename the package scope. npm currently requires a package to exist before its trusted publisher can be configured. Every new package identity needs one first real candidate publication. -The initial proto/API packages already exist; WP03.00 introduces +The initial proto/API packages already existed; WP03.00 introduced `@arcforges/contract-fixtures`, `@arcforges/ai-internal` and -`@arcforges/operator-client`, which need their own setup. The workflow performs that publication automatically with a -temporary granular token: +`@arcforges/operator-client`. All five now exist; the completed bootstrap and +remaining OIDC evidence are recorded below. A future new identity follows the +same first-creation sequence with a temporary granular token: 1. In the npm account menu, open Access Tokens and create a granular token named `Contracts-initial-publish`. @@ -100,7 +103,7 @@ temporary granular token: put it in source or store it as a repository variable. 5. Set the repository variable **NPM_PUBLISH_MODE=bootstrap**. 6. Merge the bootstrap PR, or the next accepted PR if the scaffold is already on - main. CI publishes all five registered npm packages after the + main. CI publishes all registered npm packages after the build/offline candidate gate, in dependency order. Use a token authorized for existing packages and new identities; secret-name presence does not prove validity. @@ -141,15 +144,17 @@ requires updating its registry trust relationships. Official reference: [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/). -The [main run publishing 1.0.0-ci.6.1](https://github.com/ArcForges/Contracts/actions/runs/34697244586) -completed both registry jobs. Its npm log records `NPM_PUBLISH_MODE=oidc`, and -both npm versions identify GitHub Actions as their trusted publisher with -provenance. The initial token is no longer needed for these two packages. -Deleting the GitHub environment secret removes that stored copy; revoke -`Contracts-initial-publish` in npm Account → Access Tokens to invalidate the -credential itself. Keep the package trusted-publisher connections and the GitHub -`npm` environment. This evidence concerns registry publication, not product or -Android device acceptance. +The historical [main run publishing 1.0.0-ci.6.1](https://github.com/ArcForges/Contracts/actions/runs/34697244586) +completed its NuGet/npm registry jobs. Its npm log records +`NPM_PUBLISH_MODE=oidc`, and the proto/API versions identify GitHub Actions as +their trusted publisher with provenance. This proves OIDC only for those two +package identities; it does not authorize later packages or establish their +OIDC publication. Follow the all-package confirmation above before removing a +temporary credential used for a later expansion. Deleting the GitHub environment +secret removes that stored copy; revoking the token in npm Account → Access +Tokens invalidates the credential itself. Keep the package trusted-publisher +connections and the GitHub `npm` environment. Registry publication does not +establish product or Android device acceptance. ## Maven Central setup @@ -245,5 +250,36 @@ still stop publication. Stable and newer CI tags retain their existing protectio The old run is a partial release and is not an accepted complete package set. Re-running its unchanged job would execute the same defective source. The reviewed -source correction uses the normal main publication channel to produce a complete -corrected release; it does not overwrite or republish the old immutable versions. +source correction used the normal main publication channel to produce the +complete corrected release below; it did not overwrite or republish the old +immutable versions. + +### WP03.00 accepted publication + +[Contracts PR #34](https://github.com/ArcForges/Contracts/pull/34) merged as +`84c89054b119bb0afa595c85ad85c24638501b65`. Its +[main run 35704055306](https://github.com/ArcForges/Contracts/actions/runs/35704055306) +passed Build candidate, Verify and all three publication jobs; the +[matching Security run](https://github.com/ArcForges/Contracts/actions/runs/35704055307) +also passed. It published the +complete registered set of 22 outputs: 14 NuGet and five npm packages at +`1.0.0-ci.84.1`, plus the three Maven modules at `1.0.0-SNAPSHOT` with that source +and CI build identity. This is the accepted WP03.00 package set; the earlier +partial `1.0.0-ci.82.1` set remains historical. + +The npm job used bootstrap authorization. On 2026-09-22, the account owner +confirmed that all three new packages have their GitHub Actions trusted +publisher saved for `ArcForges/Contracts`, workflow `ci.yml`, environment `npm`, +with direct `npm publish` allowed. `NPM_PUBLISH_MODE` was then set to `oidc` and +read back. The first normal OIDC publication covering all five packages has +not yet been observed. The temporary `NPM_BOOTSTRAP_TOKEN` environment secret +is retained until that publication succeeds; OIDC mode does not pass it to the +publisher. Afterwards, remove the stored secret and revoke the npm token as +described above. No verification-only publication, replacement version or tag +is required to record this transition. + +Acceptance uses the expected source identity and successful build/publication +job results. No post-publication archive download, installation or runtime test +was performed. The selected structure, generated slices and offline checks do +not establish the later WP03 business-schema, compatibility, product integration +or device acceptance gates. From 9795eda6d40b7f52ce0ce8c461fc305564c16a4f Mon Sep 17 00:00:00 2001 From: sammiller Date: Tue, 22 Sep 2026 03:22:51 -0700 Subject: [PATCH 2/2] Clarify required CI for documentation changes in code repositories --- AGENTS.md | 1 + docs/releasing.md | 8 ++++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 40e30e7..08f973d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,7 @@ Follow the [current CI/local authority](https://github.com/ArcForges/ArcForges-D - Preserve Maven main SNAPSHOT and deliberate-tag formal releases. Never create tags, republish or re-sign solely for verification. Diagnose failed jobs before rerun; ambiguous existing immutable releases require investigation, not silent skipping. - Do not reinstall vcpkg, SDKs, emulators or toolchains to expand validation. Stop on local network failure and report the exact operation; diagnose and repair CI failures before a targeted retry; no proxy configuration, port 7890, wsl.exe or WSL wrappers. - Review the full latest PR and wait for applicable checks before merging. Post-merge work ends after expected commit, required build/publication status and clean primary fast-forward. Keep branches/worktrees and report untested coverage accurately. +- This repository has configured CI/security checks; they remain required for documentation-only PRs. Direct merge after review without CI applies only to documentation repositories with no configured CI. Do not suppress configured workflows with skip directives or bypass branch protection. Documentation changes require no additional ad-hoc local product builds or runtime tests. ## Dependency admission (WP02.05) diff --git a/docs/releasing.md b/docs/releasing.md index 9717391..33d3ce9 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -271,10 +271,10 @@ The npm job used bootstrap authorization. On 2026-09-22, the account owner confirmed that all three new packages have their GitHub Actions trusted publisher saved for `ArcForges/Contracts`, workflow `ci.yml`, environment `npm`, with direct `npm publish` allowed. `NPM_PUBLISH_MODE` was then set to `oidc` and -read back. The first normal OIDC publication covering all five packages has -not yet been observed. The temporary `NPM_BOOTSTRAP_TOKEN` environment secret -is retained until that publication succeeds; OIDC mode does not pass it to the -publisher. Afterwards, remove the stored secret and revoke the npm token as +read back. That configuration change alone does not prove a successful normal +OIDC publication covering all five packages. Retain the temporary +`NPM_BOOTSTRAP_TOKEN` environment secret until that publication succeeds; +OIDC mode does not pass it to the publisher. Afterwards, remove the stored secret and revoke the npm token as described above. No verification-only publication, replacement version or tag is required to record this transition.