feat: Add evaluation engine with offset resolution and CI/CD automation (#5)

* chore: Update implementation tasks in tasks.md for clarity and organization

- Renumbered and reorganized tasks in `tasks.md` to improve clarity and maintain a consistent structure.
- Added sub-tasks for offset resolution, type reading, operator creation, rule evaluation, and output formatting to enhance task tracking.
- Updated task descriptions to reflect current implementation requirements and ensure alignment with project goals.

These changes streamline the development process and provide clearer guidance for contributors on upcoming tasks and their dependencies.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat: Enhance project metadata and CI configuration

- Added `homepage` and `documentation` fields to `Cargo.toml` for improved project visibility and resource access.
- Introduced `dist-workspace.toml` to configure workspace settings and CI parameters for building and releasing artifacts across multiple platforms.
- Created a comprehensive GitHub Actions workflow in `release.yml` to automate the release process, including artifact building, uploading, and GitHub release creation.
- Implemented offset resolution logic in `offset.rs`, including error handling and comprehensive unit tests to ensure robustness.

These changes improve project organization, enhance automation capabilities, and ensure better handling of file offsets during evaluation.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Implement basic byte reading functionality

- Added `read_byte` function in `src/evaluator/types.rs` for safely reading a single byte from a buffer with bounds checking.
- Introduced `TypeReadError` enum to handle buffer overrun errors during byte reading operations.
- Updated `mod.rs` to include the new `types` module.
- Marked task 6.1 as complete in `tasks.md`, reflecting the implementation of basic type reading for byte values.

These changes enhance the evaluator's capability to interpret byte data safely, improving overall robustness and error handling in the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Implement multi-byte type reading and interpretation

- Completed tasks for reading multi-byte types, including `read_short` and `read_long` functions in `src/evaluator/types.rs`, supporting both signed and unsigned interpretations with endianness handling.
- Introduced `read_typed_value` function to interpret bytes according to the specified `TypeKind`, allowing for flexible type reading.
- Enhanced error handling with the addition of `UnsupportedType` variant in `TypeReadError` for unsupported types.
- Updated `tasks.md` to reflect the completion of tasks related to multi-byte type reading and interpretation.

These changes significantly improve the evaluator's capability to handle various data types, enhancing the robustness and flexibility of the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Implement basic equality operator for value comparison

- Completed the implementation of the basic equality operator in `src/evaluator/operators.rs` with the `apply_equal` function, allowing for type-safe comparisons between different `Value` variants.
- Updated `mod.rs` to include the new `operators` module.
- Marked task 7.1 as complete in `tasks.md`, reflecting the addition of value-to-value comparison functionality.

These changes enhance the evaluator's capability to accurately compare values, improving the robustness of the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Implement inequality and bitwise AND operators for value comparison

- Completed the implementation of the inequality operator with the `apply_not_equal` function, allowing for type-safe comparisons between different `Value` variants.
- Added the bitwise AND operator with the `apply_bitwise_and` function, enabling pattern matching for integer values.
- Introduced the `apply_operator` function to dispatch operations based on the `Operator` enum, supporting equality, inequality, and bitwise AND operations.
- Updated `tasks.md` to reflect the completion of tasks related to operator creation and application.

These enhancements improve the evaluator's capability to perform complex comparisons and operations, further strengthening the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Implement single rule evaluation logic

- Added the `evaluate_single_rule` function in `src/evaluator/mod.rs` to evaluate a single magic rule against a file buffer.
- The function resolves the rule's offset, reads the corresponding bytes, and applies the specified operator for comparison.
- Comprehensive unit tests have been included to validate the functionality of the evaluation logic, covering various scenarios including equality, inequality, and bitwise operations.
- Updated `tasks.md` to reflect the completion of the task for basic rule evaluation.

These enhancements significantly improve the evaluator's capability to process and validate magic rules, enhancing the overall file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(hooks): Remove outdated automation hooks for code analysis

- Deleted the `llms-txt-updater.kiro.hook`, `rust-code-analyzer.kiro.hook`, `rust-perf-analyzer.kiro.hook`, `rust-quality-monitor.kiro.hook`, and `rust-security-hardening.kiro.hook` files as they are no longer needed.
- These hooks were previously used for automated analysis and updates but have been replaced with more efficient user-triggered mechanisms to enhance control and accuracy in code quality and performance assessments.

This cleanup improves the project's automation infrastructure and reduces potential confusion regarding obsolete hooks.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Introduce EvaluationContext for managing evaluation state

- Added the `EvaluationContext` struct in `src/evaluator/mod.rs` to maintain the state during rule evaluation, including current offset, recursion depth, and configuration settings.
- Implemented methods for managing the offset and recursion depth, including incrementing and decrementing the recursion depth with error handling for exceeding limits.
- Updated `lib.rs` to re-export `EvaluationContext` for convenience.
- Marked task 8.2 as complete in `tasks.md`, reflecting the addition of the evaluation context structure.

These enhancements improve the evaluator's ability to manage state during complex rule evaluations, contributing to a more robust file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(evaluator): Enhance evaluation configuration and hierarchical rule processing

- Completed the implementation of the `EvaluationConfig` struct in `src/lib.rs`, allowing for customizable evaluation options such as recursion limits, string length limits, and timeout settings.
- Introduced the `MatchResult` struct to encapsulate results from rule evaluations, including matched messages and offsets.
- Implemented the `evaluate_rules` function in `src/evaluator/mod.rs` to support hierarchical rule evaluation, enabling parent-child relationships in rules and refined matching.
- Updated `tasks.md` to reflect the completion of tasks related to evaluation configuration and hierarchical processing.

These enhancements improve the evaluator's flexibility and robustness, allowing for more complex and efficient file type detection processes.

Signed-off-by: UncleSp1d3r <[email protected]>

* refactor(evaluation): Enhance EvaluationConfig and EvaluationContext with const functions

- Updated `EvaluationConfig` in `src/lib.rs` to derive `Eq` for improved comparison capabilities.
- Refactored methods in `EvaluationContext` within `src/evaluator/mod.rs` to be `const fn`, allowing for compile-time evaluation and optimizations.
- Adjusted method signatures for `new`, `current_offset`, `set_current_offset`, `recursion_depth`, `config`, `should_stop_at_first_match`, `max_string_length`, `enable_mime_types`, `timeout_ms`, and `reset` to reflect the new const nature.
- Updated error handling in `src/io/mod.rs` to simplify path handling in error types.

These changes improve the efficiency and usability of the evaluation configuration and context, enhancing the overall robustness of the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(hooks): Update Rust code analysis and performance optimization hooks

- Modified the `rust-code-analyzer.kiro.hook` to analyze only the changed files in the current branch, enhancing its accuracy in identifying code quality issues.
- Updated the `rust-perf-optimizer.kiro.hook` to reflect the same change, ensuring performance analysis is based on the current diff.
- These updates improve the hooks' functionality and maintainability, aligning them with the project's focus on code quality and performance.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(output): Refactor MatchResult and EvaluationResult structures for enhanced clarity and functionality

- Updated the `MatchResult` struct in `src/output/mod.rs` to include additional fields such as `length`, `rule_path`, `confidence`, and `mime_type`, providing more comprehensive match information.
- Introduced the `EvaluationResult` struct to encapsulate the results of file evaluations, including metadata about the evaluation process and a vector of successful matches.
- Enhanced documentation with examples for both structs, improving usability and understanding of the evaluation results.
- Adjusted the `Cargo.toml` to modify lint settings, changing specific lints from "allow" to "warn" for better code quality enforcement.

These changes improve the output formatting module's capability to represent evaluation results, contributing to a more robust file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(output): Implement text output formatting for evaluation results

- Created a new module `text.rs` in the `src/output` directory to handle text formatting of match results, providing a human-readable output style compatible with the GNU `file` command.
- Implemented functions for formatting single and multiple match results, as well as complete evaluation results, ensuring clear and structured output.
- Updated `tasks.md` to reflect the completion of tasks related to text output formatting, including unit tests for various scenarios.

These enhancements improve the output capabilities of the library, facilitating better user interaction and understanding of file type detection results.

Signed-off-by: UncleSp1d3r <[email protected]>

* refactor(evaluator): Update function signatures and enhance error handling

- Changed `set_current_offset` and `reset` methods in `src/evaluator/mod.rs` from `const fn` to regular functions to allow for mutable state changes.
- Improved error handling in `evaluate_rules` to provide more context for rule evaluation failures, including rule message and offset in error messages.
- Enhanced `read_byte` function in `src/evaluator/types.rs` to use `.copied()` for better clarity and safety.
- Added TODOs across various modules for comprehensive error handling, validation, and performance monitoring improvements, including file metadata validation and match result checks.

These changes enhance the robustness and clarity of the evaluation logic, paving the way for improved error management and validation in the file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* docs(lib): Enhance documentation for MagicDatabase methods

- Added detailed documentation for `load_from_file` and `evaluate_file` methods in `src/lib.rs`, including arguments, error handling, and usage examples to improve clarity and usability.
- Introduced a constant `SMALL_FILE_THRESHOLD` in `src/io/mod.rs` to indicate the threshold for small file handling, enhancing code readability and maintainability.

These updates improve the overall documentation quality, making it easier for users to understand and utilize the library's functionality effectively.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(dependencies): Update development dependencies and GitHub Actions

- Added `nix` crate as a development dependency in `Cargo.toml` for enhanced file type handling capabilities.
- Updated GitHub Actions in `dist-workspace.toml` to use newer versions for `attest-build-provenance` and `upload-artifact`, ensuring compatibility and improved functionality.
- Refactored the `release.yml` workflow to utilize the updated action version for build provenance.

These changes enhance the development environment and CI/CD pipeline, contributing to a more robust and maintainable project structure.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(markdown): Simplify allowed_elements formatting in markdownlint configuration

- Reformatted the `allowed_elements` array in `.markdownlint.json` to a single line for improved readability and consistency.
- This change enhances the clarity of the configuration file without altering its functionality.

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(security): Enhance security features and validation in evaluation configuration

- Added comprehensive security documentation in `src/lib.rs`, outlining memory safety, bounds checking, resource limits, input validation, error handling, and timeout protection.
- Improved the `validate` method in `EvaluationConfig` to include checks for stack overflow, memory exhaustion, denial of service, and integer overflow vulnerabilities.
- Introduced tests for potential integer overflow vulnerabilities in offset calculations in `src/evaluator/offset.rs`.
- Enhanced the `read_byte` function in `src/evaluator/types.rs` with strict bounds checking to prevent buffer overruns and ensure secure byte reading.
- Updated `create_memory_mapping` in `src/io/mod.rs` to include security considerations for memory mapping.

These changes significantly bolster the security posture of the library, ensuring safer file type detection and evaluation processes.

Signed-off-by: UncleSp1d3r <[email protected]>

* chore(dependencies): Update nix crate to include fs feature

- Modified the `nix` dependency in `Cargo.toml` to enable the `fs` feature, enhancing file system capabilities for the project.
- Added an ignore attribute to the FIFO rejection test in `src/io/mod.rs` to prevent hanging issues in CI environments.
- Updated the text output formatting test in `src/output/text.rs` to clarify handling of Windows paths on Unix systems.

These changes improve the development environment and ensure more robust testing practices, contributing to a more reliable file type detection process.

Signed-off-by: UncleSp1d3r <[email protected]>

* fix(output): Improve cross-platform filename extraction in text formatting

- Update filename extraction logic in `format_evaluation_result` function
- Add platform-specific handling for Windows and Unix paths
- Modify test case to support different path extraction behaviors
- Ensure consistent filename display across different operating systems
- Add Windows-specific assertion for filename extraction

Signed-off-by: UncleSp1d3r <[email protected]>

* feat(output): Improve cross-platform filename extraction in text formatting

- Add cfg-if dependency to Cargo.toml for conditional compilation
- Update text output formatting test to handle different path extraction on Windows and Unix
- Implement cfg_if! macro to conditionally assert filename extraction based on platform
- Enhance test coverage for filename extraction in evaluation result formatting

Signed-off-by: UncleSp1d3r <[email protected]>

* ci(workflow): Update GitHub Actions matrix for Linux platform support

- Modify Linux platform matrix to use ubuntu-22.04 instead of generic 'arm'
- Ensure consistent and reliable Linux platform testing configuration
- Improve cross-platform compatibility for CI/CD pipeline

Signed-off-by: UncleSp1d3r <[email protected]>

---------

Signed-off-by: UncleSp1d3r <[email protected]>

Author: unclesp1d3r

.github/workflows/ci.yml

@@ -99,7 +99,7 @@ jobs:
                     # Primary Support - Linux
                     - os: ubuntu-latest
                       platform: "Linux"
-                    - os: arm
+                    - os: ubuntu-22.04
                       platform: "Linux"
                     # Primary Support - macOS (using available runners)
                     - os: macos-latest

.github/workflows/release.yml

@@ -0,0 +1,323 @@
+# This file was autogenerated by dist: https://axodotdev.github.io/cargo-dist
+#
+# Copyright 2022-2024, axodotdev
+# SPDX-License-Identifier: MIT or Apache-2.0
+#
+# CI that:
+#
+# * checks for a Git Tag that looks like a release
+# * builds artifacts with dist (archives, installers, hashes)
+# * uploads those artifacts to temporary workflow zip
+# * on success, uploads the artifacts to a GitHub Release
+#
+# Note that the GitHub Release will be created with a generated
+# title/body based on your changelogs.
+
+name: Release
+permissions:
+  "attestations": "write"
+  "contents": "write"
+  "id-token": "write"
+
+# This task will run whenever you push a git tag that looks like a version
+# like "1.0.0", "v0.1.0-prerelease.1", "my-app/0.1.0", "releases/v1.0.0", etc.
+# Various formats will be parsed into a VERSION and an optional PACKAGE_NAME, where
+# PACKAGE_NAME must be the name of a Cargo package in your workspace, and VERSION
+# must be a Cargo-style SemVer Version (must have at least major.minor.patch).
+#
+# If PACKAGE_NAME is specified, then the announcement will be for that
+# package (erroring out if it doesn't have the given version or isn't dist-able).
+#
+# If PACKAGE_NAME isn't specified, then the announcement will be for all
+# (dist-able) packages in the workspace with that version (this mode is
+# intended for workspaces with only one dist-able package, or with all dist-able
+# packages versioned/released in lockstep).
+#
+# If you push multiple tags at once, separate instances of this workflow will
+# spin up, creating an independent announcement for each one. However, GitHub
+# will hard limit this to 3 tags per commit, as it will assume more tags is a
+# mistake.
+#
+# If there's a prerelease-style suffix to the version, then the release(s)
+# will be marked as a prerelease.
+on:
+  pull_request:
+  push:
+    tags:
+      - '**[0-9]+.[0-9]+.[0-9]+*'
+
+jobs:
+  # Run 'dist plan' (or host) to determine what tasks we need to do
+  plan:
+    runs-on: "ubuntu-22.04"
+    outputs:
+      val: ${{ steps.plan.outputs.manifest }}
+      tag: ${{ !github.event.pull_request && github.ref_name || '' }}
+      tag-flag: ${{ !github.event.pull_request && format('--tag={0}', github.ref_name) || '' }}
+      publishing: ${{ !github.event.pull_request }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install dist
+        # we specify bash to get pipefail; it guards against the `curl` command
+        # failing. otherwise `sh` won't catch that `curl` returned non-0
+        shell: bash
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/axodotdev/cargo-dist/releases/download/v0.30.0/cargo-dist-installer.sh | sh"
+      - name: Cache dist
+        uses: actions/upload-artifact@v4
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/dist
+      # sure would be cool if github gave us proper conditionals...
+      # so here's a doubly-nested ternary-via-truthiness to try to provide the best possible
+      # functionality based on whether this is a pull_request, and whether it's from a fork.
+      # (PRs run on the *source* but secrets are usually on the *target* -- that's *good*
+      # but also really annoying to build CI around when it needs secrets to work right.)
+      - id: plan
+        run: |
+          dist ${{ (!github.event.pull_request && format('host --steps=create --tag={0}', github.ref_name)) || 'plan' }} --output-format=json > plan-dist-manifest.json
+          echo "dist ran successfully"
+          cat plan-dist-manifest.json
+          echo "manifest=$(jq -c "." plan-dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-plan-dist-manifest
+          path: plan-dist-manifest.json
+
+  # Build and packages all the platform-specific things
+  build-local-artifacts:
+    name: build-local-artifacts (${{ join(matrix.targets, ', ') }})
+    # Let the initial task tell us to not run (currently very blunt)
+    needs:
+      - plan
+    if: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix.include != null && (needs.plan.outputs.publishing == 'true' || fromJson(needs.plan.outputs.val).ci.github.pr_run_mode == 'upload') }}
+    strategy:
+      fail-fast: false
+      # Target platforms/runners are computed by dist in create-release.
+      # Each member of the matrix has the following arguments:
+      #
+      # - runner: the github runner
+      # - dist-args: cli flags to pass to dist
+      # - install-dist: expression to run to install dist on the runner
+      #
+      # Typically there will be:
+      # - 1 "global" task that builds universal installers
+      # - N "local" tasks that build each platform's binaries and platform-specific installers
+      matrix: ${{ fromJson(needs.plan.outputs.val).ci.github.artifacts_matrix }}
+    runs-on: ${{ matrix.runner }}
+    container: ${{ matrix.container && matrix.container.image || null }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/${{ join(matrix.targets, '-') }}-dist-manifest.json
+    steps:
+      - name: enable windows longpaths
+        run: |
+          git config --global core.longpaths true
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install Rust non-interactively if not already installed
+        if: ${{ matrix.container }}
+        run: |
+          if ! command -v cargo > /dev/null 2>&1; then
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+            echo "$HOME/.cargo/bin" >> $GITHUB_PATH
+          fi
+      - name: Install dist
+        run: ${{ matrix.install_dist.run }}
+      # Get the dist-manifest
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v5
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - name: Install cargo-auditable
+        run: ${{ matrix.install_cargo_auditable.run }}
+      - name: Install dependencies
+        run: |
+          ${{ matrix.packages_install }}
+      - name: Build artifacts
+        run: |
+          # Actually do builds and make zips and whatnot
+          dist build ${{ needs.plan.outputs.tag-flag }} --print=linkage --output-format=json ${{ matrix.dist_args }} > dist-manifest.json
+          echo "dist ran successfully"
+      - name: Attest
+        uses: actions/attest-build-provenance@v3
+        with:
+          subject-path: "target/distrib/*${{ join(matrix.targets, ', ') }}*"
+      - id: cargo-dist
+        name: Post-build
+        # We force bash here just because github makes it really hard to get values up
+        # to "real" actions without writing to env-vars, and writing to env-vars has
+        # inconsistent syntax between shell and powershell.
+        shell: bash
+        run: |
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          dist print-upload-files-from-manifest --manifest dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-build-local-${{ join(matrix.targets, '_') }}
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+
+  # Build and package all the platform-agnostic(ish) things
+  build-global-artifacts:
+    needs:
+      - plan
+      - build-local-artifacts
+    runs-on: "ubuntu-22.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      BUILD_MANIFEST_NAME: target/distrib/global-dist-manifest.json
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install cached dist
+        uses: actions/download-artifact@v5
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/
+      - run: chmod +x ~/.cargo/bin/dist
+      - name: Install cargo-cyclonedx
+        # we specify bash to get pipefail; it guards against the `curl` command
+        # failing. otherwise `sh` won't catch that `curl` return non-0
+        run: "curl --proto '=https' --tlsv1.2 -LsSf https://github.com/CycloneDX/cyclonedx-rust-cargo/releases/download/cargo-cyclonedx-0.5.5/cargo-cyclonedx-installer.sh | sh"
+        shell: bash
+      # Get all the local artifacts for the global tasks to use (for e.g. checksums)
+      - name: Fetch local artifacts
+        uses: actions/download-artifact@v5
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - id: cargo-dist
+        shell: bash
+        run: |
+          dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json
+          echo "dist ran successfully"
+
+          # Parse out what we just built and upload it to scratch storage
+          echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+          jq --raw-output ".upload_files[]" dist-manifest.json >> "$GITHUB_OUTPUT"
+          echo "EOF" >> "$GITHUB_OUTPUT"
+
+          cp dist-manifest.json "$BUILD_MANIFEST_NAME"
+      - id: cargo-cyclonedx
+        shell: bash
+        run: |
+            # Generate SBOM (.cdx.xml) files.
+            cargo cyclonedx -v
+
+            # Move all SBOM (.cdx.xml) files under target/distrib/ since
+            # we expect all artifacts to be in that folder.
+            find . -name '*.cdx.xml' -exec mv '{}' target/distrib/ ';'
+
+            echo "paths<<EOF" >> "$GITHUB_OUTPUT"
+            find . -name '*.cdx.xml' | tee -a "$GITHUB_OUTPUT"
+            echo "EOF" >> "$GITHUB_OUTPUT"
+      - name: "Upload artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-build-global
+          path: |
+            ${{ steps.cargo-dist.outputs.paths }}
+            ${{ steps.cargo-cyclonedx.output.paths }}
+            ${{ env.BUILD_MANIFEST_NAME }}
+  # Determines if we should publish/announce
+  host:
+    needs:
+      - plan
+      - build-local-artifacts
+      - build-global-artifacts
+    # Only run if we're "publishing", and only if local and global didn't fail (skipped is fine)
+    if: ${{ always() && needs.plan.outputs.publishing == 'true' && (needs.build-global-artifacts.result == 'skipped' || needs.build-global-artifacts.result == 'success') && (needs.build-local-artifacts.result == 'skipped' || needs.build-local-artifacts.result == 'success') }}
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    runs-on: "ubuntu-22.04"
+    outputs:
+      val: ${{ steps.host.outputs.manifest }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive
+      - name: Install cached dist
+        uses: actions/download-artifact@v5
+        with:
+          name: cargo-dist-cache
+          path: ~/.cargo/bin/
+      - run: chmod +x ~/.cargo/bin/dist
+      # Fetch artifacts from scratch-storage
+      - name: Fetch artifacts
+        uses: actions/download-artifact@v5
+        with:
+          pattern: artifacts-*
+          path: target/distrib/
+          merge-multiple: true
+      - id: host
+        shell: bash
+        run: |
+          dist host ${{ needs.plan.outputs.tag-flag }} --steps=upload --steps=release --output-format=json > dist-manifest.json
+          echo "artifacts uploaded and released successfully"
+          cat dist-manifest.json
+          echo "manifest=$(jq -c "." dist-manifest.json)" >> "$GITHUB_OUTPUT"
+      - name: "Upload dist-manifest.json"
+        uses: actions/upload-artifact@v4
+        with:
+          # Overwrite the previous copy
+          name: artifacts-dist-manifest
+          path: dist-manifest.json
+      # Create a GitHub Release while uploading all files to it
+      - name: "Download GitHub Artifacts"
+        uses: actions/download-artifact@v5
+        with:
+          pattern: artifacts-*
+          path: artifacts
+          merge-multiple: true
+      - name: Cleanup
+        run: |
+          # Remove the granular manifests
+          rm -f artifacts/*-dist-manifest.json
+      - name: Create GitHub Release
+        env:
+          PRERELEASE_FLAG: "${{ fromJson(steps.host.outputs.manifest).announcement_is_prerelease && '--prerelease' || '' }}"
+          ANNOUNCEMENT_TITLE: "${{ fromJson(steps.host.outputs.manifest).announcement_title }}"
+          ANNOUNCEMENT_BODY: "${{ fromJson(steps.host.outputs.manifest).announcement_github_body }}"
+          RELEASE_COMMIT: "${{ github.sha }}"
+        run: |
+          # Write and read notes from a file to avoid quoting breaking things
+          echo "$ANNOUNCEMENT_BODY" > $RUNNER_TEMP/notes.txt
+
+          gh release create "${{ needs.plan.outputs.tag }}" --target "$RELEASE_COMMIT" $PRERELEASE_FLAG --title "$ANNOUNCEMENT_TITLE" --notes-file "$RUNNER_TEMP/notes.txt" artifacts/*
+
+  announce:
+    needs:
+      - plan
+      - host
+    # use "always() && ..." to allow us to wait for all publish jobs while
+    # still allowing individual publish jobs to skip themselves (for prereleases).
+    # "host" however must run to completion, no skipping allowed!
+    if: ${{ always() && needs.host.result == 'success' }}
+    runs-on: "ubuntu-22.04"
+    env:
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          submodules: recursive