Update System

Update System

Self-update management for CortexPrism, supporting both binary and source installation modes with automatic health checks and safe rollback.

Architecture

Four files in src/update/:

File	Purpose
checker.ts	GitHub releases API client, semver comparison, caching
installer.ts	Binary and source update installation, manifest tracking
rollback.ts	Health check validation and rollback with grace period
mod.ts	Orchestration: lock-based update flow, status API

Update Flow

check → acquire lock → clear stale cache → fetch releases
  → evaluate (up-to-date? → done)
  → download & install (binary or source)
  → run migrations
  → health check
    → pass: success
    → fail: auto-rollback → report
  → release lock

Lock Mechanism

Updates use a file-based lock (update.lock) with a 10-minute staleness timeout. Only one update can be in progress at a time. The lock stores the PID of the updating process.

Binary vs Source Mode

Detection is automatic based on Deno.execPath():

Mode	Detection	Install Method
Binary	Executable name is cortex (not deno)	Download platform archive, extract, replace binary
Source	Running via deno	git checkout target tag, or fallback to tarball download

Platform Assets

Platform	Asset Name
x86_64-linux	cortex-x86_64-linux.tar.gz
aarch64-linux	cortex-aarch64-linux.tar.gz
x86_64-darwin	cortex-x86_64-darwin.tar.gz
aarch64-darwin	cortex-aarch64-darwin.tar.gz
x86_64-windows	cortex-x86_64-windows.zip

Binary Install Process

1. Resolve platform asset from release
2. Download archive to temp directory
3. Extract (tar.gz via tar, .zip via unzip or PowerShell)
4. Backup current binary as <binaryPath>.<oldVersion>
5. Copy and chmod +x new binary
6. Run database migrations
7. Update manifest

Source Install Process

1. Attempt git fetch --tags origin + git checkout v<version>
2. Check for dirty working tree (refuse unless --force)
3. If git checkout fails (no .git dir), fall back to tarball download
4. Run database migrations
5. Update manifest

Health Check Validation

After installation, healthCheck() validates the new version:

Mode	Check Method
Binary	Run <binaryPath> --version and verify output contains expected version
Source	Read VERSION file or deno.json version field

Rollback

Binary Rollback

1. Move current (failed) binary to <binary>.failed
2. Restore <binary>.<oldVersion> to <binary>
3. chmod +x
4. Run health check on restored binary

Source Rollback

1. git fetch --tags origin
2. git checkout v<previousVersion>
3. Update manifest
4. Run health check

Grace Period

A 24-hour grace period (GRACE_PERIOD_MS) applies to backup cleanup. A periodic timer runs every hour to remove backup binaries older than the grace period. Backups are cleaned up via cleanupOldBackups().

Configuration

{
  "update": {
    "channel": "stable",
    "checkOnStartup": true,
    "autoUpdate": false,
    "githubToken": "ghp_..."
  }
}

Key	Type	Default	Description
channel	"stable" | "pre-release"	"stable"	Release channel
checkOnStartup	boolean	true	Check for updates on startup
autoUpdate	boolean	false	Auto-apply updates
githubToken	string	—	GitHub PAT for higher API rate limits

Release Channel

Channel	Behavior
stable	Only non-prerelease releases
pre-release	All releases including prereleases

Caching

Release data is cached for 5 minutes in the update cache file (updateCache path). Cache is cleared during applyUpdate() to force a fresh fetch.

Rate Limiting

Without a GitHub token, the unauthenticated API rate limit is 60 requests/hour. When the rate limit is exceeded, the system falls back to cached data or returns an error.

Checksum & Signature Verification

Function	Description
verifyChecksums(release, binaryPath)	Downloads checksums.txt, computes SHA-256 of binary, compares
verifyGpgSignature(release, gpgKeyPath)	Downloads checksums.txt.asc, imports GPG key, verifies signature

CLI

cortex update check                       # Check for available updates
cortex update status                      # Show current version and update status
cortex update apply                       # Download and install latest update
cortex update apply --channel pre-release # Use pre-release channel
cortex update apply --force               # Force update (skip dirty tree check)
cortex update rollback                    # Rollback to previous version

REST API

Method	Path	Description
GET	/api/update/status	Get current version and update availability
POST	/api/update/check	Trigger update check
POST	/api/update/apply	Apply available update
POST	/api/update/rollback	Rollback to previous version

Update Status Response

{
  "currentVersion": "1.2.3",
  "latestVersion": "1.3.0",
  "updateAvailable": true,
  "channel": "stable",
  "installType": "binary",
  "lastChecked": "2026-06-19T08:48:04.000Z"
}

See Also

• Eval System — Regression detection after updates
• Distributed Nodes — Node version compatibility
• Projects — Project isolation with versioning