borgmcp-shared 0.3.0 → 0.4.2

package/docs/releasing.md

@@ -6,8 +6,9 @@ published from that exact tarball. Local publication and publication from an
 unreviewed branch are not supported.
 
 The active release policy is governed by the ratified
-`shared-package-consumption` and `npm-publish-sole-operator-approval` decisions.
-This document describes the operator procedure; it does not authorize a release.
+`shared-package-consumption`, `borgmcp-shared-coordinator-autonomy`, and
+`npm-publish-sole-operator-approval` decisions. This document describes the
+operator procedure; it does not authorize a release.
 
 ## Permanent Repository Configuration
 
@@ -67,8 +68,9 @@ Configure these controls before creating a release tag:
    `SECURITY.md` directs reporters to the private reporting path, so disabled
    reporting is always a release-blocking documentation failure.
 
-The environment approval is the final technical control. Approval must remain
-pending while Security reviews the artifact produced by the `verify` job.
+The environment approval is the final technical control. It appears only on the
+`publish` job, after `validate` has verified the SR approval tuple. Approval must
+remain pending while Security reviews the artifact produced by the `verify` job.
 GitHub's ephemeral workflow token cannot read every repository-administration
 setting checked by `scripts/verify-release-configuration.mjs`. An authorized
 operator must run the guard with an administration-capable token before creating
@@ -88,7 +90,7 @@ before dependency installation, and includes the same values in the uploaded
 `RUN_EVIDENCE` file. Never use the Actions rerun controls to advance a failed
 immutable tag or proof run.
 
-Both jobs reject a repository-root `.npmrc` before their first npm command. The
+All three jobs reject a repository-root `.npmrc` before their first npm command. The
 exact npm bootstrap uses isolated runner-temp prefix, user config, and cache
 paths, forces `https://registry.npmjs.org`, disables scripts, and verifies both
 the installed npm version and registry before adding its bin directory to
@@ -137,9 +139,10 @@ Recover out of band without rerunning the workflow:
 2. With `GITHUB_SHA=508f2dc88658d8e00ff036b7ce6913fcfbef239b` and
    `NPM_EXPECTED_OWNER=byteventures`, run
    `node scripts/verify-registry-release.mjs postpublish <audited-tarball>`. The
-   verifier retries only transient HTTP 404 propagation responses with bounded
-   backoff; non-404 failures and integrity, owner, or provenance mismatches remain
-   immediate terminal failures.
+   verifier retries only transient HTTP 404 propagation responses. Its production
+   envelope performs at most 18 reads over approximately three and a half minutes
+   (1, 2, 4, and 8 second waits, then a 15 second cap). Non-404 failures and
+   integrity, owner, or provenance mismatches remain immediate terminal failures.
 3. Install exact `borgmcp-shared@0.2.2` from the registry into a clean temporary
    prefix with scripts disabled and run `npm audit signatures` against that
    prefix.
@@ -190,15 +193,23 @@ first:
 - exercises npm's publish metadata in dry-run mode; and
 - installs the exact tarball with scripts disabled in a clean consumer, verifies
   its production tree, and imports every reviewed public export; and
-- uploads the tarball, verifier report, and SHA-512 checksum for seven days.
+- uploads the tarball, verifier report, SHA-512 checksum, SBOM, and
+  `RUN_EVIDENCE` for seven days.
 
 Security must download and audit that exact workflow artifact. After Security
 approves the tarball, Release Quality confirms the operator procedure, and the
-Queen explicitly authorizes the public flip, an authorized reviewer may approve
-the waiting `npm-publish` environment deployment. The publish job downloads and
-checksum-verifies the same artifact, repeats the artifact verifier, checks that
-`0.2.2` is absent and the name is unclaimed as expected, and publishes only the
-downloaded tarball with `--access public --provenance`.
+Queen explicitly authorizes the public flip, the Coordinator writes the SR
+approval tuple (`ARTIFACT_SR_SHA512`, `ARTIFACT_SR_RUN_ID`,
+`ARTIFACT_SR_RUN_ATTEMPT`) to environment variables and dispatches the
+`publish.yml` workflow with the tag. The `validate` job runs first (outside
+the `npm-publish` environment): it re-verifies the source, queries the source
+run's workflow path, tag, conclusion, and attempt via the GitHub API, downloads
+the artifact, binds the SR tuple to the exact tarball, and confirms run identity.
+Only after `validate` succeeds does the `publish` job run, which surfaces the
+`npm-publish` environment approval dialog. The `publish` job re-downloads and
+checksum-verifies the same artifact, re-binds the SR tuple, repeats the artifact
+verifier, checks that `0.2.2` is absent and the name is unclaimed as expected,
+and publishes only the downloaded tarball with `--access public --provenance`.
 
 Immediately after a successful first publish:
 
@@ -216,42 +227,59 @@ Immediately after a successful first publish:
 
 ## Later Releases
 
-### 0.3.0 Enrollment Contract
+### 0.4.2 Cross-Platform SBOM Recovery
 
