Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Mutex, MutexGuard};
use hiroute_application_api::{
ApplyRequestV1, ErrorCode, PreviewRequestV1, PreviewResultV1, PrincipalKind, command_by_id,
};
use hiroute_domain::{
AgentAccessGrantMutationKindV1, CanonicalDigest, CompensationOutcome, ComputeSourceControlPort,
ControlRepositoryPort, CredentialPoolControlPort, EffectReconciliation, ExternalEffectPort,
OperationId, OperationState, OperationStepKind, OperationStepStatus, OperationV1,
OwnedEffectKind, OwnedEffectV1, PortError, RevisionMismatch, RuntimeStatePort,
SecretMutationKind, SecretStorePort, WorkspaceId,
};
use serde::Serialize;
use thiserror::Error;
use crate::change::{
ChangePreparationError, ConnectionOptionAuthorizationPort, PreparedPreview, ProtectedInputPort,
prepare_preview,
};
mod agent_access_grants;
mod compute_compensation;
mod execution;
mod prepared;
pub use prepared::PreparedTransactionV1;
pub(crate) mod control;
pub struct AcceptedApply {
operation: OperationV1,
existing: bool,
}
impl AcceptedApply {
pub fn operation(&self) -> &OperationV1 {
&self.operation
}
pub const fn existing(&self) -> bool {
self.existing
}
}
/// Principal identity established by authenticated local transport. This sealed type is not
/// serde/wire constructible and is the only identity accepted by the transaction engine.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VerifiedPrincipal {
scope: String,
local_control: bool,
}
impl VerifiedPrincipal {
pub fn from_protected_launcher(kind: PrincipalKind) -> Result<Self, TransactionError> {
let scope = match kind {
PrincipalKind::InteractiveUser => "interactive-user",
PrincipalKind::Desktop => "desktop",
PrincipalKind::Skill | PrincipalKind::SealedCollaboration => {
return Err(TransactionError::CapabilityDenied);
}
};
Ok(Self {
scope: scope.to_owned(),
local_control: false,
})
}
/// Process-local authority for the bounded maintenance of an already confirmed subscription.
/// It has no wire representation and is accepted only with an exact one-shot capability.
pub fn for_subscription_maintenance() -> Self {
Self {
scope: "daemon-subscription-maintenance".to_owned(),
local_control: false,
}
}
/// Identity established by the owner-only Local Control socket and peer UID check. It has no
/// wire token and is accepted only by explicitly Released local mutation paths.
pub fn for_local_control() -> Self {
Self {
scope: "interactive-user".to_owned(),
local_control: true,
}
}
}
/// One per hirouted process. It starts closed, serializes every writer, and opens only after all
/// durable admitted Operations have been reconciled.
#[derive(Debug, Default)]
pub struct TransactionRuntime {
writer: Mutex<()>,
writes_open: AtomicBool,
}
impl TransactionRuntime {
fn lock_writer(&self) -> Result<MutexGuard<'_, ()>, TransactionError> {
self.writer
.lock()
.map_err(|_| TransactionError::RecoveryRequired)
}
}
pub struct TransactionCoordinator<'a, C, S, R, E, I> {
control: &'a C,
secrets: &'a S,
runtime: &'a R,
external: &'a E,
protected_inputs: &'a I,
admission: &'a TransactionRuntime,
}
impl<'a, C, S, R, E, I> TransactionCoordinator<'a, C, S, R, E, I>
where
C: ControlRepositoryPort
+ ComputeSourceControlPort
+ CredentialPoolControlPort
+ ConnectionOptionAuthorizationPort,
S: SecretStorePort,
R: RuntimeStatePort,
E: ExternalEffectPort,
I: ProtectedInputPort,
{
pub fn new(
control: &'a C,
secrets: &'a S,
runtime: &'a R,
external: &'a E,
protected_inputs: &'a I,
admission: &'a TransactionRuntime,
) -> Self {
Self {
control,
secrets,
runtime,
external,
protected_inputs,
admission,
}
}
pub fn reconcile_startup_and_open(&self) -> Result<Vec<OperationV1>, TransactionError> {
let _writer = self.admission.lock_writer()?;
self.admission.writes_open.store(false, Ordering::Release);
let operations = self.control.recoverable_operations()?;
let mut recovered = Vec::with_capacity(operations.len());
for operation in operations {
let terminal = self.run_current_or_reload_locked(operation, false)?;
if terminal.state == OperationState::NeedsAttention {
return Err(TransactionError::RecoveryRequired);
}
recovered.push(terminal);
}
if self.control.writer_recovery_required()? {
return Err(TransactionError::RecoveryRequired);
}
self.admission.writes_open.store(true, Ordering::Release);
Ok(recovered)
}
pub fn preview(
&self,
workspace: &WorkspaceId,
request: PreviewRequestV1,
) -> Result<PreviewResultV1, TransactionError> {
if hiroute_domain::CHANGE_SPEC_SCHEMA_V1
.negotiate(request.schema_version)
.is_none()
{
return Err(TransactionError::InvalidArguments);
}
let revisions = self.control.current_revisions(workspace)?;
Ok(prepare_preview(
self.secrets,
self.runtime,
self.external,
self.protected_inputs,
self.control,
request,
revisions,
)?
.result)
}
/// Applies the exact ordering contract: lookup idempotency first, then target/dependency
/// revisions, then normalization/digest, and only then the first durable write.
pub fn accept(
&self,
workspace: &WorkspaceId,
principal: &VerifiedPrincipal,
request: ApplyRequestV1,
) -> Result<AcceptedApply, TransactionError> {
if hiroute_domain::CHANGE_SPEC_SCHEMA_V1
.negotiate(request.schema_version)
.is_none()
{
return Err(TransactionError::InvalidArguments);
}
let descriptor = command_by_id(&request.spec.command_id)
.filter(|descriptor| descriptor.kind == hiroute_application_api::CommandKind::Apply)
.ok_or(TransactionError::InvalidArguments)?;
self.accept_with_reproduced_plan(
workspace,
principal,
&descriptor.operation_id,
request,
|current, request| {
let PreparedPreview { result, plan } = prepare_preview(
self.secrets,
self.runtime,
self.external,
self.protected_inputs,
self.control,
PreviewRequestV1::new(request.spec.clone()),
current.clone(),
)?;
for intent in plan.external() {
self.external.validate_external_admission(intent)?;
}
Ok((result.change_digest, plan))
},
)
}
/// Consume the sealed admission result. A concurrent writer forces a fresh durable read.
pub fn run_accepted(&self, accepted: AcceptedApply) -> Result<OperationV1, TransactionError> {
let _writer = self.admission.lock_writer()?;
self.run_current_or_reload_locked(accepted.operation, true)
}
fn run_current_or_reload_locked(
&self,
operation: OperationV1,
retry_tail: bool,
) -> Result<OperationV1, TransactionError> {
if self.control.operation_is_current(&operation)? {
self.run_operation_locked(operation, retry_tail)
} else {
self.run_locked(&operation.operation_id, retry_tail)
}
}
pub fn run(&self, operation_id: &OperationId) -> Result<OperationV1, TransactionError> {
let _writer = self.admission.lock_writer()?;
self.run_locked(operation_id, true)
}
fn run_locked(
&self,
operation_id: &OperationId,
retry_tail: bool,
) -> Result<OperationV1, TransactionError> {
let operation = self
.control
.load_operation(operation_id)?
.ok_or(TransactionError::OperationNotFound)?;
self.run_operation_locked(operation, retry_tail)
}
fn run_operation_locked(
&self,
mut operation: OperationV1,
retry_tail: bool,
) -> Result<OperationV1, TransactionError> {
if operation.state == OperationState::NeedsAttention {
// A previous build may have parked after every effect was compensated but before
// the terminal proof completed. Recheck exact ownership; never release the writer
// for an effect whose compensation remains uncertain.
if operation
.steps
.iter()
.all(|step| step.status == OperationStepStatus::Compensated)
&& self.reconcile_terminal_rollback(&operation).is_ok()
{
operation.transition(OperationState::RolledBack)?;
self.control.finish_operation(&mut operation)?;
self.external.finish_publication_activation(&operation)?;
}
return Ok(operation);
}
if operation.state.is_terminal() {
return Ok(operation);
}
if operation.state == OperationState::RollingBack {
return self.finish_rollback(operation, "RECOVERY_ROLLBACK");
}
if let Some(receipt) = settings_service_receipt(&operation) {
return self.resume_settings_tail(operation, &receipt, retry_tail);
}
for kind in OperationStepKind::ALL {
if operation.step(kind).status == OperationStepStatus::Applied
&& kind != OperationStepKind::Activate
{
continue;
}
if let Err(error) = self.run_step(&mut operation, kind) {
if let Some(conflict) = error.model_budget_conflict() {
operation.step_mut(kind).terminal_result = Some(
serde_json::to_string(conflict).expect("safe capacity facts serialize"),
);
operation.safe_error_code = Some(error.safe_code().to_owned());
// Publication abort checks the durable journal's exact ownership. Persist
// the diagnostic first so rollback observes the same operation snapshot.
self.control.save_operation(&mut operation)?;
}
if let Some(receipt) = settings_service_receipt(&operation)
&& matches!(
settings_service_completion_digest(
&operation,
receipt.publication_revision,
&receipt.publication_digest,
),
Ok(expected) if expected == receipt.completed_effects_digest
)
{
// The service segment is durably complete; only the client file tail
// remains, so parking must never roll the publication back.
operation.safe_error_code = Some(error.safe_code().to_owned());
self.control.save_operation_tail(&mut operation)?;
return Ok(operation);
}
let code = error.safe_code();
return self.finish_rollback(operation, code);
}
}
self.finish_success(operation)
}
fn finish_success(&self, mut operation: OperationV1) -> Result<OperationV1, TransactionError> {
if let Err(error) = self.reconcile_terminal_success(&mut operation) {
let code = error.safe_code();
return self.finish_rollback(operation, code);
}
let is_price_change = operation.plan.source_price_change().is_some();
if is_price_change || operation.plan.compute_source().is_some() {
match self.external.install_source_price_snapshot(&operation) {
Ok(generation) if is_price_change => {
operation
.step_mut(OperationStepKind::Activate)
.terminal_result = Some(
serde_json::to_string(&generation)
.map_err(|_| TransactionError::InvalidArguments)?,
);
operation.safe_error_code = None;
self.control.save_operation(&mut operation)?;
}
Err(_) if is_price_change => {
// Configuration has committed; do not roll it back or accept a newer writer
// while this generation still needs installation. Restart resumes this step.
self.admission.writes_open.store(false, Ordering::Release);
operation.safe_error_code = Some("PRICE_RECOVERY_REQUIRED".into());
self.control.save_operation(&mut operation)?;
return Err(TransactionError::RecoveryRequired);
}
_ => (),
}
}
operation.transition(OperationState::Succeeded)?;
self.control.finish_operation(&mut operation)?;
self.external.finish_publication_activation(&operation)?;
Ok(operation)
}
/// A settings operation whose service segment is sealed by a completion receipt. The
/// client-file tail is retried only on an explicit run; startup reports it untouched.
fn resume_settings_tail(
&self,
operation: OperationV1,
receipt: &hiroute_domain::SettingsServiceCompletionV1,
retry_tail: bool,
) -> Result<OperationV1, TransactionError> {
if !matches!(
settings_service_completion_digest(
&operation,
receipt.publication_revision,
&receipt.publication_digest,
),
Ok(expected) if expected == receipt.completed_effects_digest
) {
return self.finish_rollback(operation, "SETTINGS_RECEIPT_INVALID");
}
for intent in operation
.plan
.external()
.iter()
.filter(|intent| intent.kind() == OwnedEffectKind::Publication)
{
match self.external.observe_external(&operation, intent)? {
EffectReconciliation::Applied(_) => {}
// The receipt cannot prove the service segment; the generic path re-verifies it.
EffectReconciliation::Staged(_) | EffectReconciliation::Missing => {
let mut operation = operation;
operation
.step_mut(OperationStepKind::Activate)
.terminal_result = None;
self.control.save_operation(&mut operation)?;
return self.run_steps_and_finish(operation);
}
// A later publication replaced this tail's root: expired, never rewrite files.
EffectReconciliation::OwnershipLost(_) => {
let mut operation = operation;
operation.safe_error_code = Some("SETTINGS_TAIL_EXPIRED".into());
self.control.save_operation_tail(&mut operation)?;
return Ok(operation);
}
}
}
let files_applied = operation
.plan
.external()
.iter()
.filter(|intent| hiroute_domain::is_settings_managed_configuration(intent))
.all(|intent| {
matches!(
self.external.observe_external(&operation, intent),
Ok(EffectReconciliation::Applied(_))
)
});
if files_applied {
// The files were already switched; complete the terminal record, never rewrite.
return self.run_steps_and_finish(operation);
}
if !retry_tail {
// Startup only reports a pending tail: no file writes and no writer retention. The
// generic adapter code cannot express "service done, file tail awaiting retry".
let mut operation = operation;
operation.safe_error_code = Some("SETTINGS_TAIL_PENDING".into());
self.control.save_operation_tail(&mut operation)?;
return Ok(operation);
}
// Explicit same-operation retry: re-acquire the claim, then only the file tail runs.
self.control
.reclaim_operation_writer(&operation.operation_id)?;
let mut operation = self
.control
.load_operation(&operation.operation_id)?
.ok_or(TransactionError::OperationNotFound)?;
match self.activate_settings_file_tail(&mut operation) {
Ok(()) => {
// The explicit tail retry bypasses run_step; complete its step journal before
// publishing terminal success so strict history readers can verify the result.
operation.step_mut(OperationStepKind::Activate).status =
OperationStepStatus::Applied;
operation.safe_error_code = None;
self.control.save_operation(&mut operation)?;
self.finish_success(operation)
}
Err(error) => {
operation.safe_error_code = Some(error.safe_code().to_owned());
self.control.save_operation_tail(&mut operation)?;
Ok(operation)
}
}
}
fn run_steps_and_finish(
&self,
mut operation: OperationV1,
) -> Result<OperationV1, TransactionError> {
for kind in OperationStepKind::ALL {
if operation.step(kind).status == OperationStepStatus::Applied
&& kind != OperationStepKind::Activate
{
continue;
}
if let Err(error) = self.run_step(&mut operation, kind) {
let code = error.safe_code();
return self.finish_rollback(operation, code);
}
}
self.finish_success(operation)
}
pub fn recover_all(&self) -> Vec<Result<OperationV1, TransactionError>> {
match self.control.recoverable_operations() {
Ok(operations) => operations
.into_iter()
.map(|operation| {
let _writer = self.admission.lock_writer()?;
self.run_current_or_reload_locked(operation, true)
})
.collect(),
Err(error) => vec![Err(TransactionError::Port(error))],
}
}
/// A step journal saying `Applied` is not sufficient evidence for terminal success. Every
/// exact-owned adapter marker and committed view is re-authenticated at the terminal boundary.
fn reconcile_terminal_success(
&self,
operation: &mut OperationV1,
) -> Result<(), TransactionError> {
for mutation in operation.plan.secrets().to_vec() {
require_applied(
self.secrets
.observe_secret(&operation.operation_id, &mutation)?,
)?;
}
self.require_agent_access_grants_applied(operation)?;
require_applied(
self.control
.observe_control(&operation.operation_id, &operation.workspace_id)?,
)?;
for intent in operation.plan.external().to_vec() {
require_applied(self.external.observe_external(operation, &intent)?)?;
}
for mutation in operation.plan.runtime().to_vec() {
require_applied(
self.runtime
.observe_runtime(&operation.operation_id, &mutation)?,
)?;
}
Ok(())
}
fn record_effect(
&self,
operation: &mut OperationV1,
step: OperationStepKind,
effect: OwnedEffectV1,
) -> Result<(), TransactionError> {
let journal = operation.step_mut(step);
if let Some(existing) = journal
.effects
.iter_mut()
.find(|existing| existing.effect_id == effect.effect_id)
{
if *existing == effect {
return Ok(());
}
*existing = effect;
} else {
journal.effects.push(effect);
}
self.control.save_operation(operation)?;
Ok(())
}
fn finish_rollback(
&self,
mut operation: OperationV1,
safe_error_code: &str,
) -> Result<OperationV1, TransactionError> {
// A publication may have crossed a durable boundary before its adapter returned.
// Obtain and persist the abort decision before compensating ANY dependent effect.
for effect in operation
.step(OperationStepKind::CompilePublication)
.effects
.clone()
{
match self
.external
.prepare_publication_rollback(&operation, &effect)
{
Ok(checkpoint) => self.record_effect(
&mut operation,
OperationStepKind::CompilePublication,
checkpoint,
)?,
Err(error) if error.code == hiroute_domain::PortErrorCode::Unavailable => {
self.admission.writes_open.store(false, Ordering::Release);
operation.safe_error_code = Some("PUBLICATION_RECOVERY_REQUIRED".to_owned());
self.control.save_operation(&mut operation)?;
return Err(TransactionError::RecoveryRequired);
}
Err(_) => {
self.admission.writes_open.store(false, Ordering::Release);
if operation.state != OperationState::RollingBack {
operation.transition(OperationState::RollingBack)?;
}
operation.transition(OperationState::NeedsAttention)?;
operation.safe_error_code =
Some("PUBLICATION_OWNERSHIP_UNCONFIRMED".to_owned());
self.control.finish_operation(&mut operation)?;
return Ok(operation);
}
}
}
if safe_error_code != "RECOVERY_ROLLBACK" || operation.model_budget_conflict().is_none() {
operation.safe_error_code = Some(safe_error_code.to_owned());
}
if operation.state != OperationState::RollingBack {
operation.transition(OperationState::RollingBack)?;
}
self.control.save_operation(&mut operation)?;
let mut uncertain = false;
for kind in OperationStepKind::ALL.into_iter().rev() {
if operation.step(kind).status == OperationStepStatus::Compensated {
continue;
}
operation.step_mut(kind).status = OperationStepStatus::Compensating;
self.control.save_operation(&mut operation)?;
let reconciliation = self.reconcile_step_for_rollback(&mut operation, kind);
// Reconciliation uncertainty must not prevent best-effort compensation of the
// other effects that still prove exact Operation ownership.
let compensation = self.compensate_step(&operation, kind);
let restored_stage_discarded = execution::is_settings_restoration(&operation)
&& kind == OperationStepKind::ApplyAgentArtifacts
&& compensation.is_ok()
&& operation
.plan
.external()
.iter()
.filter(|intent| intent.kind() == OwnedEffectKind::AgentArtifact)
.all(|intent| {
matches!(
self.external.observe_external(&operation, intent),
Ok(EffectReconciliation::Missing)
)
});
let outcome = match (reconciliation, compensation) {
(Ok(()), Ok(())) => Ok(()),
(Err(_), Ok(())) if restored_stage_discarded => Ok(()),
_ => Err(TransactionError::EffectOwnershipLost),
};
match outcome {
Ok(()) => {
let step = operation.step_mut(kind);
step.status = OperationStepStatus::Compensated;
// Keep the frozen rejection through compensation and restart. It has no
// effect ownership or replay authority; status projection validates its schema.
if step
.terminal_result
.as_deref()
.and_then(hiroute_domain::AgentModelBudgetConflictV1::parse)
.is_none()
{
step.terminal_result = Some("compensated".to_owned());
}
}
Err(_) => {
uncertain = true;
let step = operation.step_mut(kind);
step.status = OperationStepStatus::Attention;
step.terminal_result = Some("ownership_unconfirmed".to_owned());
}
}
self.control.save_operation(&mut operation)?;
}
if !uncertain && self.reconcile_terminal_rollback(&operation).is_err() {
uncertain = true;
}
if uncertain {
operation.transition(OperationState::NeedsAttention)?;
} else {
operation.transition(OperationState::RolledBack)?;
}
self.control.finish_operation(&mut operation)?;
self.external.finish_publication_activation(&operation)?;
Ok(operation)
}
fn reconcile_terminal_rollback(&self, operation: &OperationV1) -> Result<(), TransactionError> {
// Re-run every recorded compensation by exact ownership token. `AlreadyCompensated` is
// positive durable evidence; a vanished/corrupt marker is uncertainty, not proof that the
// effect never existed.
for kind in OperationStepKind::ALL.into_iter().rev() {
for effect in operation.step(kind).effects.iter().rev() {
require_compensated(self.compensate_effect(operation, effect)?)?;
}
}
for mutation in operation.plan.secrets() {
require_missing(
self.secrets
.observe_secret(&operation.operation_id, mutation)?,
)?;
}
self.require_agent_access_grants_missing(operation)?;
require_missing(
self.control
.observe_control(&operation.operation_id, &operation.workspace_id)?,
)?;
for intent in operation.plan.external() {
if intent.kind() == OwnedEffectKind::LoginItem {
// Desktop performs and, on a definitive rollback, compensates this action.
// The daemon's observation is the host's original declaration, so it stays
// "Applied" even after every daemon-owned effect is gone.
continue;
}
require_missing(self.external.observe_external(operation, intent)?)?;
}
for mutation in operation.plan.runtime() {
require_missing(
self.runtime
.observe_runtime(&operation.operation_id, mutation)?,
)?;
}
self.reconcile_compute_compensation(operation)?;
Ok(())
}
fn reconcile_step_for_rollback(
&self,
operation: &mut OperationV1,
kind: OperationStepKind,
) -> Result<(), TransactionError> {
let mut ownership_lost = false;
match kind {
OperationStepKind::Prepare => {}
OperationStepKind::ApplySecrets => {
for mutation in operation.plan.secrets().to_vec() {
match self
.secrets
.observe_secret(&operation.operation_id, &mutation)?
{
EffectReconciliation::Missing => {}
EffectReconciliation::Staged(effect)
| EffectReconciliation::Applied(effect) => {
self.record_effect(operation, kind, effect)?;
}
EffectReconciliation::OwnershipLost(effect) => {
self.record_effect(operation, kind, effect)?;
ownership_lost = true;
}
}
}
if self
.reconcile_agent_access_grants_for_rollback(operation)
.is_err()
{
ownership_lost = true;
}
}
OperationStepKind::MaterializeSources => {
match self
.control
.observe_control(&operation.operation_id, &operation.workspace_id)?
{
EffectReconciliation::Missing => {}
EffectReconciliation::Staged(effect)
| EffectReconciliation::Applied(effect) => {
self.record_effect(operation, kind, effect)?;
}
EffectReconciliation::OwnershipLost(effect) => {
self.record_effect(operation, kind, effect)?;
ownership_lost = true;
}
}
}
OperationStepKind::CompilePublication | OperationStepKind::ApplyAgentArtifacts => {
let effect_kind = if kind == OperationStepKind::CompilePublication {
OwnedEffectKind::Publication
} else {
OwnedEffectKind::AgentArtifact
};
let intents = operation
.plan
.external()
.iter()
.filter(|intent| intent.kind() == effect_kind)
.cloned()
.collect::<Vec<_>>();
for intent in intents {
match self.external.observe_external(operation, &intent)? {
EffectReconciliation::Missing => {}
EffectReconciliation::Staged(effect)
| EffectReconciliation::Applied(effect) => {
self.record_effect(operation, kind, effect)?;
}
EffectReconciliation::OwnershipLost(effect) => {
self.record_effect(operation, kind, effect)?;
ownership_lost = true;
}
}
}
}
OperationStepKind::Activate => {
for mutation in operation.plan.runtime().to_vec() {
match self
.runtime
.observe_runtime(&operation.operation_id, &mutation)?
{
EffectReconciliation::Missing => {}
EffectReconciliation::Staged(effect)
| EffectReconciliation::Applied(effect) => {
self.record_effect(operation, kind, effect)?;
}
EffectReconciliation::OwnershipLost(effect) => {
self.record_effect(operation, kind, effect)?;
ownership_lost = true;
}
}
}
}
}
if ownership_lost {
Err(TransactionError::EffectOwnershipLost)
} else {
Ok(())
}
}
fn compensate_step(
&self,
operation: &OperationV1,
kind: OperationStepKind,
) -> Result<(), TransactionError> {
let mut uncertain = false;
for effect in operation.step(kind).effects.iter().rev() {
if self
.compensate_effect(operation, effect)
.and_then(require_compensated)
.is_err()
{
uncertain = true;
}
}
if uncertain {
Err(TransactionError::EffectOwnershipLost)
} else {
Ok(())
}
}
fn compensate_effect(
&self,
operation: &OperationV1,
effect: &OwnedEffectV1,
) -> Result<CompensationOutcome, TransactionError> {
Ok(match effect.kind {
OwnedEffectKind::Control => self.control.compensate_control(effect)?,
OwnedEffectKind::Secret if hiroute_domain::is_agent_access_grant_effect(effect) => {
self.secrets.compensate_agent_access_grant(effect)?
}
OwnedEffectKind::Secret => self.secrets.compensate_secret(effect)?,
OwnedEffectKind::RuntimeState => self.runtime.compensate_runtime(effect)?,
OwnedEffectKind::Publication | OwnedEffectKind::AgentArtifact => {
self.external.compensate_external(operation, effect)?
}
// The login item runs in the Desktop host under the native confirmation; the host
// unregisters its own creation when the apply fails. Daemon-side rollback must
// not touch the host's system registration, so compensation is deliberately empty.
OwnedEffectKind::LoginItem => CompensationOutcome::AlreadyCompensated,
})
}
}
fn require_compensated(outcome: CompensationOutcome) -> Result<(), TransactionError> {
match outcome {
CompensationOutcome::Compensated | CompensationOutcome::AlreadyCompensated => Ok(()),
CompensationOutcome::OwnershipLost => Err(TransactionError::EffectOwnershipLost),
}
}
fn settings_service_receipt(
operation: &OperationV1,
) -> Option<hiroute_domain::SettingsServiceCompletionV1> {
operation
.step(OperationStepKind::Activate)
.terminal_result
.as_deref()
.and_then(hiroute_domain::SettingsServiceCompletionV1::parse)
}
/// Read readiness for a parked client-file tail. This does not authorize a new writer
/// or a file retry: the current publication must still match the sealed service proof.
pub fn settings_service_completion_is_current(
operation: &OperationV1,
publication_revision: u64,
publication_digest: &CanonicalDigest,
) -> bool {
operation.state == OperationState::Activating
&& operation.plan.spec().command_id == "agents.settings.apply"
&& operation
.plan
.external()
.iter()
.any(hiroute_domain::is_settings_managed_configuration)
&& operation.steps.iter().all(|step| {
step.kind == OperationStepKind::Activate
|| step.status == OperationStepStatus::Applied
})
&& settings_service_receipt(operation).is_some_and(|receipt| {
receipt.publication_revision == publication_revision
&& receipt.publication_digest == *publication_digest
&& matches!(
settings_service_completion_digest(operation, publication_revision, publication_digest),
Ok(expected) if expected == receipt.completed_effects_digest
)
})
}
fn settings_service_completion_digest(
operation: &OperationV1,
publication_revision: u64,
publication_digest: &CanonicalDigest,
) -> Result<CanonicalDigest, TransactionError> {
CanonicalDigest::of(&(
"hiroute.settings-service-proof/v2",
operation.operation_id.as_str(),
&operation.accepted_digest,
publication_revision,
publication_digest,
operation
.stable_input_digest()
.map_err(|_| TransactionError::InvalidArguments)?,
))
.map_err(|_| TransactionError::InvalidArguments)
}
fn require_applied(reconciliation: EffectReconciliation) -> Result<(), TransactionError> {
match reconciliation {
EffectReconciliation::Applied(_) => Ok(()),
EffectReconciliation::Missing | EffectReconciliation::Staged(_) => {
Err(TransactionError::EffectMissing)
}
EffectReconciliation::OwnershipLost(_) => Err(TransactionError::EffectOwnershipLost),
}
}
fn require_missing(reconciliation: EffectReconciliation) -> Result<(), TransactionError> {
match reconciliation {
EffectReconciliation::Missing => Ok(()),
EffectReconciliation::Staged(_)
| EffectReconciliation::Applied(_)
| EffectReconciliation::OwnershipLost(_) => Err(TransactionError::EffectOwnershipLost),
}
}
fn apply_request_digest(request: &ApplyRequestV1) -> Result<CanonicalDigest, TransactionError> {
#[derive(Serialize)]
struct DigestInput<'a> {
schema_version: hiroute_domain::SchemaVersion,
spec: &'a hiroute_domain::ChangeSpecV1,
accept_digest: &'a CanonicalDigest,
expected_revisions: &'a hiroute_domain::RevisionSetV1,
apply_capability: &'a Option<String>,
}
Ok(CanonicalDigest::of(&DigestInput {
schema_version: request.schema_version,
spec: &request.spec,
accept_digest: &request.accept_digest,
expected_revisions: &request.expected_revisions,
apply_capability: &request.apply_capability,
})?)
}
#[derive(Debug, Error)]
pub enum TransactionError {
#[error("typed plan content preparation failed: {0:?}")]
PlanContent(hiroute_application_api::ErrorCode),
#[error("invalid transaction arguments")]
InvalidArguments,
#[error("cash budget behavior is not enabled in P0")]
FeatureNotEnabled,
#[error("authenticated principal lacks this capability")]
CapabilityDenied,
#[error("expected revisions changed: {0:?}")]
RevisionConflict(RevisionMismatch),
#[error("the reproduced change no longer matches the accepted digest")]
ChangePreviewStale,
#[error("the idempotency key is already bound to a different request")]
IdempotencyKeyReused,
#[error("the durable Operation was not found")]
OperationNotFound,
#[error("protected Secret input is unavailable")]
ProtectedInputUnavailable,
#[error("an effect is no longer owned by this Operation")]
EffectOwnershipLost,
#[error("an exact Operation effect is missing or remains provisional")]
EffectMissing,
#[error("durable writer recovery must complete before accepting writes")]
RecoveryRequired,
#[error(transparent)]
Preparation(#[from] ChangePreparationError),
#[error(transparent)]
DomainOperation(#[from] hiroute_domain::OperationValidationError),
#[error(transparent)]
CanonicalDigest(#[from] hiroute_domain::CanonicalDigestError),
#[error(transparent)]
Port(#[from] PortError),
}
impl TransactionError {
pub fn model_budget_conflict(&self) -> Option<&hiroute_domain::AgentModelBudgetConflictV1> {
match self {
Self::Port(error) | Self::Preparation(ChangePreparationError::Port(error))
if error.code == hiroute_domain::PortErrorCode::Conflict =>
{
error
.model_budget_conflict
.as_deref()
.filter(|value| value.is_valid())
}
_ => None,
}
}
pub(crate) fn envelope(
&self,
request_id: String,
include_model_budget_conflict: bool,
) -> hiroute_application_api::MachineEnvelopeV2<serde_json::Value> {
let mut error = hiroute_application_api::ErrorV1::new(self.error_code());
if include_model_budget_conflict && let Some(conflict) = self.model_budget_conflict() {
error.details_schema = hiroute_domain::AGENT_MODEL_BUDGET_CONFLICT_SCHEMA_V1.into();
// Released readers deserialize data as the command's success DTO. Keep failures
// data-free; ErrorV1 supports additive metadata without changing that DTO.
error.model_budget_conflict = Some(Box::new(conflict.clone()));
}
hiroute_application_api::MachineEnvelopeV2::failed(error, Some(request_id))
}
pub fn error_code(&self) -> ErrorCode {
if let Some(conflict) = self.model_budget_conflict() {
return if conflict.safe_code() == "QODER_MODEL_BUDGET_CONFLICT" {
ErrorCode::QoderModelBudgetConflict
} else {
// Preserve the released closed ErrorCode enum for strict older callers.
ErrorCode::RevisionConflict
};
}
match self {
Self::Port(error) | Self::Preparation(ChangePreparationError::Port(error))
if error.code == hiroute_domain::PortErrorCode::Conflict
&& error.context == "qoder.model.budget.shrink" =>
{
ErrorCode::QoderModelBudgetConflict
}
Self::PlanContent(code) => *code,
Self::FeatureNotEnabled
| Self::Preparation(ChangePreparationError::FeatureNotEnabled) => {
ErrorCode::FeatureNotEnabled
}
Self::CapabilityDenied => ErrorCode::CapabilityDenied,
Self::RevisionConflict(_)
| Self::Preparation(ChangePreparationError::RuntimeGenerationChanged)
| Self::Preparation(ChangePreparationError::SecretGenerationChanged) => {
ErrorCode::RevisionConflict
}
Self::ChangePreviewStale
| Self::Preparation(ChangePreparationError::SecretFingerprintMismatch)
| Self::Preparation(ChangePreparationError::ExternalEffectChanged) => {
ErrorCode::ChangePreviewStale
}
Self::IdempotencyKeyReused => ErrorCode::IdempotencyKeyReused,
Self::OperationNotFound => ErrorCode::ResourceNotFound,
Self::ProtectedInputUnavailable => ErrorCode::ActionRequired,
Self::EffectOwnershipLost | Self::EffectMissing => ErrorCode::OperationNeedsAttention,
Self::RecoveryRequired => ErrorCode::DaemonUnavailable,
Self::Preparation(ChangePreparationError::Port(error)) => {
if error.code == hiroute_domain::PortErrorCode::NotFound {
ErrorCode::ActionRequired
} else {
ErrorCode::DaemonUnavailable
}
}
Self::Port(_) => ErrorCode::DaemonUnavailable,
_ => ErrorCode::InvalidArguments,
}
}
fn safe_code(&self) -> &'static str {
if let Some(conflict) = self.model_budget_conflict() {
return conflict.safe_code();
}
match self {
Self::Port(error) | Self::Preparation(ChangePreparationError::Port(error))
if error.code == hiroute_domain::PortErrorCode::Conflict
&& error.context == "qoder.model.budget.shrink" =>
{
"QODER_MODEL_BUDGET_CONFLICT"
}
Self::ChangePreviewStale
| Self::Preparation(ChangePreparationError::SecretFingerprintMismatch)
| Self::Preparation(ChangePreparationError::ExternalEffectChanged) => {
"CHANGE_PREVIEW_STALE"
}
Self::EffectOwnershipLost | Self::EffectMissing => "EFFECT_OWNERSHIP_LOST",
Self::RecoveryRequired => "RECOVERY_REQUIRED",
Self::ProtectedInputUnavailable => "PROTECTED_INPUT_UNAVAILABLE",
Self::Port(error)
if matches!(
error.context,
"subscription.source.changed" | "cpa-subscription-source-changed"
) =>
{
"SUBSCRIPTION_SOURCE_CHANGED"
}
Self::Port(error) if error.context == "subscription.native.store-unsupported" => {
"SUBSCRIPTION_NATIVE_STORE_UNSUPPORTED"
}
Self::Port(error) if error.context == "subscription.native.login-unsupported" => {
"SUBSCRIPTION_NATIVE_LOGIN_UNSUPPORTED"
}
Self::Port(error) if error.context == "subscription.native.account-missing" => {
"SUBSCRIPTION_NATIVE_ACCOUNT_MISSING"
}
Self::Port(error) if error.context == "subscription.native.login-missing" => {
"SUBSCRIPTION_NATIVE_LOGIN_MISSING"
}
Self::Port(error) if error.context == "subscription.native.read-failed" => {
"SUBSCRIPTION_NATIVE_READ_FAILED"
}
Self::Port(error) if error.context == "subscription.native.login-invalid" => {
"SUBSCRIPTION_NATIVE_LOGIN_INVALID"
}
Self::Port(error) if error.context == "subscription.native.client-unavailable" => {
"SUBSCRIPTION_NATIVE_CLIENT_UNAVAILABLE"
}
Self::Port(error) if error.context == "subscription.managed.login-required" => {
"SUBSCRIPTION_MANAGED_LOGIN_REQUIRED"
}
Self::Port(error) if error.context == "subscription.authentication" => {
"SUBSCRIPTION_NEEDS_AUTH"
}
Self::Port(error) if error.context == "cpa-subscription-needs-auth" => {
"SUBSCRIPTION_NEEDS_AUTH"
}
Self::Port(error) if error.context == "cpa-subscription-runtime" => {
"SUBSCRIPTION_RUNTIME_UNAVAILABLE"
}
Self::Port(error) if error.context.starts_with("subscription.") => {
"SUBSCRIPTION_RUNTIME_UNAVAILABLE"
}
Self::Port(_) => "ADAPTER_FAILURE",
_ => "APPLY_STEP_FAILED",
}
}
}
#[cfg(test)]
mod tests;