Installer Transaction System
Relevant source files
The following files were used as context for generating this wiki page:
The Installer Transaction System is a robust framework introduced in v0.37.0 to manage the installation and update lifecycle of the Orcy platform. It converts the @orcy/installer from an append-only log into a transactional system featuring crash recovery, atomic writes, and idempotency. The system ensures that partial installations do not leave the host machine in an inconsistent state by utilizing a two-file model consisting of a transient Journal and a committed Manifest.
Sources: README.md:167-167, CHANGELOG.md:12-12
System Architecture
The architecture relies on a "transactional" approach to local environment modification. Before any file is written or service is registered, the intent and progress are recorded in a journal.
Core Components
| Component | Description |
|---|---|
| Transient Journal | A per-step transaction record that tracks in-flight operations. It is unlinked only upon successful completion. |
| Committed Manifest | The permanent ledger of installed artifacts, built from the journal's "done" entries. It includes hashes to detect user modifications. |
| Atomic Writer | A utility using temp + fsync + rename patterns to prevent file corruption during crashes. |
| Wizard | The interactive/CLI entry point that orchestrates the lifecycle, including stale-journal detection and recovery. |
Sources: CHANGELOG.md:12-12, CHANGELOG.md:104-104, packages/installer/src/wizard.ts:241-245
Transaction Lifecycle Flow
This diagram illustrates how the installer handles a standard installation versus a recovery scenario.
Journaling and Record Keeping
The system tracks every action—such as created, fenced, merged-json, and copied—to ensure they can be verified or reversed.
Step Recording
Every significant modification to the filesystem or system services is routed through the record() function. In v0.37.0, this was updated to deduplicate records based on the {path, action} pair, preventing the manifest from growing indefinitely during repeated updates.
Sources: CHANGELOG.md:16-16, packages/installer/test/characterizes-install.test.ts:46-51
Two-Phase Registration
Special handling is implemented for agent registration. The journal supports two-phase sub-stepping for the registerAgent step. This allows the system to distinguish between a remote POST request that succeeded (creating an orphaned agent on the server) and one that never ran, facilitating proper compensation during rollback.
Sources: CHANGELOG.md:104-104, packages/installer/src/wizard.ts:127-135
Recovery and Rollback Logic
The system identifies "stale" journals—leftovers from interrupted processes—and provides multiple recovery paths.
Viability Assessment
The function isJournalViable determines if an install can be resumed. For example, if a registerAgent step reached the remote POST phase but failed to write local credentials, it is marked as non-viable to prevent the creation of duplicate remote agents.
Sources: CHANGELOG.md:52-52, packages/installer/src/wizard.ts:121-125
Recovery Actions
Users are presented with three primary options when a stale journal is detected:
- Resume: Discards the journal and re-runs the install; idempotency ensures completed steps converge.
- Rollback: Actively reverses completed steps (deleting files, stopping services) to return to a clean state.
- Abort: Stops the process and preserves the journal for manual inspection.
Sources: packages/installer/src/wizard.ts:153-176, CHANGELOG.md:163-163
Rollback Sequence
Rollback follows a strict inverse order of installation to ensure dependencies are handled correctly.
Verification and Maintenance
The system provides tools for auditing the state of the installation against the recorded manifest.
- Doctor: A liveness probe that checks for interrupted installs (stale journals), service status, and general environment health.
- Verify: A consistency auditor that cross-references the manifest against the actual disk state. it reports missing paths, duplicate entries, and orphaned footprint directories.
Sources: CHANGELOG.md:139-143, packages/installer/src/wizard.ts:316-316
Artifact Integrity
To prevent data loss, uninstallAll and rollbackJournal detect user modifications. Files like package.json or custom skill directories are hash-checked. If the current hash does not match the recorded installation hash, the system preserves the file and warns the user instead of deleting it.
Sources: CHANGELOG.md:118-121, packages/installer/src/install-packages.ts:98-100
Conclusion
The Installer Transaction System provides a high-integrity deployment mechanism for Orcy. By combining atomic operations, metadata-aware manifest entries, and a robust journaling system, it ensures that AI agent environments remain consistent even across unexpected failures or complex update chains.