feat(runtime-host): page semantic transcript turns

.asf.yaml

@@ -110,6 +110,15 @@ github:
         policies:
           - name: main
             type: branch
+    nightly:
+      required_reviewers: []
+      wait_timer: 0
+      prevent_self_review: false
+      deployment_branch_policy:
+        protected_branches: false
+        policies:
+          - name: main
+            type: branch
     product-release:
       required_reviewers:
         - id: M4n5ter

.github/DESKTOP_NIGHTLY.md

@@ -21,19 +21,22 @@
 
 Desktop Nightly is an ephemeral developer snapshot, not an Apache release. It builds the current `main` commit every day so contributors can try recent Desktop changes and report problems without waiting for an ASF source-release vote.
 
-The npm publication workflow gives each snapshot an immutable version such as `0.2.0-dev.42.20260829`. The run number is the sole ordering authority. After that exact npm version is public, it triggers Desktop Nightly with a version-only artifact; the authenticated workflow event supplies the exact source commit and upstream run. A packaged Nightly accepts updates only from `https://nightlies.apache.org/maka/desktop/`, advances only to a higher run number, and verifies that downloaded bytes were attested by `.github/workflows/desktop-nightly.yml` on `main`. A formal Desktop build continues to use the GitHub Release feed and the formal product-release attestation identity.
+The npm publication workflow gives each snapshot an immutable version such as `0.2.0-dev.42.20260829`. The run number is the sole ordering authority. After that exact npm version is public, it triggers Desktop Nightly with a version-only artifact; the authenticated workflow event supplies the exact source commit and upstream run. Each fresh Desktop Nightly creates a protected `v<version>` tag and one GitHub draft prerelease containing the macOS and Windows packages, blockmaps, `dev-mac.yml`, `dev.yml`, and one offline Sigstore bundle. The workflow verifies every remote asset before it publishes the prerelease as non-Latest. Packaged Nightlies use the GitHub `dev` channel and verify that downloaded bytes were attested by `.github/workflows/desktop-nightly.yml` on `main`. A formal Desktop build uses the separate stable GitHub Release channel and formal product-release attestation identity.
 
-Nightly currently uses the same application identity as the formal Desktop. Installing it replaces the existing Maka installation rather than creating a second side-by-side app. Its user data remains in the same location. Testers who need the formal build should reinstall that build before returning to the formal channel.
+Nightly currently uses the same application identity as the formal Desktop. Installing it replaces the existing Maka installation rather than creating a second side-by-side app. Its user data remains in the same location. Testers who need the formal build should reinstall that build before returning to the formal channel. Builds previously downloaded from `nightlies.apache.org` do not migrate automatically; testers must install the newest GitHub prerelease once, after which GitHub Nightlies update automatically.
 
 ## One-time setup
 
-1. Ask Apache Infra to allow `apache/maka` to publish GitHub Actions output to `nightlies.apache.org`, provide the SSH `known_hosts` entry through an authenticated channel, and confirm whether retention is service-managed or requires a separate project cleanup job. Do not enable scheduled publication until that retention owner is explicit.
-2. Create a GitHub Environment named `nightly` that permits only `main`. Store `NIGHTLIES_RSYNC_PATH`, `NIGHTLIES_RSYNC_HOST`, `NIGHTLIES_RSYNC_PORT`, `NIGHTLIES_RSYNC_USER`, `NIGHTLIES_RSYNC_KEY`, and the Infra-verified `NIGHTLIES_RSYNC_KNOWN_HOSTS` value as Environment secrets. Configure its macOS signing and notarization secrets: `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_API_KEY`, `APPLE_API_KEY_ID`, and `APPLE_API_ISSUER`. Do not expose these secrets to repository-wide or pull-request workflows.
-3. Configure npm Trusted Publishing for `apache/maka` and `.github/workflows/npm-publication.yml`, restricted to the `npm-publication` Environment and with both `npm publish` and `npm stage publish` allowed. Do not create or store a long-lived npm token.
-4. After npm Trusted Publishing is ready, set `NPM_NIGHTLY_ENABLED` to `true`, run `npm publication` from `main` with `channel=nightly`, and verify the exact npm version and `nightly` dist-tag. This does not depend on Desktop Infra.
-5. After Infra publishing and the `nightly` Environment secrets are ready, set `DESKTOP_NIGHTLY_ENABLED` to `true` and start a fresh npm Nightly. Confirm that its successful run triggers `Desktop Nightly`.
-6. Verify the download page, `latest-mac.yml`, and `latest.yml` under `https://nightlies.apache.org/maka/desktop/`, install both platform artifacts on clean machines, and confirm one automatic update before sharing the channel with testers.
+1. After the checked-in `.asf.yaml` reaches `main`, verify that ASF reconciliation created the `nightly` GitHub Environment with only `main` permitted and no approval gate. Do not maintain that policy manually in GitHub. Configure its macOS signing and notarization secrets: `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_API_KEY`, `APPLE_API_KEY_ID`, and `APPLE_API_ISSUER`. Do not expose these secrets to repository-wide or pull-request workflows.
+2. Configure npm Trusted Publishing for `apache/maka` and `.github/workflows/npm-publication.yml`, restricted to the `npm-publication` Environment and with both `npm publish` and `npm stage publish` allowed. Do not create or store a long-lived npm token.
+3. Enable GitHub Immutable Releases for `apache/maka` before distributing Desktop Nightlies so published tags and assets cannot be replaced or deleted.
+4. After npm Trusted Publishing is ready, set `NPM_NIGHTLY_ENABLED` to `true`, run `npm publication` from `main` with `channel=nightly`, and verify the exact npm version and `nightly` dist-tag.
+5. Set `DESKTOP_NIGHTLY_ENABLED` to `true` and manually dispatch a fresh npm Nightly. Confirm that its successful run triggers `Desktop Nightly`. Do not rerun a failed attempt in place.
+6. Verify that `v<version>` points to the exact source SHA and that its GitHub Release is published with Draft off, Prerelease on, Latest off, Immutable on, and exactly the nine expected assets. Install that prerelease on both platforms.
+7. Publish one later fresh Nightly and confirm a GitHub-to-GitHub automatic and differential update on both platforms before sharing the channel with testers.
 
-The npm schedule starts at 18:17 UTC. Before changing the npm tag, the workflow requires its run number to exceed the current `nightly` version. Desktop applies the same check against both remote feed files before uploading anything. It then appends a new immutable Desktop version directory and advances the mutable update metadata last. Each platform feed file is replaced independently after its complete payload exists, so an interrupted feed transfer may temporarily leave macOS and Windows on different valid Nightly versions. Do not rerun a failed workflow attempt in place; start a fresh npm Nightly so it receives a new version. Historical payload cleanup is separate from publication, targets the Nightlies retention policy, and must never rewrite a published version or delete one referenced by a feed. Apache Nightlies storage is temporary; it must not be used as a formal release archive.
+The npm schedule starts at 18:17 UTC. Before changing the npm tag, the workflow requires its run number to exceed the current `nightly` version. Desktop assembles and verifies a draft before one publish mutation; a packaging, attestation, tag, upload, or digest failure leaves no partially published GitHub Release. Never rerun a failed workflow attempt in place; dispatch a fresh npm Nightly with a newer version.
+
+GitHub Release retention is intentionally outside this workflow. Do not delete an old Nightly prerelease or its tag while any installed client may need its payload or blockmap. Disabling `DESKTOP_NIGHTLY_ENABLED` stops new Desktop publication without mutating tags or releases.
 
 Remote Runtime Host setup uses the exact `maka-agent@<nightly-version>` package embedded in the Desktop manifest. The npm package is verified before Desktop artifacts become visible, so clean remote setup never depends on an unpublished Runtime Host version.

.github/RELEASE_CHECKLIST.md