-The ratified `borgmcp-shared-enrollment-version` decision selects `0.3.0` for
-the breaking retry-safe enrollment and idempotent multi-cube contract. Updating
-package metadata, lockfiles, assertions, compatibility documentation, and this
-runbook does not authorize creating `v0.3.0` or publishing the package.
+`borgmcp-shared@0.4.0` is the published, immutable clean-slate v2 contract, but
+its registry artifact was built before the public package's local/self-hosted
+topology cleanup. The immutable `v0.4.1` run `29701429995` built the cleaned
+artifact, but independent macOS verification proved that the SBOM verifier used
+the auditor's installed optional-dependency tree instead of a deterministic
+release graph. The `v0.4.1` tag, run, and artifact are failed evidence: never
+publish, move, reuse, rerun, or substitute them.
 
-Before a separately authorized `v0.3.0` tag is created:
+Version `0.4.2` carries the reviewed cleanup with a lockfile-derived SBOM graph
+for the fixed release target `{os: linux, cpu: x64, libc: glibc}`. It does not
+change the protocol tag or runtime behavior. This source now identifies `0.4.2`.
+The reviewed recovery bump does not authorize creating `v0.4.2` or publishing
+the package.
 
-1. The exact `0.3.0` source commit must be merged to protected `main` after Code
+Before a separately authorized `v0.4.2` tag is created:
+
+1. The exact `0.4.2` source commit must be merged to protected `main` after Code
    Review, Security, and Release Quality approve the package identity, public
-   API, conformance behavior, generated output, and release documentation.
-2. The package and root lockfile, `SHARED_PACKAGE_VERSION`, compatibility matrix,
-   packed-artifact verifier, and version assertions must all identify `0.3.0`.
+   API, generated output, and release documentation.
+2. The package and root lockfile, `SHARED_PACKAGE_VERSION`, packed-artifact and
+   SBOM verifiers, generated declarations, and version assertions must all
+   identify `0.4.2`. The protocol tag remains unchanged.
 3. The protected workflow must build one exact tarball and pass its full source,
    test, audit, public-export, source-map, install/import, dry-run, lock-derived
    CycloneDX SBOM, integrity, and provenance gates. Security must approve that
    exact workflow artifact.
-4. The `0.3.0` workflow must generate a CycloneDX SBOM, canonicalize npm's
+4. The `0.4.2` workflow must generate a CycloneDX SBOM, canonicalize npm's
    checkout-derived root display name to the already-verified manifest name,
    and validate every component's exact canonical registry tarball URL, single
    matching CycloneDX distribution reference, purl, and lock SHA-512 plus the
-   exact installed dependency graph and zero package runtime dependencies. The
-   tarball, SBOM, and SBOM validation report must be
-   checksummed and uploaded together for Security audit.
+   exact lockfile-derived release-target graph and zero package runtime
+   dependencies. The graph starts from root development dependencies, follows
+   required dependencies and peers, includes only target-compatible optional
+   dependencies, and includes optional peers only when another reachable edge
+   installs them. Root manifest and lock selectors must match and permit the
+   fixed target. Verification must not inspect the auditor's operating system,
+   installed dependency tree, or `node_modules`. The tarball, SBOM, and SBOM
+   validation report must be checksummed and uploaded together for Security
+   audit.
 5. The tag and publication each require their own explicit authorization. A
    source-version approval, merge, or successful verification run grants neither.
 
 After registry publication and independent integrity/provenance verification,
-the first borgmcp client and borgmcp-server releases may replace their temporary
-development dependency with the reviewed registry range `^0.3.0`. They must not
-ship a Git dependency or fall back to the incompatible `0.2.x` enrollment
-response.
+the first borgmcp client and borgmcp-server releases must pin exact
+`borgmcp-shared@0.4.2` and commit their registry lockfiles. They must not ship a
+Git dependency, a version range that can resolve to the pre-cleanup artifact, or
+a fallback to the incompatible `0.3.0` v1 enrollment response.
 
 Later releases follow the same source gates, annotated protected tag, exact
-tarball audit, Queen authorization, and environment approval. The registry
+tarball audit, Coordinator authorization under the ratified shared release
+autonomy, and environment approval. The registry
 preflight requires the package to be owned by `NPM_EXPECTED_OWNER` and rejects
 an existing target version. It also fails if
 `ALLOW_UNCLAIMED_FIRST_PUBLISH` is not `false` or any `NPM_TOKEN` remains;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borgmcp-shared",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Shared protocol, domain, templates, and conformance contracts for Borg MCP implementations.",
   "type": "module",
   "main": "./dist/index.js",
@@ -68,7 +68,7 @@
   ],
   "author": "Byte Ventures IO AB",
   "license": "Apache-2.0",
-  "homepage": "https://borgmcp.ai",
+  "homepage": "https://github.com/Byte-Ventures/borg-mcp-shared",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Byte-Ventures/borg-mcp-shared.git"