Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Add DESKTOP_RELEASE_REQUIRED_PLATFORMS escape valve (transiently broken platform) (#3188)
mike-inkeepee102a052977
diff --git a/.github/scripts/build-smoke-alert-payload.test.mjs b/.github/scripts/build-smoke-alert-payload.test.mjsindex 46f488441..d2ab3e53a 100644--- a/.github/scripts/build-smoke-alert-payload.test.mjs+++ b/.github/scripts/build-smoke-alert-payload.test.mjs@@ -130,15 +130,17 @@ describe('parseArgs', () => {});describe('workflow wiring', () => {- test('the alert job is failure-conditioned, not success-conditioned', () => {- // Under the fan-out topology the failure() lives at the ALERT JOB level- // (a failed packaging job skips finalize, so a failure()-step inside it- // could never fire); the step keeps only the stable-only channel gate.+ test('the alert job fires on a blocked release, never on success', () => {+ // The blocked-release predicate lives at the ALERT JOB level (a failed+ // packaging job skips finalize, so a failure()-step inside finalize+ // could never fire). It keys on finalize's result rather than bare+ // failure() so a degraded-mode cut that still publishes does not page;+ // the step keeps only the stable-only channel gate.const alertJob = desktopRelease.slice(desktopRelease.indexOf('\n alert:'),desktopRelease.indexOf('- name: Alert on a blocked release'),);- expect(alertJob).toContain('if: failure()');+ expect(alertJob).toContain("needs.finalize.result != 'success'");expect(alertJob).not.toContain('if: success()');expect(alertStep()).not.toContain('if: success()');});diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjsindex e95701518..f83d7bcc9 100644--- a/.github/scripts/release-cascade-shape.test.mjs+++ b/.github/scripts/release-cascade-shape.test.mjs@@ -75,18 +75,28 @@ describe('the stable gate is upstream of everything that ships', () => {expect(smoke).toBeLessThan(indexOfStep(names, 'Announce stable release to Discord'));});- test('nothing downstream of the gate opts out of the implicit success() guard', () => {- // A downstream step carrying `if: always()` would run even after the gate- // refused — which is exactly how a gate stops gating.+ test('no shipping STEP opts out of the implicit success() guard', () => {+ // A downstream step carrying `if: always()` / `!cancelled()` would run+ // even after the gate refused — which is exactly how a gate stops+ // gating. JOB-level `!cancelled()` predicates are a different animal:+ // the required-platforms valve needs them, and each one re-asserts the+ // success of everything it actually gates on — they are pinned exactly+ // in the fan-in DAG describe below. Step-level ifs sit at 8-space+ // indentation; job-level at 4.const afterGate = desktopRelease.slice(desktopRelease.indexOf('- name: Smoke the packaged DMG'),);- const shipping = afterGate.slice(- 0,- afterGate.indexOf('- name: Alert on a blocked release'), // failure-conditioned by design- );- expect(shipping).not.toContain('if: always()');- expect(shipping).not.toContain('!cancelled()');+ const shipping = afterGate.slice(0, afterGate.indexOf('- name: Alert on a blocked release'));+ const stepIfs = [...shipping.matchAll(/^ {8}if: (.+)$/gm)].map((m) => m[1].trim());+ expect(stepIfs.length).toBeGreaterThan(0);+ for (const condition of stepIfs) {+ expect(condition, `step-level if opts out of success(): ${condition}`).not.toContain(+ 'always()',+ );+ expect(condition, `step-level if opts out of success(): ${condition}`).not.toContain(+ '!cancelled()',+ );+ }});test('every shipping step with an explicit if: spells success() itself', () => {@@ -101,13 +111,13 @@ describe('the stable gate is upstream of everything that ships', () => {desktopRelease.indexOf('- name: Smoke the packaged DMG'),);const shipping = afterGate.slice(0, afterGate.indexOf('- name: Alert on a blocked release'));- const conditions = [...shipping.matchAll(/^\s*if: (.+)$/gm)].map((m) => m[1].trim());- // Two conditions in this span are gates, not shipping: the smoke gate's- // own channel scope, and the alert JOB's failure() header (the span ends- // at the alert step's name, which sits after its job header). Everything- // else ships and must be success()-gated.+ // Step-level ifs only (8-space indent) — job-level predicates are the+ // required-platforms valve, pinned exactly in the fan-in DAG describe.+ const conditions = [...shipping.matchAll(/^ {8}if: (.+)$/gm)].map((m) => m[1].trim());+ // One condition in this span is a gate, not shipping: the smoke gate's+ // own channel scope. Everything else ships and must be success()-gated.const shippingConditions = conditions.filter(- (c) => c !== "steps.channel.outputs.channel == 'latest'" && c !== 'failure()',+ (c) => c !== "steps.channel.outputs.channel == 'latest'",);expect(shippingConditions.length).toBeGreaterThan(0);for (const condition of shippingConditions) {@@ -180,6 +190,45 @@ describe('the fan-in publication DAG gates every platform', () => {expect(assert).toBeLessThan(upload);expect(upload).toBeLessThan(verify);});++ test('the required-platforms valve gates exactly what it may skip — and mac has no bypass', () => {+ // publish-assets may proceed past a FAILED platform only when that+ // platform is absent from the required set; the mac result is asserted+ // unconditionally (the stable smoke gate rides on build-macos), and+ // prepare refuses a required-set that omits mac at the variable level.+ const pa = desktopRelease.slice(+ desktopRelease.indexOf('\n publish-assets:'),+ desktopRelease.indexOf('\n finalize:'),+ );+ expect(pa).toContain("needs.build-macos.result == 'success'");+ expect(pa).toContain(+ "needs.build-windows.result == 'success' || !contains(needs.prepare.outputs.required, 'windows')",+ );+ expect(pa).toContain(+ "needs.build-linux.result == 'success' || !contains(needs.prepare.outputs.required, 'linux')",+ );+ expect(pa).not.toContain("contains(needs.prepare.outputs.required, 'mac')");+ const fin = desktopRelease.slice(+ desktopRelease.indexOf('\n finalize:'),+ desktopRelease.indexOf('\n alert:'),+ );+ expect(fin).toContain("needs.publish-assets.result == 'success'");+ expect(fin).toContain("needs.build-macos.result == 'success'");+ expect(desktopRelease).toContain("must include 'mac'");+ });++ test('the alert pages on a blocked RELEASE, not on any failed job', () => {+ // Under a degraded required-set a non-required platform can fail while+ // the release still publishes — paging on that would train readers to+ // ignore the alert. finalize != success covers every blocked shape+ // transitively.+ const alertJob = desktopRelease.slice(+ desktopRelease.indexOf('\n alert:'),+ desktopRelease.indexOf('- name: Alert on a blocked release'),+ );+ expect(alertJob).toContain("needs.finalize.result != 'success'");+ expect(alertJob).not.toContain('if: failure()');+ });});describe('the moved dispatch keeps the contract release.yml consumes', () => {diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.ymlindex 0eaebdeca..006b60adc 100644--- a/.github/workflows/desktop-release.yml+++ b/.github/workflows/desktop-release.yml@@ -67,6 +67,12 @@ name: Desktop release# GITHUB_TOKEN (auto-provided, contents:write scope) — used as GH_TOKEN# for the fan-in `gh release upload` + the finalize/alert steps.#+# Operator escape valve: the DESKTOP_RELEASE_REQUIRED_PLATFORMS repo variable+# (unset = mac,windows,linux) lets a TRANSIENTLY broken platform stop blocking+# publication — see the "Resolve required platforms" step in prepare for the+# full contract (mac can never be dropped; healthy non-required platforms+# still ship; degraded cuts warn loudly; remove the variable once fixed).+## Unsigned mode is explicitly REJECTED on macOS AND Windows. On macOS,# auto-update refuses unsigned upgrades (Squirrel.Mac signature-verifies every# update against the installed app's cert). On Windows nothing technically@@ -150,6 +156,7 @@ jobs:outputs:channel: ${{ steps.channel.outputs.channel }}version: ${{ steps.channel.outputs.version }}+ required: ${{ steps.required.outputs.required }}steps:- name: Link to triggering run# Back-link: promote-stable forwards its run URL in@@ -231,6 +238,45 @@ jobs:echo "::notice::Building LATEST channel from tag $RELEASE_TAG"fi+ # The operator escape valve for a TRANSIENTLY broken platform: the+ # `DESKTOP_RELEASE_REQUIRED_PLATFORMS` repo variable (comma-separated+ # subset of mac,windows,linux; unset = all three — fail-closed) names+ # the platforms whose build failure blocks publication. Non-required+ # platforms still BUILD every cut, and when their build succeeds their+ # assets still ship — requiredness only changes what can block. `mac`+ # can never be dropped: the stable DMG smoke gate (FR5b) and the npm+ # dispatch hang off build-macos, so a mac-less release would ship+ # unsmoked. A client on a platform missing from a cut simply 404s that+ # cut's channel manifest and retries next interval — the same benign+ # behavior as before that platform shipped at all. REMOVE the variable+ # once the platform is fixed; every degraded cut warns loudly so a+ # forgotten override stays visible.+ - name: Resolve required platforms+ id: required+ env:+ RAW: ${{ vars.DESKTOP_RELEASE_REQUIRED_PLATFORMS }}+ run: |+ set -euo pipefail+ REQUIRED="${RAW:-mac,windows,linux}"+ # Normalize: strip spaces, lowercase.+ REQUIRED="$(tr -d ' ' <<<"$REQUIRED" | tr '[:upper:]' '[:lower:]')"+ IFS=',' read -ra toks <<<"$REQUIRED"+ for t in "${toks[@]}"; do+ case "$t" in+ mac|windows|linux) ;;+ *) echo "::error::DESKTOP_RELEASE_REQUIRED_PLATFORMS contains unknown platform '$t' (allowed: mac, windows, linux)"; exit 1 ;;+ esac+ done+ if ! grep -q "mac" <<<"$REQUIRED"; then+ echo "::error::DESKTOP_RELEASE_REQUIRED_PLATFORMS must include 'mac' — the stable smoke gate and npm dispatch hang off the mac build, so a mac-less release would ship unverified."+ exit 1+ fi+ echo "required=$REQUIRED" >> "$GITHUB_OUTPUT"+ if [[ "$REQUIRED" != *windows* || "$REQUIRED" != *linux* ]]; then+ echo "::warning::DEGRADED RELEASE MODE: required platforms = ${REQUIRED}. A non-required platform's build failure will NOT block publication. Remove the DESKTOP_RELEASE_REQUIRED_PLATFORMS variable once the platform is fixed."+ echo "### ⚠️ Degraded release mode: required = ${REQUIRED}" >> "$GITHUB_STEP_SUMMARY"+ fi+# The manual recovery path uploads to an existing Release; the cascade# path's Release was just created by the upstream. Either way, failing# here — before three platforms spend 30+ runner-minutes building — beats@@ -1214,6 +1260,19 @@ jobs:# 30-minute signed build; `--clobber` makes the retry idempotent.publish-assets:needs: [prepare, build-macos, build-windows, build-linux]+ # Runs when every REQUIRED platform built (see prepare's "Resolve+ # required platforms"). `!cancelled()` is load-bearing: with a+ # non-required platform's job failed, the default success()-of-all-needs+ # would skip this job and block the release the override exists to save.+ # This predicate is only the fast gate — the inventory assert below is+ # the deterministic backstop (a required platform's missing assets fail+ # the must-have check even if this expression were wrong).+ if: >-+ !cancelled() &&+ needs.prepare.result == 'success' &&+ needs.build-macos.result == 'success' &&+ (needs.build-windows.result == 'success' || !contains(needs.prepare.outputs.required, 'windows')) &&+ (needs.build-linux.result == 'success' || !contains(needs.prepare.outputs.required, 'linux'))runs-on: ubuntu-latest# Sized to the upload retry envelope: 3 bounded 300s attempts + backoffs# (see the upload step) plus download/verify overhead.@@ -1232,6 +1291,12 @@ jobs:RELEASE_TAG: ${{ github.event.client_payload.release_tag || inputs.release_tag }}CHANNEL: ${{ needs.prepare.outputs.channel }}VERSION: ${{ needs.prepare.outputs.version }}+ REQUIRED: ${{ needs.prepare.outputs.required }}+ # A platform's asset group joins the expected inventory when it is+ # required OR its build succeeded anyway (a healthy non-required+ # platform still ships).+ WINDOWS_BUILT: ${{ needs.build-windows.result == 'success' }}+ LINUX_BUILT: ${{ needs.build-linux.result == 'success' }}steps:- name: Download all platform release assetsuses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v5.0.0@@ -1256,6 +1321,10 @@ jobs:- name: Define the expected asset inventoryrun: |set -euo pipefail+ # Per-platform groups. mac is unconditional (always required); the+ # windows/linux groups join when the platform is required OR its+ # build succeeded anyway — so a degraded cut still ships every+ # healthy platform, and the no-extras check below stays exact.{echo "EXPECTED_ASSETS<<OK_INVENTORY_EOF"echo "OpenKnowledge-arm64.dmg"@@ -1263,15 +1332,22 @@ jobs:echo "OpenKnowledge-${VERSION}-arm64-mac.zip"echo "OpenKnowledge-${VERSION}-arm64-mac.zip.blockmap"echo "${CHANNEL}-mac.yml"- echo "OpenKnowledge-Setup-x64.exe"- echo "OpenKnowledge-Setup-arm64.exe"- echo "${CHANNEL}.yml"- echo "OpenKnowledge-amd64.deb"- echo "OpenKnowledge-arm64.deb"- echo "OpenKnowledge-x86_64.rpm"- echo "OpenKnowledge-aarch64.rpm"- echo "${CHANNEL}-linux.yml"- echo "${CHANNEL}-linux-arm64.yml"+ if [[ "$REQUIRED" == *windows* || "$WINDOWS_BUILT" == "true" ]]; then+ echo "OpenKnowledge-Setup-x64.exe"+ echo "OpenKnowledge-Setup-arm64.exe"+ echo "${CHANNEL}.yml"+ fi+ if [[ "$REQUIRED" == *linux* || "$LINUX_BUILT" == "true" ]]; then+ echo "OpenKnowledge-amd64.deb"+ echo "OpenKnowledge-arm64.deb"+ echo "OpenKnowledge-x86_64.rpm"+ echo "OpenKnowledge-aarch64.rpm"+ echo "${CHANNEL}-linux.yml"+ echo "${CHANNEL}-linux-arm64.yml"+ fi+ # GITHUB_ENV's multiline syntax REQUIRES the closing delimiter+ # line — without it the runner rejects the whole env file.+ echo "OK_INVENTORY_EOF"} >> "$GITHUB_ENV"- name: Assert the complete cross-platform inventory@@ -1371,6 +1447,14 @@ jobs:# that).finalize:needs: [prepare, build-macos, publish-assets]+ # `!cancelled()` for the same reason as publish-assets: under a degraded+ # required-set, a non-required platform's failure elsewhere in the run+ # must not skip finalization. The explicit success checks keep the real+ # gates: verified inventory (publish-assets) + the smoke-bearing mac job.+ if: >-+ !cancelled() &&+ needs.publish-assets.result == 'success' &&+ needs.build-macos.result == 'success'runs-on: ubuntu-latesttimeout-minutes: 15permissions:@@ -1639,11 +1723,14 @@ jobs:# SKIPS finalize entirely — skipped steps can't alert.alert:needs: [prepare, build-macos, build-windows, build-linux, publish-assets, finalize]- # Job-level failure() is true when any job in `needs` failed. prepare- # failing before channel detection leaves the channel output empty; the- # steps below treat that as "not stable" (FR5c skips, STUCK-DRAFT still- # logs).- if: failure()+ # "The release did not publish" — not "some job failed": under a degraded+ # required-set a non-required platform can fail while the release still+ # publishes, and paging on that would train readers to ignore the alert.+ # finalize != success covers every blocked shape transitively (prepare,+ # a required build, publish-assets, or finalize itself). prepare failing+ # before channel detection leaves the channel output empty; the steps+ # below treat that as "not stable" (FR5c skips, STUCK-DRAFT still logs).+ if: ${{ !cancelled() && needs.finalize.result != 'success' }}runs-on: ubuntu-latesttimeout-minutes: 10permissions: