Skip to main content
The Palyra release process is a multi-stage pipeline designed to ensure artifact coherence, cross-platform compatibility, and runtime safety. It encompasses the generation of portable archives, desktop-specific installation logic, and a rigorous “smoke test” suite that validates the system’s behavior in clean environments. The process is governed by a regression matrix that enforces consistency between the code, documentation, and release readiness criteria.

​
Packaging Architecture

Palyra utilizes PowerShell and Bash scripts to orchestrate the packaging of binaries and assets into distribution-ready archives. The primary packaging logic resides in scripts/release/package-portable.ps1, which supports two main artifact kinds: desktop and headless scripts/release/package-portable.ps1#1-16.

​
Portable Archive Structure

Archives are generated as ZIP files containing a specific “payload” layout required for the application to function in a portable or installed state.
ComponentDescriptionSource
palyraThe primary CLI entry point.palyra-cli
palyradThe core gateway daemon.palyra-daemon
palyra-browserdThe browser automation service.palyra-browserd
palyra-desktop-control-center(Desktop only) The Tauri-based GUI supervisor.apps/desktop
web/Bundled React dashboard assets.apps/web/dist
docs/help_snapshots/Offline CLI help documentation.crates/palyra-cli/tests/help_snapshots
deployment/Generated deployment recipes (e.g., single-vm).Generated via palyra deployment recipe
The package-portable.ps1 script validates the existence of all required binaries and assets before staging them scripts/release/package-portable.ps1#40-59. It also calculates SHA-256 hashes for all binary entries to ensure integrity scripts/release/package-portable.ps1#74-79.

​
Data Flow: Packaging to Metadata

The following diagram illustrates how raw build artifacts are transformed into a versioned release bundle with associated metadata. Release Packaging Data Flow Sources: scripts/release/package-portable.ps1#24-37, scripts/release/package-portable.ps1#63-80, scripts/release/package-portable.ps1#116-126

​
Installation and CLI Exposure

Palyra provides specialized installation scripts for different environments. These scripts manage binary placement, environment variables, and “CLI exposure”—the process of making the palyra command available in the user’s shell.

​
Desktop Installation

scripts/release/install-desktop-package.ps1 handles the setup of the desktop bundle. It:
  1. Extracts the archive to the specified InstallRoot scripts/release/install-desktop-package.ps1#24-25.
  2. Sets executable permissions on all binaries scripts/release/install-desktop-package.ps1#30-32.
  3. Configures “CLI Exposure” using Install-PalyraCliExposure, which may involve creating shims or updating the system PATH scripts/release/install-desktop-package.ps1#42-47.
  4. Performs an initial setup in local mode to initialize the configuration scripts/release/install-desktop-package.ps1#58-65.

​
Headless Installation

scripts/release/install-headless-package.ps1 is tailored for server environments. In addition to standard binary setup, it can generate a systemd unit file for palyrad on Linux systems, ensuring the daemon persists across reboots scripts/release/install-headless-package.ps1#90-114.

​
Uninstallation and Cleanup

The scripts/release/uninstall-package.ps1 and scripts/test/uninstall-clean-desktop.ps1 scripts provide a clean teardown. This includes stopping running processes, removing binary shims, and optionally deleting the StateRoot where runtime data (journals, memory) is stored scripts/test/uninstall-clean-desktop.ps1#20-40, scripts/test/uninstall-clean-desktop.ps1#168-185. Sources: scripts/release/install-desktop-package.ps1#1-127, scripts/release/install-headless-package.ps1#1-141, scripts/test/uninstall-clean-desktop.ps1#1-190

​
Release Readiness and Smoke Tests

Before a release is finalized, it must pass a series of automated gates defined in the infra/release/ directory.

​
Release Smoke Test

The scripts/test/run-release-smoke.ps1 script executes a battery of tests against a freshly installed package. It validates:

​
Workflow Regression Matrix

The infra/release/workflow-regression-matrix.json defines the canonical “acceptance scenarios” that must pass for a release to be considered stable. It supports two profiles:

​
Code-to-Manifest Consistency

The crates/palyra-cli/tests/workflow_regression_contract.rs test ensures that the actual code implementation of runtime capabilities matches the definitions in the regression matrix crates/palyra-cli/tests/workflow_regression_contract.rs#1-46. It validates that every RuntimePreviewCapability defined in palyra-common is represented in the release readiness checklist crates/palyra-cli/tests/workflow_regression_contract.rs#87-104. Workflow Regression Entity Map Sources: crates/palyra-common/src/runtime_preview.rs#73-83, infra/release/workflow-regression-matrix.json#1-121, crates/palyra-cli/tests/workflow_regression_contract.rs#46-52

​
Deployment Promotion and Rollout Gates

Palyra uses “Compatibility Hardening Readiness” checks to gate the rollout of new features, particularly those in “Runtime Preview.”

​
Rollout Controls

The infra/release/compat-hardening-readiness.json file tracks the state of specific subsystems (e.g., retrieval_dual_path, networked_worker_preview_rollout). These controls ensure that features remain “fail-closed” or disabled by default until they meet the required evidence criteria infra/release/compat-hardening-readiness.json#6-37.

​
Evidence Requirements

Promotion to a stable release requires evidence from multiple sources:
  1. Workflow Regression (Fast/Full): Must pass specific scenarios like queued_input_lifecycle_contract or dual_path_retrieval_runtime_diagnostics infra/release/compat-hardening-readiness.json#75-165.
  2. Migration Tracks: Validates that runtime contracts and config schemas have been properly adopted before widening the rollout infra/release/compat-hardening-readiness.json#38-57.

​
Known Limitations

The readiness checklist explicitly documents limitations, such as the networked_worker_execution_remains_preview_only state, which prevents accidental promotion of unfinished distributed execution features infra/release/compat-hardening-readiness.json#58-74. Sources: infra/release/compat-hardening-readiness.json#1-165, crates/palyra-cli/src/workflow_regression.rs#1-100