@@ -63,10 +63,10 @@ Before the first product release, confirm the checked-in `.asf.yaml` has reconci
 - the `Immutable release tags` ruleset blocks updates, force-pushes, and deletions of `v*` tags;
 - the `release` Environment accepts only its declared source-candidate tag pattern and requires a
   reviewer other than the triggering user;
-- `npm-publication` and `product-release` accept only `main`; `product-release` requires a reviewer
-  other than the triggering user. `npm-publication` has no GitHub
-  approval gate because scheduled Nightly publication is automatic; formal npm publication still
-  requires human 2FA approval after staging.
+- `npm-publication`, `nightly`, and `product-release` accept only `main`; `product-release` requires
+  a reviewer other than the triggering user. `npm-publication` and `nightly` have no GitHub approval
+  gate because scheduled npm and Desktop Nightly publication is automatic; formal npm publication
+  still requires human 2FA approval after staging.
 
 These controls close the check-to-upload and check-to-stage windows. Finalize uses GitHub Actions
 OIDC rather than a stored signing key to attest every convenience artifact. Keep the Release in

.github/workflows/ci.yml

@@ -143,7 +143,7 @@ jobs:
           fi
 
       - name: Install dependencies
-        if: steps.plan.outputs.code == 'true' || steps.plan.outputs.asf_source == 'true' || steps.plan.outputs.cli_package == 'true' || steps.plan.outputs.release_contract == 'true'
+        if: steps.plan.outputs.code == 'true' || steps.plan.outputs.astryx_surface == 'true' || steps.plan.outputs.asf_source == 'true' || steps.plan.outputs.cli_package == 'true' || steps.plan.outputs.release_contract == 'true'
         run: npm ci
 
       # The header audit above remains install-free. The complete source gate
@@ -181,7 +181,9 @@ jobs:
       # directly instead of being hidden behind an earlier compilation failure.
       - name: Astryx surface inventory
         if: steps.plan.outputs.code == 'true' || steps.plan.outputs.astryx_surface == 'true'
-        run: npm run astryx:surface-inventory
+        run: |
+          npm run astryx:surface-inventory
+          npm run astryx:surface-inventory:test
 
       - name: Build
         if: steps.plan.outputs.code == 'true' || steps.plan.outputs.cli_package == 'true' || steps.plan.outputs.release_contract == 'true'

.github/workflows/desktop-nightly.yml

@@ -184,14 +184,14 @@ jobs:
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-mac-arm64.dmg" \
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-mac-arm64.zip" \
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-mac-arm64.zip.blockmap" \
-              apps/desktop/release/latest-mac.yml \
+              apps/desktop/release/dev-mac.yml \
               "$STAGE_DIRECTORY/"
           else
             cp -- \
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-win-x64.exe" \
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-win-x64.exe.blockmap" \
               "apps/desktop/release/Maka-$NIGHTLY_VERSION-win-x64.zip" \
-              apps/desktop/release/latest.yml \
+              apps/desktop/release/dev.yml \
               "$STAGE_DIRECTORY/"
           fi
 
@@ -212,7 +212,7 @@ jobs:
     permissions:
       artifact-metadata: write
       attestations: write
-      contents: read
+      contents: write
       id-token: write
     steps:
       - name: Reject in-place workflow reruns
@@ -243,29 +243,26 @@ jobs:
           path: ${{ github.workspace }}/.nightly-input
           merge-multiple: true
 
-      - name: Stage the versioned Nightly site
+      - name: Stage the exact GitHub Release assets
         env:
           NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
-          SOURCE_COMMIT: ${{ needs.identity.outputs.source_commit }}
         run: |
           node scripts/desktop-nightly.mjs stage \
             "$GITHUB_WORKSPACE/.nightly-input" \
-            "$GITHUB_WORKSPACE/.nightly-publish" \
-            "$NIGHTLY_VERSION" \
-            "$SOURCE_COMMIT"
+            "$GITHUB_WORKSPACE/.nightly-stage" \
+            "$NIGHTLY_VERSION"
 
-      - name: Attest the exact Nightly payloads
+      - name: Attest every GitHub Nightly asset subject
         id: attest
         uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
         with:
-          subject-path: ${{ github.workspace }}/.nightly-publish/versions/${{ needs.identity.outputs.version }}/*
+          subject-path: ${{ github.workspace }}/.nightly-stage/release/*
 
       - name: Verify the issued Nightly provenance
         env:
           ATTESTATION_BUNDLE: ${{ steps.attest.outputs.bundle-path }}
           CERTIFICATE_IDENTITY: https://github.com/${{ github.repository }}/.github/workflows/desktop-nightly.yml@refs/heads/main
           GH_TOKEN: ${{ github.token }}
-          NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
         run: |
           verified=0
           while IFS= read -r -d '' artifact; do
@@ -275,67 +272,51 @@ jobs:
               --cert-identity "$CERTIFICATE_IDENTITY" \
               --cert-oidc-issuer https://token.actions.githubusercontent.com
             verified=$((verified + 1))
-          done < <(find "$GITHUB_WORKSPACE/.nightly-publish/versions/$NIGHTLY_VERSION" -maxdepth 1 -type f -print0)
-          if (( verified == 0 )); then
-            echo "No Desktop Nightly artifacts were verified" >&2
+          done < <(find "$GITHUB_WORKSPACE/.nightly-stage/release" -maxdepth 1 -type f -print0)
+          if (( verified != 8 )); then
+            echo "Expected 8 verified Desktop Nightly subjects, found $verified" >&2
             exit 1
           fi
 
-      - name: Add the offline provenance bundle
+      - name: Add the one offline provenance bundle
         env:
           ATTESTATION_BUNDLE: ${{ steps.attest.outputs.bundle-path }}
           NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
-        run: >-
-          cp -- "$ATTESTATION_BUNDLE"
-          "$GITHUB_WORKSPACE/.nightly-publish/versions/$NIGHTLY_VERSION/Maka-$NIGHTLY_VERSION-attestation.sigstore.json"
+        run: |
+          node scripts/desktop-nightly.mjs add-attestation \
+            "$GITHUB_WORKSPACE/.nightly-stage" \
+            "$NIGHTLY_VERSION" \
+            "$ATTESTATION_BUNDLE"
 
-      - name: Prepare authenticated Nightlies SSH transport
+      - name: Ensure the exact versioned Nightly tag
         env:
-          NIGHTLIES_RSYNC_HOST: ${{ secrets.NIGHTLIES_RSYNC_HOST }}
-          NIGHTLIES_RSYNC_KEY: ${{ secrets.NIGHTLIES_RSYNC_KEY }}
-          NIGHTLIES_RSYNC_KNOWN_HOSTS: ${{ secrets.NIGHTLIES_RSYNC_KNOWN_HOSTS }}
-          NIGHTLIES_RSYNC_PATH: ${{ secrets.NIGHTLIES_RSYNC_PATH }}
-          NIGHTLIES_RSYNC_PORT: ${{ secrets.NIGHTLIES_RSYNC_PORT }}
-          NIGHTLIES_RSYNC_USER: ${{ secrets.NIGHTLIES_RSYNC_USER }}
+          GH_TOKEN: ${{ github.token }}
+          NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
+          SOURCE_COMMIT: ${{ needs.identity.outputs.source_commit }}
         run: |
-          test -n "$NIGHTLIES_RSYNC_HOST"
-          test -n "$NIGHTLIES_RSYNC_KEY"
-          test -n "$NIGHTLIES_RSYNC_KNOWN_HOSTS"
-          test -n "$NIGHTLIES_RSYNC_PATH"
-          test -n "$NIGHTLIES_RSYNC_USER"
-          [[ "$NIGHTLIES_RSYNC_PORT" =~ ^[0-9]{1,5}$ ]]
-          (( NIGHTLIES_RSYNC_PORT >= 1 && NIGHTLIES_RSYNC_PORT <= 65535 ))
-          ssh_directory="$RUNNER_TEMP/nightlies-ssh"
-          install -m 700 -d "$ssh_directory"
-          umask 077
-          printf '%s\n' "$NIGHTLIES_RSYNC_KEY" > "$ssh_directory/key"
-          printf '%s\n' "$NIGHTLIES_RSYNC_KNOWN_HOSTS" > "$ssh_directory/known_hosts"
-          {
-            echo "NIGHTLIES_RSYNC_TARGET=$NIGHTLIES_RSYNC_USER@$NIGHTLIES_RSYNC_HOST:${NIGHTLIES_RSYNC_PATH%/}/maka/desktop"
-            echo "RSYNC_RSH=ssh -i $ssh_directory/key -o IdentitiesOnly=yes -o StrictHostKeyChecking=yes -o UserKnownHostsFile=$ssh_directory/known_hosts -p $NIGHTLIES_RSYNC_PORT"
-          } >> "$GITHUB_ENV"
-
-      - name: Require the Desktop Nightly feed to advance
+          gh auth setup-git
+          node scripts/product-release-tag.mjs ensure "v$NIGHTLY_VERSION" "$SOURCE_COMMIT"
+
+      - name: Prepare and verify the draft GitHub Prerelease
         env:
+          GH_TOKEN: ${{ github.token }}
           NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
+          SOURCE_COMMIT: ${{ needs.identity.outputs.source_commit }}
         run: |
-          mkdir -p .nightly-current-feed
-          rsync -rlptDz --protect-args \
-            --include='/latest-mac.yml' \
-            --include='/latest.yml' \
-            --exclude='*' \
-            "$NIGHTLIES_RSYNC_TARGET/" \
-            .nightly-current-feed/
-          node scripts/desktop-nightly.mjs assert-feed-advance \
-            .nightly-current-feed \
-            "$NIGHTLY_VERSION"
-
-      - name: Publish immutable Nightly payloads
-        run: rsync -rlptDvz --protect-args .nightly-publish/versions/ "$NIGHTLIES_RSYNC_TARGET/versions/"
-
-      - name: Advance the Nightly update feed last
-        run: rsync -rlptDvz --protect-args .nightly-publish/feed/ "$NIGHTLIES_RSYNC_TARGET/"
+          node scripts/desktop-nightly-release.mjs prepare \
+            "$GITHUB_WORKSPACE/.nightly-stage/release" \
+            "$NIGHTLY_VERSION" \
+            "$SOURCE_COMMIT" \
+            "$GITHUB_REPOSITORY"
 
-      - name: Remove the temporary Nightlies credentials
-        if: always()
-        run: rm -f "$RUNNER_TEMP/nightlies-ssh/key" "$RUNNER_TEMP/nightlies-ssh/known_hosts"
+      - name: Publish the complete GitHub Prerelease
+        env:
+          GH_TOKEN: ${{ github.token }}
+          NIGHTLY_VERSION: ${{ needs.identity.outputs.version }}
+          SOURCE_COMMIT: ${{ needs.identity.outputs.source_commit }}
+        run: |
+          node scripts/desktop-nightly-release.mjs publish \
+            "$GITHUB_WORKSPACE/.nightly-stage/release" \
+            "$NIGHTLY_VERSION" \
+            "$SOURCE_COMMIT" \
+            "$GITHUB_REPOSITORY"

.github/workflows/windows-recovery.yml

@@ -158,8 +158,8 @@ jobs:
           $exitCode = $LASTEXITCODE
           if ($exitCode -ne 0) { exit $exitCode }
           $output = Get-Content "$env:RUNNER_TEMP/skill-catalog.tap"
-          if ($output -notcontains '# tests 90' -or $output -notcontains '# pass 90' -or $output -notcontains '# skipped 0') {
-            Write-Error 'Skill catalog gate did not run exactly 90 passing Windows tests'
+          if ($output -notcontains '# tests 91' -or $output -notcontains '# pass 91' -or $output -notcontains '# skipped 0') {
+            Write-Error 'Skill catalog gate did not run exactly 91 passing Windows tests'
             exit 1
           }