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 hiroute_diagnostics::publication::{PublicationStage, measure};
use std::cell::RefCell;
use std::collections::BTreeMap;
use std::fs;
#[cfg(not(windows))]
use std::fs::OpenOptions;
use std::io::Read;
#[cfg(not(windows))]
use std::io::Write;
use std::path::{Component, Path, PathBuf};
use aes_gcm::aead::{Aead, Payload};
use aes_gcm::{Aes256Gcm, KeyInit, Nonce};
use hiroute_domain::{
BeginOperationOutcome, CanonicalDigest, CompensationOutcome, ControlRepositoryPort,
EffectReconciliation, ExternalEffectIntentV1, ExternalEffectPort, IdempotencyScopeV1,
OperationId, OperationState, OperationStepV1, OperationV1, OwnedEffectKind, OwnedEffectV1,
PortError, PortErrorCode, PortResult, ProtectedApplyCapability, RevisionMismatch,
RevisionSetV1, VerifiedApplyAuthorizationV1, WorkerDependencySelectionChangeV1, WorkspaceId,
};
#[cfg(test)]
use hiroute_domain::{ChangeSpecV1, TransactionPlanV1};
use rusqlite::{Connection, OptionalExtension, Transaction, TransactionBehavior, params};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use zeroize::Zeroizing;
use crate::migrations::{DatabaseKind, open_database, open_database_from_set};
use crate::{DaemonStorageAuthority, LocalStorageError};
#[cfg(test)]
mod agent_transaction_tests;
#[cfg(test)]
mod surface_check_tests;
#[cfg(test)]
mod test_native_permissions;
#[cfg(test)]
mod transaction_v2_tests;
#[cfg(all(test, windows))]
mod windows_artifacts_tests;
#[cfg(all(test, windows))]
mod windows_native_reader_tests;
mod agent_check;
mod agent_read;
mod native_targets;
pub use agent_read::SucceededAgentOperationV1;
#[path = "../agents/collaboration_store.rs"]
mod collaboration_store;
mod compute;
mod decision_services;
mod journal;
#[path = "../agents/native_artifacts.rs"]
mod native_artifacts;
#[path = "../agents/native_directories.rs"]
mod native_directories;
mod native_permissions;
#[path = "../agents/native_reference.rs"]
mod native_reference;
use native_permissions::{
current_artifact_aad, current_artifact_schema, desired_windows_permissions,
};
#[cfg(windows)]
use native_permissions::{read_private_restore_file, windows_artifact_fingerprint};
#[path = "../agents/native_restoration_ack.rs"]
mod native_restoration_ack;
mod operation_status;
mod plans;
mod prices;
mod worker_dependencies;
use native_directories::CreatedNativeDirectory;
#[cfg(all(test, unix))]
#[path = "../agents/native_file_tests.rs"]
mod native_file_tests;
#[path = "../agents/plan_references.rs"]
mod plan_references;
mod publication;
#[path = "../agents/skill_store.rs"]
mod skill_store;
pub use compute::{
ComputeSubscriptionValidationRecordV1, ComputeSubscriptionValidationStateV1,
InventorySnapshotV1,
};
pub struct ControlStore {
diagnostics: RefCell<hiroute_diagnostics::DiagnosticsPort>,
pub(crate) connection: RefCell<Connection>,
pub(crate) startup_lock: Option<std::sync::Arc<std::fs::File>>,
}
/// One exact grant received over the daemon launcher's protected inherited channel. The raw
/// capability is zeroized by the domain wrapper and this type is intentionally neither Clone nor
/// serializable, so it cannot become an ambient socket/API credential.
pub struct ApplyCapabilityRegistrationV1 {
capability: ProtectedApplyCapability,
authorization: VerifiedApplyAuthorizationV1,
revisions: RevisionSetV1,
}
impl ApplyCapabilityRegistrationV1 {
#[allow(clippy::too_many_arguments)]
pub fn from_protected_launcher(
capability: String,
principal: impl Into<String>,
workspace: WorkspaceId,
operation_kind: impl Into<String>,
accepted_digest: CanonicalDigest,
revisions: RevisionSetV1,
expires_at_unix: i64,
) -> Result<Self, LocalStorageError> {
let principal = principal.into();
if principal == "daemon-subscription-maintenance" {
return Err(LocalStorageError::InvalidData);
}
Self::build(
capability,
principal,
workspace,
operation_kind.into(),
accepted_digest,
revisions,
expires_at_unix,
)
}
pub fn from_subscription_maintenance(
capability: String,
workspace: WorkspaceId,
operation_kind: impl Into<String>,
accepted_digest: CanonicalDigest,
revisions: RevisionSetV1,
expires_at_unix: i64,
) -> Result<Self, LocalStorageError> {
let operation_kind = operation_kind.into();
if !matches!(
operation_kind.as_str(),
"ApplySubscriptionCheck" | "ApplyComputeSave"
) {
return Err(LocalStorageError::InvalidData);
}
Self::build(
capability,
"daemon-subscription-maintenance".to_owned(),
workspace,
operation_kind,
accepted_digest,
revisions,
expires_at_unix,
)
}
#[allow(clippy::too_many_arguments)]
fn build(
capability: String,
principal: String,
workspace: WorkspaceId,
operation_kind: String,
accepted_digest: CanonicalDigest,
revisions: RevisionSetV1,
expires_at_unix: i64,
) -> Result<Self, LocalStorageError> {
let capability = ProtectedApplyCapability::new(capability)
.map_err(|_| LocalStorageError::InvalidData)?;
if capability.expose().len() < 32 || expires_at_unix <= 0 {
return Err(LocalStorageError::InvalidData);
}
let revisions_digest =
CanonicalDigest::of(&revisions).map_err(|_| LocalStorageError::InvalidData)?;
let authorization = VerifiedApplyAuthorizationV1::from_capability_verifier(
CanonicalDigest::of_bytes(capability.expose()),
principal,
workspace,
operation_kind,
accepted_digest,
revisions_digest,
"apply:one-shot",
expires_at_unix,
)
.map_err(|_| LocalStorageError::InvalidData)?;
Ok(Self {
capability,
authorization,
revisions,
})
}
}
/// Borrowed registrar available only from the coordinated daemon storage set. It can persist a
/// launcher-verified grant, but cannot mint, clone, serialize, or return a capability.
pub struct ApplyCapabilityRegistrar<'a> {
control: &'a ControlStore,
}
impl ApplyCapabilityRegistrar<'_> {
pub(crate) fn new(control: &ControlStore) -> ApplyCapabilityRegistrar<'_> {
ApplyCapabilityRegistrar { control }
}
pub fn register(self, registration: ApplyCapabilityRegistrationV1) -> PortResult<()> {
let now: i64 = self
.control
.connection
.borrow()
.query_row("SELECT unixepoch()", [], |row| row.get(0))
.map_err(|_| port(PortErrorCode::Unavailable, "control.capability.clock"))?;
if registration.authorization.expires_at_unix() <= now
|| registration.authorization.expires_at_unix() > now.saturating_add(300)
{
return Err(port(
PortErrorCode::PermissionDenied,
"control.capability.expiry",
));
}
self.control.insert_apply_capability(
®istration.capability,
registration.authorization.principal(),
registration.authorization.workspace_id(),
registration.authorization.operation_kind(),
registration.authorization.accepted_digest(),
®istration.revisions,
registration.authorization.expires_at_unix(),
)
}
}
impl ControlStore {
pub(crate) fn native_credential_unavailable(
&self,
stage: hiroute_diagnostics::event::NativeCredentialLookupStage,
) {
use hiroute_diagnostics::event::{CredentialLease, LeaseResultCode};
self.diagnostics
.borrow()
.emit(hiroute_diagnostics::DiagnosticEvent::CredentialLease(
CredentialLease {
result: LeaseResultCode::Unavailable,
stage: Some(stage),
},
));
}
pub fn set_diagnostics(&self, port: hiroute_diagnostics::DiagnosticsPort) {
*self.diagnostics.borrow_mut() = port;
}
pub(crate) fn open(
_authority: &DaemonStorageAuthority,
path: impl AsRef<Path>,
migration_backup_root: impl AsRef<Path>,
) -> Result<Self, LocalStorageError> {
Ok(Self {
diagnostics: RefCell::new(Default::default()),
startup_lock: None,
connection: RefCell::new(open_database(
_authority,
path,
DatabaseKind::Control,
migration_backup_root,
)?),
})
}
pub(crate) fn open_from_migration_set(
authority: &DaemonStorageAuthority,
path: &Path,
migration_backup_root: &Path,
expected_store_uuid: &str,
target_schema_version: u32,
) -> Result<Self, LocalStorageError> {
Ok(Self {
diagnostics: RefCell::new(Default::default()),
startup_lock: None,
connection: RefCell::new(open_database_from_set(
authority,
path,
DatabaseKind::Control,
migration_backup_root,
Some(expected_store_uuid),
None,
target_schema_version,
)?),
})
}
#[cfg(test)]
pub(crate) fn with_connection<T>(&self, function: impl FnOnce(&Connection) -> T) -> T {
function(&self.connection.borrow())
}
/// Read the retained writer owner even when it has reached NeedsAttention.
pub fn writer_claim_operation(&self) -> PortResult<Option<OperationV1>> {
load_operation_where(
&self.diagnostics.borrow(),
&self.connection.borrow(),
"operation_id = (SELECT operation_id FROM writer_claim WHERE singleton = 1)",
[],
)
}
pub fn desired_state(&self, workspace: &WorkspaceId) -> PortResult<Option<Value>> {
let connection = self.connection.borrow();
let encoded: Option<String> = connection
.query_row(
"SELECT desired_json FROM workspace_state WHERE workspace_id = ?1",
params![workspace.as_str()],
|row| row.get(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.desired.read"))?;
encoded
.map(|value| {
let mut envelope: Value = serde_json::from_str(&value)
.map_err(|_| port(PortErrorCode::Corrupt, "control.desired.decode"))?;
if envelope.get("schema").and_then(Value::as_str)
!= Some("hiroute.control-desired/v1")
{
return Err(port(PortErrorCode::Corrupt, "control.desired.schema"));
}
envelope
.as_object_mut()
.and_then(|object| object.remove("value"))
.ok_or_else(|| port(PortErrorCode::Corrupt, "control.desired.value"))
})
.transpose()
}
#[cfg(test)]
pub(crate) fn set_dependency_revision(
&self,
workspace: &WorkspaceId,
key: &str,
revision: u64,
) -> PortResult<()> {
self.connection
.borrow()
.execute(
"INSERT INTO dependency_revisions(workspace_id, dependency_key, revision)
VALUES (?1, ?2, ?3)
ON CONFLICT(workspace_id, dependency_key)
DO UPDATE SET revision = excluded.revision",
params![workspace.as_str(), key, revision],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.dependencies.write"))?;
Ok(())
}
pub fn operation_step_rows(&self, operation_id: &OperationId) -> PortResult<usize> {
self.connection
.borrow()
.query_row(
"SELECT count(*) FROM operation_steps WHERE operation_id = ?1",
params![operation_id.as_str()],
|row| row.get(0),
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.journal.count"))
}
/// Reads completed operations as newest-first immutable projections. Callers still validate
/// the sealed command-specific plan; this does not create a mutable AgentConnection state
/// store.
pub fn succeeded_operations_for_kind(
&self,
workspace: &WorkspaceId,
operation_kind: &str,
) -> PortResult<Vec<OperationV1>> {
self.succeeded_operations_for_kinds(workspace, &[operation_kind])
}
pub fn succeeded_operations_for_kinds(
&self,
workspace: &WorkspaceId,
operation_kinds: &[&str],
) -> PortResult<Vec<OperationV1>> {
if operation_kinds.is_empty() || operation_kinds.len() > 32 {
return Err(port(
PortErrorCode::InvalidData,
"control.operation.completed.kinds",
));
}
let placeholders = (0..operation_kinds.len())
.map(|_| "?")
.collect::<Vec<_>>()
.join(",");
let sql = format!(
"SELECT operation_json FROM operations WHERE workspace_id = ? AND operation_kind IN ({placeholders}) AND state = 'succeeded' ORDER BY rowid DESC"
);
let connection = self.connection.borrow();
let mut statement = connection.prepare(&sql).map_err(|_| {
port(
PortErrorCode::Unavailable,
"control.operation.completed.prepare",
)
})?;
let rows = statement
.query_map(
rusqlite::params_from_iter(
std::iter::once(workspace.as_str()).chain(operation_kinds.iter().copied()),
),
|row| row.get::<_, String>(0),
)
.map_err(|_| {
port(
PortErrorCode::Unavailable,
"control.operation.completed.query",
)
})?;
let mut operations = Vec::new();
for row in rows {
let encoded =
row.map_err(|_| port(PortErrorCode::Corrupt, "control.operation.completed.row"))?;
operations.push(decode_operation(&self.diagnostics.borrow(), &encoded)?);
}
Ok(operations)
}
#[cfg(test)]
pub(crate) fn grant_apply_capability(
&self,
capability: &str,
operation: &OperationV1,
expires_at: i64,
) -> PortResult<()> {
let capability = ProtectedApplyCapability::new(capability.to_owned())
.map_err(|_| port(PortErrorCode::InvalidData, "control.capability.value"))?;
self.insert_apply_capability(
&capability,
&operation.idempotency.principal,
&operation.workspace_id,
&operation.idempotency.operation_kind,
&operation.accepted_digest,
&operation.expected_revisions,
expires_at,
)
}
#[allow(clippy::too_many_arguments)]
fn insert_apply_capability(
&self,
capability: &ProtectedApplyCapability,
principal: &str,
workspace: &WorkspaceId,
operation_kind: &str,
accepted_digest: &CanonicalDigest,
revisions: &RevisionSetV1,
expires_at: i64,
) -> PortResult<()> {
let capability_digest = CanonicalDigest::of_bytes(capability.expose());
let revisions_digest = CanonicalDigest::of(revisions)
.map_err(|_| port(PortErrorCode::InvalidData, "control.capability.revisions"))?;
self.connection
.borrow()
.execute(
"INSERT INTO apply_capabilities(
capability_digest, principal, workspace_id, operation_kind,
accepted_digest, expected_revisions_digest, capability_scope,
expires_at, revoked, consumed_operation_id
) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'apply:one-shot', ?7, 0, NULL)",
params![
capability_digest.as_str(),
principal,
workspace.as_str(),
operation_kind,
accepted_digest.as_str(),
revisions_digest.as_str(),
expires_at,
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.capability.grant"))?;
Ok(())
}
}
impl ControlStore {
fn begin_operation_admitted(
&self,
operation: &OperationV1,
authorization: Option<&VerifiedApplyAuthorizationV1>,
) -> PortResult<BeginOperationOutcome> {
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.operation.begin"))?;
if let Some(existing) = load_operation_where(
&self.diagnostics.borrow(),
&transaction,
"workspace_id = ?1 AND principal = ?2 AND operation_kind = ?3 AND idempotency_key = ?4",
params![
operation.workspace_id.as_str(),
&operation.idempotency.principal,
&operation.idempotency.operation_kind,
&operation.idempotency.key
],
)? {
return if existing.accepted_digest == operation.accepted_digest {
Ok(BeginOperationOutcome::ExistingSame(Box::new(existing)))
} else {
Ok(BeginOperationOutcome::ExistingDifferent)
};
}
// Admission and the final target/dependency revision check share one SQLite transaction.
if let Some(change) = operation.plan.worker_dependency_selection() {
let current = Self::worker_dependency_selection_revision_in(
&transaction,
&operation.workspace_id,
change.after_selection.harness,
)?;
if current != operation.expected_revisions.target || current != change.before_revision {
return Ok(BeginOperationOutcome::RevisionChanged(
RevisionMismatch::Target,
));
}
if !operation.expected_revisions.dependencies.is_empty() {
return Ok(BeginOperationOutcome::RevisionChanged(
RevisionMismatch::Dependencies,
));
}
} else {
let current = read_revisions(&transaction, &operation.workspace_id)?;
if current.target != operation.expected_revisions.target {
return Ok(BeginOperationOutcome::RevisionChanged(
RevisionMismatch::Target,
));
}
if current.dependencies != operation.expected_revisions.dependencies {
return Ok(BeginOperationOutcome::RevisionChanged(
RevisionMismatch::Dependencies,
));
}
}
if let Some(authorization) = authorization
&& (!authorization.matches_operation(operation)
|| authorization.scope() != "apply:one-shot")
{
return Err(port(
PortErrorCode::PermissionDenied,
"control.capability.binding",
));
}
let claimed = transaction
.execute(
"INSERT INTO writer_claim(singleton, operation_id, admitted_at)
VALUES (1, ?1, unixepoch())",
params![operation.operation_id.as_str()],
)
.map_err(|_| port(PortErrorCode::Conflict, "control.writer.claim"))?;
if claimed != 1 {
return Err(port(PortErrorCode::Conflict, "control.writer.claim"));
}
if let Some(authorization) = authorization {
let consumed = transaction
.execute(
"UPDATE apply_capabilities SET consumed_operation_id = ?2
WHERE capability_digest = ?1
AND principal = ?3 AND workspace_id = ?4 AND operation_kind = ?5
AND accepted_digest = ?6 AND expected_revisions_digest = ?7
AND capability_scope = 'apply:one-shot'
AND expires_at > unixepoch() AND revoked = 0
AND consumed_operation_id IS NULL",
params![
authorization.capability_digest().as_str(),
operation.operation_id.as_str(),
authorization.principal(),
authorization.workspace_id().as_str(),
authorization.operation_kind(),
authorization.accepted_digest().as_str(),
authorization.expected_revisions_digest().as_str(),
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.capability.consume"))?;
if consumed != 1 {
return Err(port(
PortErrorCode::PermissionDenied,
"control.capability.consumed",
));
}
}
let encoded = serde_json::to_string(operation)
.map_err(|_| port(PortErrorCode::InvalidData, "control.operation.encode"))?;
transaction
.execute(
"INSERT INTO operations(
operation_id, workspace_id, principal, operation_kind, idempotency_key,
request_digest, accepted_change_digest, state, generation, operation_json,
created_at, updated_at
) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 0, ?9, unixepoch(), unixepoch())",
params![
operation.operation_id.as_str(),
operation.workspace_id.as_str(),
&operation.idempotency.principal,
&operation.idempotency.operation_kind,
&operation.idempotency.key,
operation.request_digest.as_str(),
operation.accepted_digest.as_str(),
operation.state.as_str(),
encoded,
],
)
.map_err(|_| port(PortErrorCode::Conflict, "control.operation.insert"))?;
store_steps(&transaction, operation)?;
compute::begin_save_handoff_in(&transaction, operation)?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.operation.commit"))?;
Ok(BeginOperationOutcome::Created)
}
}
impl ControlRepositoryPort for ControlStore {
fn current_revisions(&self, workspace: &WorkspaceId) -> PortResult<RevisionSetV1> {
read_revisions(&self.connection.borrow(), workspace)
}
fn operation_for_idempotency(
&self,
workspace: &WorkspaceId,
scope: &IdempotencyScopeV1,
) -> PortResult<Option<OperationV1>> {
let connection = self.connection.borrow();
load_operation_where(
&self.diagnostics.borrow(),
&connection,
"workspace_id = ?1 AND principal = ?2 AND operation_kind = ?3 AND idempotency_key = ?4",
params![
workspace.as_str(),
&scope.principal,
&scope.operation_kind,
&scope.key
],
)
}
fn verify_apply_authorization(
&self,
capability: &ProtectedApplyCapability,
workspace: &WorkspaceId,
principal: &str,
operation_kind: &str,
accepted_digest: &CanonicalDigest,
expected_revisions: &RevisionSetV1,
) -> PortResult<VerifiedApplyAuthorizationV1> {
let digest = CanonicalDigest::of_bytes(capability.expose());
let expected_revisions_digest = CanonicalDigest::of(expected_revisions)
.map_err(|_| port(PortErrorCode::InvalidData, "control.capability.revisions"))?;
let row = self
.connection
.borrow()
.query_row(
"SELECT principal, workspace_id, operation_kind, accepted_digest,
expected_revisions_digest, capability_scope, expires_at,
revoked, consumed_operation_id
FROM apply_capabilities WHERE capability_digest = ?1",
params![digest.as_str()],
|row| {
Ok((
row.get::<_, String>(0)?,
row.get::<_, String>(1)?,
row.get::<_, String>(2)?,
row.get::<_, String>(3)?,
row.get::<_, String>(4)?,
row.get::<_, String>(5)?,
row.get::<_, i64>(6)?,
row.get::<_, bool>(7)?,
row.get::<_, Option<String>>(8)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.capability.read"))?
.ok_or_else(|| {
port(
PortErrorCode::PermissionDenied,
"control.capability.missing",
)
})?;
let now: i64 = self
.connection
.borrow()
.query_row("SELECT unixepoch()", [], |row| row.get(0))
.map_err(|_| port(PortErrorCode::Unavailable, "control.capability.clock"))?;
if row.0 != principal
|| row.1 != workspace.as_str()
|| row.2 != operation_kind
|| row.3 != accepted_digest.as_str()
|| row.4 != expected_revisions_digest.as_str()
|| row.5 != "apply:one-shot"
|| row.6 <= now
|| row.7
|| row.8.is_some()
{
return Err(port(
PortErrorCode::PermissionDenied,
"control.capability.denied",
));
}
VerifiedApplyAuthorizationV1::from_capability_verifier(
digest,
row.0,
workspace.clone(),
row.2,
accepted_digest.clone(),
expected_revisions_digest,
row.5,
row.6,
)
.map_err(|_| port(PortErrorCode::Corrupt, "control.capability.record"))
}
fn begin_operation(
&self,
operation: &OperationV1,
authorization: &VerifiedApplyAuthorizationV1,
) -> PortResult<BeginOperationOutcome> {
self.begin_operation_admitted(operation, Some(authorization))
}
fn begin_local_operation(&self, operation: &OperationV1) -> PortResult<BeginOperationOutcome> {
if operation.idempotency.principal != "interactive-user" {
return Err(port(
PortErrorCode::PermissionDenied,
"control.local_operation.denied",
));
}
self.begin_operation_admitted(operation, None)
}
fn operation_is_current(&self, operation: &OperationV1) -> PortResult<bool> {
measure(
&self.diagnostics.borrow(),
PublicationStage::OperationCurrent,
Some(operation.operation_id.as_str()),
None,
|| journal::is_current(&self.connection.borrow(), operation),
)
}
fn load_operation(&self, operation_id: &OperationId) -> PortResult<Option<OperationV1>> {
load_operation_where(
&self.diagnostics.borrow(),
&self.connection.borrow(),
"operation_id = ?1",
params![operation_id.as_str()],
)
}
fn recoverable_operations(&self) -> PortResult<Vec<OperationV1>> {
let connection = self.connection.borrow();
let mut statement = connection
.prepare(
"SELECT operation_json FROM operations
WHERE state NOT IN ('succeeded', 'rolled_back', 'needs_attention')
OR (state = 'needs_attention' AND operation_id =
(SELECT operation_id FROM writer_claim WHERE singleton = 1))
ORDER BY created_at, operation_id",
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.recovery.prepare"))?;
let rows = statement
.query_map([], |row| row.get::<_, String>(0))
.map_err(|_| port(PortErrorCode::Unavailable, "control.recovery.query"))?;
let mut operations = Vec::new();
for row in rows {
let encoded = row.map_err(|_| port(PortErrorCode::Corrupt, "control.recovery.row"))?;
operations.push(decode_operation(&self.diagnostics.borrow(), &encoded)?);
}
Ok(operations)
}
fn writer_recovery_required(&self) -> PortResult<bool> {
self.connection
.borrow()
.query_row("SELECT EXISTS(SELECT 1 FROM writer_claim)", [], |row| {
row.get(0)
})
.map_err(|_| port(PortErrorCode::Unavailable, "control.writer.recovery"))
}
fn save_operation(&self, operation: &mut OperationV1) -> PortResult<()> {
let id = operation.operation_id.to_string();
measure(
&self.diagnostics.borrow(),
PublicationStage::OperationSave,
Some(&id),
None,
|| {
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.journal.begin"))?;
let generation = journal::save(&transaction, operation)?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.journal.commit"))?;
operation.acknowledge_journal_commit(generation);
Ok(())
},
)
}
fn worker_dependency_selection_revision(
&self,
workspace: &WorkspaceId,
harness: hiroute_domain::delegation::WorkerHarnessV1,
) -> PortResult<u64> {
Self::worker_dependency_selection_revision_in(&self.connection.borrow(), workspace, harness)
}
fn apply_worker_dependency_selection(
&self,
operation_id: &OperationId,
workspace: &WorkspaceId,
change: &WorkerDependencySelectionChangeV1,
) -> PortResult<OwnedEffectV1> {
self.stage_worker_dependency_selection(operation_id, workspace, change)
}
fn apply_control(
&self,
operation_id: &OperationId,
workspace: &WorkspaceId,
expected_revision: u64,
desired: &Value,
) -> PortResult<OwnedEffectV1> {
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.begin"))?;
let existing_effect: bool = transaction
.query_row(
"SELECT EXISTS(SELECT 1 FROM control_effects WHERE operation_id = ?1)",
params![operation_id.as_str()],
|row| row.get(0),
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.lookup"))?;
if existing_effect {
drop(transaction);
drop(connection);
return match self.observe_control(operation_id, workspace)? {
EffectReconciliation::Staged(effect) | EffectReconciliation::Applied(effect) => {
Ok(effect)
}
EffectReconciliation::Missing => {
Err(port(PortErrorCode::Conflict, "control.effect.compensated"))
}
EffectReconciliation::OwnershipLost(_) => {
Err(port(PortErrorCode::Conflict, "control.effect.ownership"))
}
};
}
let before = transaction
.query_row(
"SELECT desired_json, target_revision, desired_digest, owner_operation_id
FROM workspace_state WHERE workspace_id = ?1",
params![workspace.as_str()],
|row| {
Ok((
row.get::<_, String>(0)?,
row.get::<_, u64>(1)?,
row.get::<_, String>(2)?,
row.get::<_, Option<String>>(3)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.before"))?;
let current_revision = read_control_head(&transaction, workspace)?;
if current_revision != expected_revision {
return Err(port(PortErrorCode::Conflict, "control.effect.revision"));
}
compute::management::stage_control(&transaction, workspace, operation_id, desired)?;
decision_services::stage(&transaction, workspace, desired)?;
let desired_json = serde_json::to_string(&json!({
"schema": "hiroute.control-desired/v1",
"value": desired,
}))
.map_err(|_| port(PortErrorCode::InvalidData, "control.effect.encode"))?;
let after_digest = CanonicalDigest::of(desired)
.map_err(|_| port(PortErrorCode::InvalidData, "control.effect.digest"))?;
let after_revision = expected_revision
.checked_add(1)
.ok_or_else(|| port(PortErrorCode::Conflict, "control.effect.revision_overflow"))?;
transaction
.execute(
"INSERT INTO control_effects(
operation_id, workspace_id, before_exists, before_json, before_revision,
before_digest, before_owner_operation_id, after_revision, after_digest,
compensated, staged_json, activated
) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, 0, ?10, 0)",
params![
operation_id.as_str(),
workspace.as_str(),
i64::from(before.is_some()),
before.as_ref().map(|value| value.0.as_str()),
current_revision,
before.as_ref().map(|value| value.2.as_str()),
before.as_ref().and_then(|value| value.3.as_deref()),
after_revision,
after_digest.as_str(),
desired_json,
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.journal"))?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.commit"))?;
Ok(control_effect(
operation_id,
workspace,
before.as_ref().and_then(|value| parse_digest(&value.2)),
after_digest,
after_revision,
))
}
fn observe_control(
&self,
operation_id: &OperationId,
workspace: &WorkspaceId,
) -> PortResult<EffectReconciliation> {
if let Some(selection) =
self.observe_worker_dependency_selection(operation_id, workspace)?
{
return Ok(selection);
}
let connection = self.connection.borrow();
let effect = connection
.query_row(
"SELECT before_digest, after_revision, after_digest, compensated,
staged_json, activated, compute_pool_id, compute_pool_after_json,
compute_source_id, compute_source_after_json
FROM control_effects WHERE operation_id = ?1 AND workspace_id = ?2",
params![operation_id.as_str(), workspace.as_str()],
|row| {
Ok((
row.get::<_, Option<String>>(0)?,
row.get::<_, u64>(1)?,
row.get::<_, String>(2)?,
row.get::<_, bool>(3)?,
row.get::<_, Option<String>>(4)?,
row.get::<_, bool>(5)?,
row.get::<_, Option<String>>(6)?,
row.get::<_, Option<String>>(7)?,
row.get::<_, Option<String>>(8)?,
row.get::<_, Option<String>>(9)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.observe"))?;
let Some((
before_digest,
after_revision,
after_digest,
compensated,
staged_json,
activated,
compute_pool_id,
compute_pool_after_json,
compute_source_id,
compute_source_after_json,
)) = effect
else {
return Ok(EffectReconciliation::Missing);
};
if compensated {
return Ok(EffectReconciliation::Missing);
}
let after = CanonicalDigest::parse(after_digest.clone())
.map_err(|_| port(PortErrorCode::Corrupt, "control.effect.digest"))?;
let owned = control_effect(
operation_id,
workspace,
before_digest.as_deref().and_then(parse_digest),
after,
after_revision,
);
if !activated {
let staged_json =
staged_json.ok_or_else(|| port(PortErrorCode::Corrupt, "control.effect.stage"))?;
let mut staged: Value = serde_json::from_str(&staged_json)
.map_err(|_| port(PortErrorCode::Corrupt, "control.effect.stage"))?;
let staged_value = staged
.as_object_mut()
.and_then(|object| object.remove("value"))
.ok_or_else(|| port(PortErrorCode::Corrupt, "control.effect.stage"))?;
let staged_digest = CanonicalDigest::of(&staged_value)
.map_err(|_| port(PortErrorCode::Corrupt, "control.effect.stage_digest"))?;
if staged_digest.as_str() != after_digest {
return Err(port(PortErrorCode::Corrupt, "control.effect.stage_digest"));
}
return Ok(EffectReconciliation::Staged(owned));
}
let current = connection
.query_row(
"SELECT target_revision, desired_digest, owner_operation_id
FROM workspace_state WHERE workspace_id = ?1",
params![workspace.as_str()],
|row| {
Ok((
row.get::<_, u64>(0)?,
row.get::<_, String>(1)?,
row.get::<_, Option<String>>(2)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.current"))?;
let workspace_owned = current.as_ref().is_some_and(|current| {
current.0 == after_revision
&& current.1 == after_digest
&& current.2.as_deref() == Some(operation_id.as_str())
});
let pool_owned = match (compute_pool_id, compute_pool_after_json) {
(None, None) => true,
(Some(pool_id), Some(after_json)) => connection
.query_row(
"SELECT pool_json FROM credential_pools WHERE pool_id=?1 AND active=1",
params![pool_id],
|row| row.get::<_, String>(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.pool"))?
.is_some_and(|current| current == after_json),
_ => return Err(port(PortErrorCode::Corrupt, "control.effect.pool_stage")),
};
let source_owned = match (compute_source_id, compute_source_after_json) {
(None, None) => true,
(Some(source_id), Some(after_json))
if compute::projection::is_projection_state(&after_json) =>
{
compute::projection::current_matches(&connection, &source_id, &after_json)?
}
(Some(source_id), Some(after_json)) => connection
.query_row(
"SELECT source_json FROM compute_sources WHERE source_id=?1",
params![source_id],
|row| row.get::<_, String>(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.effect.source"))?
.is_some_and(|current| current == after_json),
_ => return Err(port(PortErrorCode::Corrupt, "control.effect.source_stage")),
};
let management_owned = compute::management::current_matches(
&connection,
workspace,
staged_json.as_deref(),
operation_id,
)?;
if workspace_owned && pool_owned && source_owned && management_owned {
Ok(EffectReconciliation::Applied(owned))
} else {
Ok(EffectReconciliation::OwnershipLost(owned))
}
}
fn activate_control(&self, effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1> {
if let Some(selection) = self.activate_worker_dependency_selection(effect)? {
return Ok(selection);
}
if effect.kind != OwnedEffectKind::Control {
return Err(port(PortErrorCode::InvalidData, "control.activate.kind"));
}
let operation_id = effect
.compensation
.get("operation_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "control.activate.metadata"))?;
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.begin"))?;
let record = transaction
.query_row(
"SELECT workspace_id, before_revision, after_revision, after_digest,
staged_json, activated, compensated, compute_pool_id,
compute_pool_expected_revision, compute_pool_after_json,
compute_source_id, compute_source_expected_revision,
compute_source_before_json, compute_source_after_json
FROM control_effects WHERE operation_id = ?1",
params![operation_id],
|row| {
Ok((
row.get::<_, String>(0)?,
row.get::<_, u64>(1)?,
row.get::<_, u64>(2)?,
row.get::<_, String>(3)?,
row.get::<_, Option<String>>(4)?,
row.get::<_, bool>(5)?,
row.get::<_, bool>(6)?,
row.get::<_, Option<String>>(7)?,
row.get::<_, Option<u64>>(8)?,
row.get::<_, Option<String>>(9)?,
row.get::<_, Option<String>>(10)?,
row.get::<_, Option<u64>>(11)?,
row.get::<_, Option<String>>(12)?,
row.get::<_, Option<String>>(13)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.lookup"))?
.ok_or_else(|| port(PortErrorCode::NotFound, "control.activate.effect"))?;
if record.6 {
return Err(port(
PortErrorCode::Conflict,
"control.activate.compensated",
));
}
if record.5 {
return Ok(effect.clone());
}
let workspace = WorkspaceId::parse(record.0.clone())
.map_err(|_| port(PortErrorCode::Corrupt, "control.activate.workspace"))?;
if read_control_head(&transaction, &workspace)? != record.1 {
return Err(port(PortErrorCode::Conflict, "control.activate.revision"));
}
let staged = record
.4
.ok_or_else(|| port(PortErrorCode::Corrupt, "control.activate.stage"))?;
match (&record.7, record.8, &record.9) {
(None, None, None) => {}
(Some(pool_id), Some(expected_revision), Some(after_json)) => {
let current_revision = transaction
.query_row(
"SELECT revision FROM credential_pools WHERE pool_id=?1 AND active=1",
params![pool_id],
|row| row.get::<_, u64>(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.pool"))?
.unwrap_or(0);
let pool: hiroute_domain::CredentialPoolV1 = serde_json::from_str(after_json)
.map_err(|_| port(PortErrorCode::Corrupt, "control.activate.pool_stage"))?;
if current_revision != expected_revision
|| pool.pool_id != *pool_id
|| pool.revision != expected_revision.saturating_add(1)
{
return Err(port(PortErrorCode::Conflict, "control.activate.pool_cas"));
}
compute::write_credential_pool_in(&transaction, &pool)?;
}
_ => {
return Err(port(
PortErrorCode::Corrupt,
"control.activate.pool_metadata",
));
}
}
if record.7.is_some() && record.10.is_some() {
return Err(port(
PortErrorCode::Corrupt,
"control.activate.compute_metadata",
));
}
match (&record.10, record.11, &record.12, &record.13) {
(None, None, None, None) => {}
(Some(source_id), Some(expected_revision), before_json, Some(after_json)) => {
if compute::projection::is_projection_state(after_json) {
compute::projection::activate(
&transaction,
source_id,
expected_revision,
before_json.as_deref(),
after_json,
)?;
} else {
let current_json = transaction
.query_row(
"SELECT source_json FROM compute_sources WHERE source_id=?1",
params![source_id],
|row| row.get::<_, String>(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.source"))?;
if current_json.as_deref() != before_json.as_deref() {
return Err(port(PortErrorCode::Conflict, "control.activate.source_cas"));
}
let source: hiroute_domain::ComputeSourceV1 = serde_json::from_str(after_json)
.map_err(|_| {
port(PortErrorCode::Corrupt, "control.activate.source_stage")
})?;
let desired_revision = expected_revision.checked_add(1).ok_or_else(|| {
port(
PortErrorCode::Conflict,
"control.activate.source_revision_overflow",
)
})?;
if source.source_id != *source_id || source.revision != desired_revision {
return Err(port(PortErrorCode::Conflict, "control.activate.source_cas"));
}
compute::write_compute_source_in(&transaction, &source)?;
}
}
_ => {
return Err(port(
PortErrorCode::Corrupt,
"control.activate.source_metadata",
));
}
}
compute::management::activate(&transaction, &workspace, &staged, operation_id)?;
prices::activate(&transaction, &workspace, &staged)?;
transaction
.execute(
"INSERT INTO workspace_state(
workspace_id, desired_json, target_revision, desired_digest,
owner_operation_id, updated_at
) VALUES (?1, ?2, ?3, ?4, ?5, unixepoch())
ON CONFLICT(workspace_id) DO UPDATE SET
desired_json = excluded.desired_json,
target_revision = excluded.target_revision,
desired_digest = excluded.desired_digest,
owner_operation_id = excluded.owner_operation_id,
updated_at = excluded.updated_at",
params![&record.0, staged, record.2, &record.3, operation_id],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.write"))?;
transaction
.execute(
"INSERT INTO workspace_revision_heads(workspace_id, revision) VALUES (?1, ?2)
ON CONFLICT(workspace_id) DO UPDATE SET revision = excluded.revision",
params![&record.0, record.2],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.head"))?;
transaction
.execute(
"UPDATE control_effects SET activated = 1 WHERE operation_id = ?1",
params![operation_id],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.mark"))?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.activate.commit"))?;
Ok(effect.clone())
}
fn compensate_control(&self, effect: &OwnedEffectV1) -> PortResult<CompensationOutcome> {
if let Some(selection) = self.compensate_worker_dependency_selection(effect)? {
return Ok(selection);
}
if effect.kind != OwnedEffectKind::Control {
return Err(port(PortErrorCode::InvalidData, "control.compensate.kind"));
}
let operation_id = effect
.compensation
.get("operation_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "control.compensate.metadata"))?;
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.begin"))?;
let record = transaction
.query_row(
"SELECT workspace_id, before_exists, before_json, before_revision,
before_digest, before_owner_operation_id, after_revision,
after_digest, compensated, activated, compute_pool_id,
compute_pool_before_json, compute_pool_after_json,
compute_source_id, compute_source_before_json, compute_source_after_json
FROM control_effects WHERE operation_id = ?1",
params![operation_id],
|row| {
Ok((
row.get::<_, String>(0)?,
row.get::<_, bool>(1)?,
row.get::<_, Option<String>>(2)?,
row.get::<_, u64>(3)?,
row.get::<_, Option<String>>(4)?,
row.get::<_, Option<String>>(5)?,
row.get::<_, u64>(6)?,
row.get::<_, String>(7)?,
row.get::<_, bool>(8)?,
row.get::<_, bool>(9)?,
row.get::<_, Option<String>>(10)?,
row.get::<_, Option<String>>(11)?,
row.get::<_, Option<String>>(12)?,
row.get::<_, Option<String>>(13)?,
row.get::<_, Option<String>>(14)?,
row.get::<_, Option<String>>(15)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.lookup"))?
.ok_or_else(|| port(PortErrorCode::NotFound, "control.compensate.effect"))?;
if record.8 {
return Ok(CompensationOutcome::AlreadyCompensated);
}
if !record.9 {
transaction
.execute(
"UPDATE control_effects SET compensated = 1 WHERE operation_id = ?1",
params![operation_id],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.stage"))?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.commit"))?;
return Ok(CompensationOutcome::Compensated);
}
let current = transaction
.query_row(
"SELECT target_revision, desired_digest, owner_operation_id
FROM workspace_state WHERE workspace_id = ?1",
params![&record.0],
|row| {
Ok((
row.get::<_, u64>(0)?,
row.get::<_, String>(1)?,
row.get::<_, Option<String>>(2)?,
))
},
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.current"))?;
if !current.as_ref().is_some_and(|current| {
current.0 == record.6
&& current.1 == record.7
&& current.2.as_deref() == Some(operation_id)
}) {
return Ok(CompensationOutcome::OwnershipLost);
}
let workspace = WorkspaceId::parse(record.0.clone())
.map_err(|_| port(PortErrorCode::Corrupt, "control.compensate.workspace"))?;
if !compute::management::compensate(&transaction, &workspace, operation_id)? {
return Ok(CompensationOutcome::OwnershipLost);
}
if !prices::compensate(&transaction, operation_id)? {
return Ok(CompensationOutcome::OwnershipLost);
}
match (&record.10, &record.11, &record.12) {
(None, None, None) => {}
(Some(pool_id), before_json, Some(after_json)) => {
let current_pool = transaction
.query_row(
"SELECT pool_json FROM credential_pools WHERE pool_id=?1 AND active=1",
params![pool_id],
|row| row.get::<_, String>(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.pool"))?;
if current_pool.as_deref() != Some(after_json.as_str()) {
return Ok(CompensationOutcome::OwnershipLost);
}
if let Some(before_json) = before_json {
let pool: hiroute_domain::CredentialPoolV1 = serde_json::from_str(before_json)
.map_err(|_| {
port(PortErrorCode::Corrupt, "control.compensate.pool_before")
})?;
if &pool.pool_id != pool_id {
return Err(port(
PortErrorCode::Corrupt,
"control.compensate.pool_identity",
));
}
compute::write_credential_pool_in(&transaction, &pool)?;
} else {
transaction
.execute(
"DELETE FROM credential_pools WHERE pool_id=?1",
params![pool_id],
)
.map_err(|_| {
port(PortErrorCode::Unavailable, "control.compensate.pool_delete")
})?;
}
}
_ => {
return Err(port(
PortErrorCode::Corrupt,
"control.compensate.pool_metadata",
));
}
}
if record.10.is_some() && record.13.is_some() {
return Err(port(
PortErrorCode::Corrupt,
"control.compensate.compute_metadata",
));
}
match (&record.13, &record.14, &record.15) {
(None, None, None) => {}
(Some(source_id), before_json, Some(after_json)) => {
if compute::projection::is_projection_state(after_json) {
if !compute::projection::compensate(
&transaction,
source_id,
before_json.as_deref(),
after_json,
)? {
return Ok(CompensationOutcome::OwnershipLost);
}
} else {
let current_source = transaction
.query_row(
"SELECT source_json FROM compute_sources WHERE source_id=?1",
params![source_id],
|row| row.get::<_, String>(0),
)
.optional()
.map_err(|_| {
port(PortErrorCode::Unavailable, "control.compensate.source")
})?;
if current_source.as_deref() != Some(after_json.as_str()) {
return Ok(CompensationOutcome::OwnershipLost);
}
if let Some(before_json) = before_json {
let source: hiroute_domain::ComputeSourceV1 =
serde_json::from_str(before_json).map_err(|_| {
port(PortErrorCode::Corrupt, "control.compensate.source_before")
})?;
if &source.source_id != source_id {
return Err(port(
PortErrorCode::Corrupt,
"control.compensate.source_identity",
));
}
compute::write_compute_source_in(&transaction, &source)?;
} else {
transaction
.execute(
"DELETE FROM compute_sources WHERE source_id=?1",
params![source_id],
)
.map_err(|_| {
port(
PortErrorCode::Unavailable,
"control.compensate.source_delete",
)
})?;
}
}
}
_ => {
return Err(port(
PortErrorCode::Corrupt,
"control.compensate.source_metadata",
));
}
}
let restored_revision = record.6.checked_add(1).ok_or_else(|| {
port(
PortErrorCode::Conflict,
"control.compensate.revision_overflow",
)
})?;
if record.1 {
transaction
.execute(
"UPDATE workspace_state SET desired_json = ?2, target_revision = ?3,
desired_digest = ?4, owner_operation_id = ?5, updated_at = unixepoch()
WHERE workspace_id = ?1",
params![
&record.0,
record.2,
restored_revision,
record.4,
operation_id
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.restore"))?;
} else {
transaction
.execute(
"DELETE FROM workspace_state WHERE workspace_id = ?1",
params![&record.0],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.delete"))?;
}
transaction
.execute(
"INSERT INTO workspace_revision_heads(workspace_id, revision) VALUES (?1, ?2)
ON CONFLICT(workspace_id) DO UPDATE SET revision = excluded.revision",
params![&record.0, restored_revision],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.head"))?;
transaction
.execute(
"UPDATE control_effects SET compensated = 1 WHERE operation_id = ?1",
params![operation_id],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.mark"))?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.compensate.commit"))?;
Ok(CompensationOutcome::Compensated)
}
fn reconcile_compute_compensation(
&self,
operation: &OperationV1,
references: &[hiroute_domain::CredentialRefV1],
) -> PortResult<()> {
compute::management::reconcile_compensation(self, operation, references)
}
fn finish_operation(&self, operation: &mut OperationV1) -> PortResult<u64> {
if !operation.state.is_terminal() {
return Err(port(
PortErrorCode::InvalidData,
"control.finish.non_terminal",
));
}
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.finish.begin"))?;
plans::finish_draft_operation(&transaction, operation)?;
decision_services::finish(&transaction, operation)?;
compute::finish_save_handoff_in(&transaction, operation)?;
let generation = journal::save(&transaction, operation)?;
if operation.state != OperationState::NeedsAttention {
let released = transaction
.execute(
"DELETE FROM writer_claim WHERE singleton = 1 AND operation_id = ?1",
params![operation.operation_id.as_str()],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.finish.release"))?;
if released != 1 {
return Err(port(PortErrorCode::Conflict, "control.finish.claim"));
}
}
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.finish.commit"))?;
operation.acknowledge_journal_commit(generation);
read_control_head(&connection, &operation.workspace_id)
}
fn save_operation_tail(&self, operation: &mut OperationV1) -> PortResult<()> {
let id = operation.operation_id.to_string();
measure(
&self.diagnostics.borrow(),
PublicationStage::OperationSaveTail,
Some(&id),
None,
|| {
if operation.state.is_terminal() {
return Err(port(PortErrorCode::InvalidData, "control.tail.terminal"));
}
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.begin"))?;
let generation = journal::save(&transaction, operation)?;
transaction
.execute(
"DELETE FROM writer_claim WHERE singleton = 1 AND operation_id = ?1",
params![operation.operation_id.as_str()],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.release"))?;
let held: bool = transaction
.query_row("SELECT EXISTS(SELECT 1 FROM writer_claim)", [], |row| {
row.get(0)
})
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.held"))?;
if held {
// The journal save above is not committed: another operation's claim stays intact.
return Err(port(PortErrorCode::Conflict, "control.tail.claim"));
}
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.commit"))?;
operation.acknowledge_journal_commit(generation);
Ok(())
},
)
}
fn reclaim_operation_writer(&self, operation_id: &OperationId) -> PortResult<()> {
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.reclaim.begin"))?;
let holder: Option<String> = transaction
.query_row(
"SELECT operation_id FROM writer_claim WHERE singleton = 1",
[],
|row| row.get(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.reclaim.read"))?;
if holder
.as_deref()
.is_some_and(|holder| holder != operation_id.as_str())
{
return Err(port(PortErrorCode::Conflict, "control.tail.reclaim.busy"));
}
if holder.is_none() {
transaction
.execute(
"INSERT INTO writer_claim(singleton, operation_id, admitted_at)
VALUES (1, ?1, unixepoch())",
params![operation_id.as_str()],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.reclaim.insert"))?;
}
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "control.tail.reclaim.commit"))?;
Ok(())
}
fn save_agent_surface_check(
&self,
workspace: &WorkspaceId,
record: &hiroute_domain::AgentSurfaceCheckRecordV1,
) -> PortResult<bool> {
record
.validate()
.map_err(|_| port(PortErrorCode::InvalidData, "surface-check.record"))?;
let surface = serde_json::to_value(record.surface)
.ok()
.and_then(|value| value.as_str().map(str::to_owned))
.ok_or_else(|| port(PortErrorCode::InvalidData, "surface-check.surface"))?;
let encoded = serde_json::to_string(record)
.map_err(|_| port(PortErrorCode::InvalidData, "surface-check.encode"))?;
let mut connection = self.connection.borrow_mut();
let transaction = connection
.transaction_with_behavior(TransactionBehavior::Immediate)
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.begin"))?;
let active: Option<u64> = transaction
.query_row(
"SELECT publication_revision FROM gateway_publications
WHERE workspace_id = ?1 AND state = 'active'",
params![workspace.as_str()],
|row| row.get(0),
)
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.active"))?;
if active != Some(record.applied_revision.get()) {
// A newer publication already replaced the checked revision: the stale result is
// dropped instead of polluting the new release's verification state.
return Ok(false);
}
transaction
.execute(
"INSERT INTO agent_surface_checks
(workspace_id, context_id, surface, applied_revision, record_json, updated_at)
VALUES (?1, ?2, ?3, ?4, ?5, unixepoch())
ON CONFLICT(workspace_id, context_id, surface) DO UPDATE SET
applied_revision = excluded.applied_revision,
record_json = excluded.record_json,
updated_at = excluded.updated_at",
params![
workspace.as_str(),
record.context_id,
surface,
record.applied_revision.get(),
encoded
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.write"))?;
transaction
.commit()
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.commit"))?;
Ok(true)
}
fn agent_surface_checks(
&self,
workspace: &WorkspaceId,
context_id: &str,
) -> PortResult<Vec<hiroute_domain::AgentSurfaceCheckRecordV1>> {
let connection = self.connection.borrow();
let mut statement = connection
.prepare(
"SELECT record_json FROM agent_surface_checks
WHERE workspace_id = ?1 AND context_id = ?2 ORDER BY surface",
)
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.prepare"))?;
let rows = statement
.query_map(params![workspace.as_str(), context_id], |row| {
row.get::<_, String>(0)
})
.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.query"))?;
let mut records = Vec::new();
for row in rows {
let encoded = row.map_err(|_| port(PortErrorCode::Unavailable, "surface-check.row"))?;
let record: hiroute_domain::AgentSurfaceCheckRecordV1 = serde_json::from_str(&encoded)
.map_err(|_| port(PortErrorCode::Corrupt, "surface-check.decode"))?;
record
.validate()
.map_err(|_| port(PortErrorCode::Corrupt, "surface-check.record"))?;
records.push(record);
}
Ok(records)
}
}
fn read_revisions(connection: &Connection, workspace: &WorkspaceId) -> PortResult<RevisionSetV1> {
let target = read_control_head(connection, workspace)?;
let mut statement = connection
.prepare(
"SELECT dependency_key, revision FROM dependency_revisions
WHERE workspace_id = ?1 ORDER BY dependency_key",
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.revisions.prepare"))?;
let rows = statement
.query_map(params![workspace.as_str()], |row| {
Ok((row.get::<_, String>(0)?, row.get::<_, u64>(1)?))
})
.map_err(|_| port(PortErrorCode::Unavailable, "control.revisions.query"))?;
let mut dependencies = BTreeMap::new();
for row in rows {
let (key, revision) =
row.map_err(|_| port(PortErrorCode::Corrupt, "control.revisions.row"))?;
dependencies.insert(key, revision);
}
Ok(RevisionSetV1 {
target,
dependencies,
})
}
fn read_control_head(connection: &Connection, workspace: &WorkspaceId) -> PortResult<u64> {
connection
.query_row(
"SELECT revision FROM workspace_revision_heads WHERE workspace_id = ?1",
params![workspace.as_str()],
|row| row.get(0),
)
.optional()
.map(|revision| revision.unwrap_or(0))
.map_err(|_| port(PortErrorCode::Unavailable, "control.revisions.target"))
}
fn store_steps(transaction: &Transaction<'_>, operation: &OperationV1) -> PortResult<()> {
for step in &operation.steps {
store_step(transaction, operation, step)?;
}
Ok(())
}
fn store_step(
transaction: &Transaction<'_>,
operation: &OperationV1,
step: &OperationStepV1,
) -> PortResult<()> {
let encoded = serde_json::to_string(&hiroute_domain::canonicalize_json(json!({
"schema": "hiroute.operation-step/v1",
"step": step,
})))
.map_err(|_| port(PortErrorCode::InvalidData, "control.step.encode"))?;
transaction
.execute(
"INSERT INTO operation_steps(operation_id, step_no, step_kind, state, step_json)
VALUES (?1, ?2, ?3, ?4, ?5)
ON CONFLICT(operation_id, step_no) DO UPDATE SET
step_kind = excluded.step_kind,
state = excluded.state,
step_json = excluded.step_json",
params![
operation.operation_id.as_str(),
step.sequence,
serde_json::to_value(step.kind)
.ok()
.and_then(|value| value.as_str().map(str::to_owned))
.unwrap_or_else(|| "invalid".to_owned()),
serde_json::to_value(step.status)
.ok()
.and_then(|value| value.as_str().map(str::to_owned))
.unwrap_or_else(|| "invalid".to_owned()),
encoded,
],
)
.map_err(|_| port(PortErrorCode::Unavailable, "control.step.write"))?;
Ok(())
}
fn load_operation_where<P: rusqlite::Params>(
diagnostics: &hiroute_diagnostics::DiagnosticsPort,
connection: &Connection,
predicate: &str,
parameters: P,
) -> PortResult<Option<OperationV1>> {
let sql = format!("SELECT operation_json FROM operations WHERE {predicate}");
let encoded: Option<String> = measure(
diagnostics,
PublicationStage::OperationRead,
None,
None,
|| {
connection
.query_row(&sql, parameters, |row| row.get(0))
.optional()
.map_err(|_| port(PortErrorCode::Unavailable, "control.operation.read"))
},
)?;
encoded
.map(|encoded| decode_operation(diagnostics, &encoded))
.transpose()
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct DurableOperation {
schema_version: u16,
operation_id: OperationId,
workspace_id: WorkspaceId,
idempotency: IdempotencyScopeV1,
request_digest: CanonicalDigest,
accepted_digest: CanonicalDigest,
expected_revisions: RevisionSetV1,
plan: hiroute_domain::StoredOperationInputV1,
state: OperationState,
generation: u64,
steps: Vec<OperationStepV1>,
safe_error_code: Option<String>,
}
fn decode_operation(
diagnostics: &hiroute_diagnostics::DiagnosticsPort,
encoded: &str,
) -> PortResult<OperationV1> {
measure(
diagnostics,
PublicationStage::OperationDecode,
None,
Some(encoded.len()),
|| {
let durable: DurableOperation = measure(
diagnostics,
PublicationStage::OperationJsonParse,
None,
Some(encoded.len()),
|| {
serde_json::from_str(encoded)
.map_err(|_| port(PortErrorCode::Corrupt, "control.operation.decode"))
},
)?;
if durable.schema_version != hiroute_domain::OPERATION_SCHEMA_VERSION {
return Err(port(PortErrorCode::Corrupt, "control.operation.schema"));
}
let operation_id = durable.operation_id.to_string();
measure(
diagnostics,
PublicationStage::OperationReconstruct,
Some(&operation_id),
Some(encoded.len()),
|| {
let plan = measure(
diagnostics,
PublicationStage::OperationPlanValidate,
Some(&operation_id),
Some(encoded.len()),
|| {
durable
.plan
.build()
.map_err(|_| port(PortErrorCode::Corrupt, "control.operation.plan"))
},
)?;
let expected_id = OperationId::derive(
&durable.workspace_id,
&durable.idempotency,
&durable.request_digest,
);
if expected_id != durable.operation_id {
return Err(port(PortErrorCode::Corrupt, "control.operation.id"));
}
measure(
diagnostics,
PublicationStage::OperationRestore,
Some(&operation_id),
Some(encoded.len()),
|| {
let mut operation = OperationV1::new(
durable.operation_id,
durable.workspace_id,
durable.idempotency,
durable.request_digest,
durable.accepted_digest,
durable.expected_revisions,
plan,
)
.map_err(|_| port(PortErrorCode::Corrupt, "control.operation.plan"))?;
operation
.restore_durable_state(
durable.state,
durable.generation,
durable.steps,
durable.safe_error_code,
)
.map_err(|_| {
port(PortErrorCode::Corrupt, "control.operation.journal")
})?;
Ok(operation)
},
)
},
)
},
)
}
fn control_effect(
operation_id: &OperationId,
workspace: &WorkspaceId,
before: Option<CanonicalDigest>,
after: CanonicalDigest,
after_revision: u64,
) -> OwnedEffectV1 {
OwnedEffectV1 {
effect_id: format!("control:{workspace}"),
kind: OwnedEffectKind::Control,
target: workspace.to_string(),
before_fingerprint: before,
after_fingerprint: Some(after),
compensation: json!({
"schema": "hiroute.control-compensation/v1",
"operation_id": operation_id.as_str(),
"after_revision": after_revision,
})
.into(),
}
}
fn parse_digest(value: &str) -> Option<CanonicalDigest> {
CanonicalDigest::parse(value).ok()
}
fn port(code: PortErrorCode, context: &'static str) -> PortError {
PortError::new(code, context)
}
#[derive(Clone, Debug, Deserialize, Serialize)]
struct NativeRestorationReceipt {
fingerprint: Option<CanonicalDigest>,
}
#[derive(Clone, Debug, Deserialize, Serialize)]
struct ArtifactMarker {
schema: String,
restore_store_uuid: String,
restore_key_id: CanonicalDigest,
operation_id: String,
effect_id: String,
kind: OwnedEffectKind,
target: String,
before_exists: bool,
before_digest: Option<CanonicalDigest>,
before_mode: Option<u32>,
#[serde(default, skip_serializing_if = "Option::is_none")]
before_windows_permissions: Option<hiroute_platform::file_security::WindowsPermissions>,
after_digest: CanonicalDigest,
#[serde(default = "artifact_present")]
after_exists: bool,
after_mode: u32,
#[serde(default, skip_serializing_if = "Option::is_none")]
after_windows_permissions: Option<hiroute_platform::file_security::WindowsPermissions>,
sensitive: bool,
#[serde(default)]
rendered: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
intent_digest: Option<CanonicalDigest>,
#[serde(default, skip_serializing_if = "Option::is_none")]
external_path_digest: Option<CanonicalDigest>,
backup_name: Option<String>,
#[serde(default)]
backup_aad: ArtifactBackupAad,
activated: bool,
compensated: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
native_restoration: Option<NativeRestorationReceipt>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
created_directories: Vec<CreatedNativeDirectory>,
}
#[derive(Clone, Copy, Debug, Default, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
enum ArtifactBackupAad {
/// Decodes an authenticated backup created by marker v2 during one-time migration.
#[default]
LegacyV2,
/// Decodes an authenticated backup created by marker v3 during one-time migration.
LegacyV3,
CurrentV4,
CurrentWindowsV5,
}
/// Writes only adapter-owned publication/config artifacts. Restore bytes are independently
/// AEAD-sealed in an owner-only restore directory, never in `control.db` or the Operation journal.
pub struct ManagedArtifactStore {
root: PathBuf,
restore_root: PathBuf,
restore_key: Zeroizing<Vec<u8>>,
restore_store_uuid: String,
restore_key_id: CanonicalDigest,
external_targets: std::sync::RwLock<BTreeMap<String, PathBuf>>,
// Process-local proof only. Reopening/replaying a deletion never recreates it.
untouched_deletions: std::sync::Mutex<BTreeMap<(String, String), CanonicalDigest>>,
}
fn artifact_present() -> bool {
true
}
const RESTORE_KEY_HEADER: &[u8; 8] = b"HIRRST2\0";
const RESTORE_BACKUP_HEADER: &[u8; 8] = b"HIRBAK1\0";
const RESTORE_KEY_BYTES: usize = 32;
const RESTORE_NONCE_BYTES: usize = 12;
const RESTORE_STORE_UUID_BYTES: usize = 16;
struct RestoreKeyMaterial {
bytes: Zeroizing<Vec<u8>>,
store_uuid: String,
key_id: CanonicalDigest,
}
impl ManagedArtifactStore {
pub fn open(
_authority: &DaemonStorageAuthority,
root: impl AsRef<Path>,
restore_root: impl AsRef<Path>,
) -> Result<Self, LocalStorageError> {
crate::prepare_owner_directory(root.as_ref())?;
crate::prepare_owner_directory(restore_root.as_ref())?;
let restore = load_or_create_restore_key(
&restore_root.as_ref().join(".restore-key"),
restore_root.as_ref(),
)?;
let store = Self {
root: root.as_ref().to_path_buf(),
restore_root: restore_root.as_ref().to_path_buf(),
restore_key: restore.bytes,
restore_store_uuid: restore.store_uuid,
restore_key_id: restore.key_id,
external_targets: std::sync::RwLock::new(BTreeMap::new()),
untouched_deletions: std::sync::Mutex::new(BTreeMap::new()),
};
store.migrate_legacy_markers()?;
store.validate_existing_marker_bindings()?;
Ok(store)
}
pub(crate) fn open_with_external_target(
_authority: &DaemonStorageAuthority,
root: impl AsRef<Path>,
restore_root: impl AsRef<Path>,
target: impl Into<String>,
path: impl Into<PathBuf>,
) -> Result<Self, LocalStorageError> {
Self::open_with_external_targets(
_authority,
root,
restore_root,
[(target.into(), path.into())],
)
}
pub(crate) fn open_with_external_targets(
_authority: &DaemonStorageAuthority,
root: impl AsRef<Path>,
restore_root: impl AsRef<Path>,
targets: impl IntoIterator<Item = (String, PathBuf)>,
) -> Result<Self, LocalStorageError> {
let mut external_targets = BTreeMap::new();
for (target, path) in targets {
// Startup registers potential targets, including Agents never configured here.
// Native permissions are checked on use and for every durable recovery marker.
validate_external_target_location(&path)?;
if external_targets.contains_key(&target)
|| external_targets.values().any(|existing| existing == &path)
{
return Err(LocalStorageError::InvalidData);
}
external_targets.insert(target, path);
}
crate::prepare_owner_directory(root.as_ref())?;
crate::prepare_owner_directory(restore_root.as_ref())?;
let restore = load_or_create_restore_key(
&restore_root.as_ref().join(".restore-key"),
restore_root.as_ref(),
)?;
let store = Self {
root: root.as_ref().to_path_buf(),
restore_root: restore_root.as_ref().to_path_buf(),
restore_key: restore.bytes,
restore_store_uuid: restore.store_uuid,
restore_key_id: restore.key_id,
external_targets: std::sync::RwLock::new(external_targets),
untouched_deletions: std::sync::Mutex::new(BTreeMap::new()),
};
// Register all exact bindings before validating the targets actually owned by markers.
// A never-managed Agent's directory cannot prevent unrelated service startup.
store.migrate_legacy_markers()?;
store.validate_existing_marker_bindings()?;
Ok(store)
}
pub fn read_target(&self, target: &str) -> Result<Option<Vec<u8>>, LocalStorageError> {
let path = self.target_path(target)?;
Ok(read_optional_regular_file(&path)?.map(|bytes| bytes.to_vec()))
}
/// Binds one registered logical effect target to an exact native file outside the HiRoute
/// artifact root. The caller must do this during composition, before recovery. The binding is
/// recorded by digest in every new marker so a changed HOME/layout cannot redirect recovery.
pub fn bind_external_target(
&mut self,
target: impl Into<String>,
path: impl Into<PathBuf>,
) -> Result<(), LocalStorageError> {
let target = target.into();
// Validate the logical target through the normal confined resolver before registering an
// alternate physical location.
let _ = self.target_path(&target)?;
let path = path.into();
validate_external_target_path(&path)?;
let targets = self
.external_targets
.get_mut()
.map_err(|_| LocalStorageError::InvalidData)?;
if targets.values().any(|existing| existing == &path)
|| targets.insert(target, path).is_some()
{
return Err(LocalStorageError::InvalidData);
}
self.validate_existing_marker_bindings()
}
/// Add exact backend-validated profile bindings after discovery. Existing bindings are
/// immutable and idempotent; registration itself performs no native write or authorization.
pub fn register_external_targets(
&self,
additions: impl IntoIterator<Item = (String, PathBuf)>,
) -> Result<(), LocalStorageError> {
let additions: Vec<_> = additions.into_iter().collect();
for (target, path) in &additions {
let logical = Path::new(target);
if logical.is_absolute()
|| logical.components().any(|part| {
!matches!(part, Component::Normal(_))
|| part.as_os_str().to_string_lossy().starts_with('.')
})
{
return Err(LocalStorageError::InvalidData);
}
validate_external_target_location(path)?;
}
let mut targets = self
.external_targets
.write()
.map_err(|_| LocalStorageError::InvalidData)?;
let mut next = targets.clone();
for (target, path) in additions {
if next.get(&target).is_some_and(|old| old != &path)
|| next.iter().any(|(key, old)| key != &target && old == &path)
{
return Err(LocalStorageError::InvalidData);
}
next.insert(target, path);
}
*targets = next;
Ok(())
}
/// Stages already rendered native bytes using the same encrypted restore and atomic
/// activation machinery as ordinary managed artifacts. Only the renderer bytes differ; the
/// sealed Operation intent remains the ownership and recovery identity.
pub fn apply_rendered_external(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
desired: &[u8],
) -> PortResult<OwnedEffectV1> {
self.apply_external_bytes(operation_id, intent, desired, true, true, true)
}
/// Confirms that a rendered external effect still has its activated marker and decryptable
/// restore point. The native integration separately verifies its owned fields semantically;
/// this deliberately does not require the entire external file to remain byte-identical.
pub fn rendered_external_is_recoverable(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
) -> PortResult<bool> {
let Some(marker) = self
.load_marker(operation_id, intent.effect_id())
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.marker.read"))?
else {
return Ok(false);
};
if marker.compensated
|| !marker.activated
|| !marker.rendered
|| marker.kind != intent.kind()
|| marker.target != intent.target()
|| marker.before_digest.as_ref() != intent.before_fingerprint()
|| marker.after_mode != intent.desired_mode()
|| marker.intent_digest.as_ref()
!= Some(
&CanonicalDigest::of(intent.desired())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.intent_digest"))?,
)
{
return Ok(false);
}
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.backup.validate"))?;
Ok(true)
}
fn target_path(&self, target: &str) -> Result<PathBuf, LocalStorageError> {
let external = self
.external_targets
.read()
.map_err(|_| LocalStorageError::InvalidData)?
.get(target)
.cloned();
if let Some(path) = external {
validate_external_target_path(&path)?;
return Ok(path);
}
let relative = Path::new(target);
if relative.is_absolute()
|| relative.components().any(|component| {
!matches!(component, Component::Normal(_))
|| component.as_os_str().to_string_lossy().starts_with('.')
})
{
return Err(LocalStorageError::InvalidData);
}
let root_metadata = fs::symlink_metadata(&self.root)?;
if root_metadata.file_type().is_symlink() || !root_metadata.file_type().is_dir() {
return Err(LocalStorageError::Permission);
}
let mut path = self.root.clone();
let mut components = relative.components().peekable();
let mut missing_ancestor = false;
while let Some(Component::Normal(component)) = components.next() {
path.push(component);
if components.peek().is_some() && !missing_ancestor {
match fs::symlink_metadata(&path) {
Ok(metadata) => validate_owner_directory_metadata(&metadata)?,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
// A missing ancestor proves the final target is absent. Preview remains
// read-only; Apply creates and validates each directory separately.
missing_ancestor = true;
}
Err(error) => return Err(error.into()),
}
}
}
Ok(path)
}
fn marker_key(operation_id: &OperationId, effect_id: &str) -> String {
let digest = CanonicalDigest::of_bytes(
format!("artifact-marker-v1\0{operation_id}\0{effect_id}").as_bytes(),
);
digest.as_str()[7..39].to_owned()
}
fn marker_path(&self, operation_id: &OperationId, effect_id: &str) -> PathBuf {
self.restore_root.join(format!(
"{}.json",
Self::marker_key(operation_id, effect_id)
))
}
fn stage_path(&self, marker: &ArtifactMarker) -> Result<PathBuf, LocalStorageError> {
let target = self.target_path(&marker.target)?;
let file_name = target
.file_name()
.and_then(|name| name.to_str())
.ok_or(LocalStorageError::InvalidData)?;
let operation_id = OperationId::parse(marker.operation_id.clone())
.map_err(|_| LocalStorageError::InvalidData)?;
let key = Self::marker_key(&operation_id, &marker.effect_id);
Ok(target.with_file_name(format!(".{file_name}.{key}.hiroute-stage")))
}
fn load_marker(
&self,
operation_id: &OperationId,
effect_id: &str,
) -> Result<Option<ArtifactMarker>, LocalStorageError> {
let path = self.marker_path(operation_id, effect_id);
match fs::symlink_metadata(&path) {
Ok(metadata) => {
validate_owner_regular_file(&metadata)?;
#[cfg(windows)]
let bytes = read_private_restore_file(&path)?;
#[cfg(not(windows))]
let bytes = fs::read(path)?;
let encoded: Value =
serde_json::from_slice(&bytes).map_err(|_| LocalStorageError::InvalidData)?;
if encoded.get("backup_aad").is_none() {
return Err(LocalStorageError::InvalidData);
}
let marker: ArtifactMarker =
serde_json::from_value(encoded).map_err(|_| LocalStorageError::InvalidData)?;
if marker.schema != current_artifact_schema()
|| marker.operation_id != operation_id.as_str()
|| marker.effect_id != effect_id
|| marker.restore_store_uuid != self.restore_store_uuid
|| marker.restore_key_id != self.restore_key_id
{
return Err(LocalStorageError::InvalidData);
}
self.validate_marker_shape(&marker)?;
Ok(Some(marker))
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
Err(error) => Err(error.into()),
}
}
/// Atomically upgrades marker metadata while preserving the exact authenticated backup.
/// The explicit AAD discriminator prevents a schema-label rewrite from making ciphertext
/// unrecoverable after a crash.
fn migrate_legacy_markers(&self) -> Result<(), LocalStorageError> {
for entry in fs::read_dir(&self.restore_root)? {
let entry = entry?;
let path = entry.path();
if path.extension().and_then(|extension| extension.to_str()) != Some("json") {
continue;
}
let metadata = fs::symlink_metadata(&path)?;
validate_owner_regular_file(&metadata).map_err(|_| LocalStorageError::Locked)?;
#[cfg(windows)]
let bytes = read_private_restore_file(&path)?;
#[cfg(not(windows))]
let bytes = fs::read(&path)?;
let encoded: Value =
serde_json::from_slice(&bytes).map_err(|_| LocalStorageError::Locked)?;
let has_backup_aad = encoded.get("backup_aad").is_some();
let mut marker: ArtifactMarker =
serde_json::from_value(encoded).map_err(|_| LocalStorageError::Locked)?;
let operation_id = OperationId::parse(marker.operation_id.clone())
.map_err(|_| LocalStorageError::Locked)?;
if path != self.marker_path(&operation_id, &marker.effect_id)
|| marker.restore_store_uuid != self.restore_store_uuid
|| marker.restore_key_id != self.restore_key_id
|| marker.external_path_digest != self.external_path_digest(&marker.target)?
{
return Err(LocalStorageError::Locked);
}
let external = self
.external_targets
.read()
.map_err(|_| LocalStorageError::InvalidData)?
.contains_key(&marker.target);
if external {
// A durable effect is a real recovery consumer, not an unused registration.
// Validate before touching even a legacy marker's internal representation.
let _ = self.target_path(&marker.target)?;
}
let changed = match marker.schema.as_str() {
"hiroute.managed-artifact-marker/v2" => {
marker.backup_aad = if marker.backup_name.is_some() {
ArtifactBackupAad::LegacyV2
} else {
ArtifactBackupAad::CurrentV4
};
true
}
"hiroute.managed-artifact-marker/v3" => {
marker.backup_aad = if marker.backup_name.is_some() {
ArtifactBackupAad::LegacyV3
} else {
ArtifactBackupAad::CurrentV4
};
true
}
#[cfg(windows)]
"hiroute.windows-managed-artifact-marker/v5" if has_backup_aad => false,
"hiroute.managed-artifact-marker/v4" if has_backup_aad => false,
"hiroute.managed-artifact-marker/v4" => return Err(LocalStorageError::Locked),
_ => return Err(LocalStorageError::Locked),
};
if changed {
marker.schema = "hiroute.managed-artifact-marker/v4".to_owned();
}
self.validate_marker_shape(&marker)
.map_err(|_| LocalStorageError::Locked)?;
self.validated_backup(&marker)
.map_err(|_| LocalStorageError::Locked)?;
if changed {
self.save_marker(&marker)
.map_err(|_| LocalStorageError::Locked)?;
}
}
Ok(())
}
fn validate_existing_marker_bindings(&self) -> Result<(), LocalStorageError> {
for entry in fs::read_dir(&self.restore_root)? {
let entry = entry?;
let path = entry.path();
if path.extension().and_then(|extension| extension.to_str()) != Some("json") {
continue;
}
let metadata = fs::symlink_metadata(&path)?;
validate_owner_regular_file(&metadata)?;
#[cfg(windows)]
let bytes = read_private_restore_file(&path)?;
#[cfg(not(windows))]
let bytes = fs::read(path)?;
let marker: ArtifactMarker =
serde_json::from_slice(&bytes).map_err(|_| LocalStorageError::Locked)?;
if marker.schema != current_artifact_schema()
|| marker.restore_store_uuid != self.restore_store_uuid
|| marker.restore_key_id != self.restore_key_id
|| marker.external_path_digest != self.external_path_digest(&marker.target)?
{
return Err(LocalStorageError::Locked);
}
self.validate_marker_shape(&marker)
.map_err(|_| LocalStorageError::Locked)?;
}
Ok(())
}
fn save_marker(&self, marker: &ArtifactMarker) -> Result<(), LocalStorageError> {
let operation_id = OperationId::parse(marker.operation_id.clone())
.map_err(|_| LocalStorageError::InvalidData)?;
let path = self.marker_path(&operation_id, &marker.effect_id);
let encoded = serde_json::to_vec(marker).map_err(|_| LocalStorageError::InvalidData)?;
atomic_write(&path, &encoded, 0o600, true)
}
fn validate_marker_shape(&self, marker: &ArtifactMarker) -> Result<(), LocalStorageError> {
match (
marker.before_exists,
marker.before_digest.as_ref(),
marker.before_mode,
marker.backup_name.as_deref(),
) {
(true, Some(_), Some(mode), Some(name)) if supported_artifact_mode(mode) => {
let relative = Path::new(name);
if relative.components().count() != 1
|| relative
.components()
.any(|component| !matches!(component, Component::Normal(_)))
|| name.starts_with('.')
{
return Err(LocalStorageError::InvalidData);
}
Ok(())
}
(false, None, None, None) => Ok(()),
_ => Err(LocalStorageError::InvalidData),
}?;
if marker.schema != current_artifact_schema()
|| (!marker.after_exists
&& (!marker.rendered || marker.kind != OwnedEffectKind::AgentArtifact))
|| !supported_artifact_mode(marker.after_mode)
|| (marker.sensitive && marker.after_mode != 0o600)
|| marker.external_path_digest != self.external_path_digest(&marker.target)?
|| marker.native_restoration.is_some()
&& (!marker.rendered
|| !marker.activated
|| marker.compensated
|| marker.kind != OwnedEffectKind::AgentArtifact)
|| marker.rendered != marker.intent_digest.is_some()
|| (marker.backup_name.is_none() && marker.backup_aad != current_artifact_aad())
{
return Err(LocalStorageError::InvalidData);
}
#[cfg(windows)]
if marker.before_windows_permissions.is_some() != marker.before_exists
|| marker.after_windows_permissions.is_none()
|| marker.backup_aad != ArtifactBackupAad::CurrentWindowsV5
{
return Err(LocalStorageError::InvalidData);
}
#[cfg(not(windows))]
if marker.before_windows_permissions.is_some() || marker.after_windows_permissions.is_some()
{
return Err(LocalStorageError::InvalidData);
}
Ok(())
}
fn external_path_digest(
&self,
target: &str,
) -> Result<Option<CanonicalDigest>, LocalStorageError> {
self.external_targets
.read()
.map_err(|_| LocalStorageError::InvalidData)?
.get(target)
.map(|path| {
path.to_str()
.map(|value| CanonicalDigest::of_bytes(value.as_bytes()))
.ok_or(LocalStorageError::InvalidData)
})
.transpose()
}
fn validated_backup(
&self,
marker: &ArtifactMarker,
) -> Result<Option<Zeroizing<Vec<u8>>>, LocalStorageError> {
self.validate_marker_shape(marker)?;
let Some(name) = marker.backup_name.as_deref() else {
return Ok(None);
};
let path = self.restore_root.join(name);
let metadata = fs::symlink_metadata(&path)?;
validate_owner_regular_file(&metadata)?;
#[cfg(windows)]
let sealed = read_private_restore_file(&path)?;
#[cfg(not(windows))]
let sealed = fs::read(path)?;
if sealed.len() <= RESTORE_BACKUP_HEADER.len() + RESTORE_NONCE_BYTES
|| &sealed[..RESTORE_BACKUP_HEADER.len()] != RESTORE_BACKUP_HEADER
{
return Err(LocalStorageError::InvalidData);
}
let nonce_start = RESTORE_BACKUP_HEADER.len();
let ciphertext_start = nonce_start + RESTORE_NONCE_BYTES;
let cipher =
Aes256Gcm::new_from_slice(&self.restore_key).map_err(|_| LocalStorageError::Crypto)?;
let bytes = Zeroizing::new(
cipher
.decrypt(
Nonce::from_slice(&sealed[nonce_start..ciphertext_start]),
Payload {
msg: &sealed[ciphertext_start..],
aad: artifact_backup_aad(marker).as_bytes(),
},
)
.map_err(|_| LocalStorageError::Crypto)?,
);
#[cfg(not(windows))]
let backup_fingerprint = artifact_fingerprint(&bytes, marker.before_mode.unwrap_or(0o600))?;
#[cfg(windows)]
let backup_fingerprint = windows_artifact_fingerprint(
&bytes,
marker
.before_windows_permissions
.as_ref()
.ok_or(LocalStorageError::InvalidData)?,
)?;
if Some(backup_fingerprint) != marker.before_digest {
return Err(LocalStorageError::InvalidData);
}
Ok(Some(bytes))
}
fn seal_backup(
&self,
marker: &ArtifactMarker,
bytes: &[u8],
) -> Result<Vec<u8>, LocalStorageError> {
let cipher =
Aes256Gcm::new_from_slice(&self.restore_key).map_err(|_| LocalStorageError::Crypto)?;
let mut nonce = [0_u8; RESTORE_NONCE_BYTES];
getrandom::fill(&mut nonce).map_err(|_| LocalStorageError::Crypto)?;
let ciphertext = cipher
.encrypt(
Nonce::from_slice(&nonce),
Payload {
msg: bytes,
aad: artifact_backup_aad(marker).as_bytes(),
},
)
.map_err(|_| LocalStorageError::Crypto)?;
let mut sealed = Vec::with_capacity(
RESTORE_BACKUP_HEADER.len() + RESTORE_NONCE_BYTES + ciphertext.len(),
);
sealed.extend_from_slice(RESTORE_BACKUP_HEADER);
sealed.extend_from_slice(&nonce);
sealed.extend_from_slice(&ciphertext);
Ok(sealed)
}
fn effect(marker: &ArtifactMarker) -> OwnedEffectV1 {
OwnedEffectV1 {
effect_id: marker.effect_id.clone(),
kind: marker.kind,
target: marker.target.clone(),
before_fingerprint: marker.before_digest.clone(),
after_fingerprint: marker.native_restoration.as_ref().map_or_else(
|| marker.after_exists.then(|| marker.after_digest.clone()),
|r| r.fingerprint.clone(),
),
compensation: json!({
"schema": "hiroute.managed-artifact-compensation/v1",
"operation_id": marker.operation_id,
"effect_id": marker.effect_id,
})
.into(),
}
}
fn apply_external_bytes(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
desired: &[u8],
rendered: bool,
sensitive: bool,
after_exists: bool,
) -> PortResult<OwnedEffectV1> {
self.apply_external_bytes_with_parents(
operation_id,
intent,
desired,
rendered,
sensitive,
after_exists,
Vec::new(),
)
}
#[allow(clippy::too_many_arguments)]
fn apply_external_bytes_with_parents(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
desired: &[u8],
rendered: bool,
sensitive: bool,
after_exists: bool,
inherited_parents: Vec<CreatedNativeDirectory>,
) -> PortResult<OwnedEffectV1> {
let mut untouched = self
.untouched_deletions
.lock()
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.deletion.lock"))?;
if !matches!(
intent.kind(),
OwnedEffectKind::Publication | OwnedEffectKind::AgentArtifact
) || (sensitive && intent.desired_mode() != 0o600)
{
return Err(port(PortErrorCode::InvalidData, "artifact.kind_or_mode"));
}
let desired_digest = artifact_fingerprint(desired, intent.desired_mode())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.after_fingerprint"))?;
if let Some(marker) = self
.load_marker(operation_id, intent.effect_id())
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.marker.read"))?
{
if marker.after_exists != after_exists
|| marker.rendered != rendered
|| marker.sensitive != sensitive
|| marker.after_digest != desired_digest
|| (rendered
&& marker.intent_digest.as_ref()
!= Some(&CanonicalDigest::of(intent.desired()).map_err(|_| {
port(PortErrorCode::InvalidData, "artifact.intent_digest")
})?))
{
return Err(port(PortErrorCode::Conflict, "artifact.ownership"));
}
return match self.observe_artifact(operation_id, intent)? {
EffectReconciliation::Staged(effect) | EffectReconciliation::Applied(effect) => {
Ok(effect)
}
EffectReconciliation::OwnershipLost(_) => {
Err(port(PortErrorCode::Conflict, "artifact.ownership"))
}
EffectReconciliation::Missing => {
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.backup.validate"))?;
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.stage"))?;
atomic_write(&stage, desired, marker.after_mode, marker.sensitive)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.stage.write"))?;
Ok(Self::effect(&marker))
}
};
}
let target = self
.target_path(intent.target())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.target"))?;
let before = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.read"))?;
let before_digest = before.as_ref().map(|snapshot| snapshot.fingerprint.clone());
if before_digest.as_ref() != intent.before_fingerprint() {
return Err(port(PortErrorCode::Conflict, "artifact.before_fingerprint"));
}
let new_directories = if after_exists || before.is_some() {
native_directories::prepare_parent(&target)
.map_err(|_| port(PortErrorCode::PermissionDenied, "artifact.target.parent"))?
} else {
Vec::new()
};
let created_directories =
native_directories::merge_lineage(inherited_parents, new_directories)
.map_err(|_| port(PortErrorCode::InvalidData, "native.parents.bound"))?;
let key = Self::marker_key(operation_id, intent.effect_id());
let backup_name = before.as_ref().map(|_| format!("{key}.before"));
let marker = ArtifactMarker {
schema: current_artifact_schema().to_owned(),
restore_store_uuid: self.restore_store_uuid.clone(),
restore_key_id: self.restore_key_id.clone(),
operation_id: operation_id.to_string(),
effect_id: intent.effect_id().to_owned(),
kind: intent.kind(),
target: intent.target().to_owned(),
before_exists: before.is_some(),
before_digest,
before_mode: before.as_ref().map(|snapshot| snapshot.mode),
before_windows_permissions: before
.as_ref()
.and_then(|snapshot| snapshot.windows_permissions.clone()),
after_digest: desired_digest,
after_exists,
after_mode: intent.desired_mode(),
after_windows_permissions: desired_windows_permissions(intent.desired_mode()).map_err(
|_| {
port(
PortErrorCode::PermissionDenied,
"artifact.native_permissions",
)
},
)?,
sensitive,
rendered,
intent_digest: rendered
.then(|| CanonicalDigest::of(intent.desired()))
.transpose()
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.intent_digest"))?,
external_path_digest: self
.external_path_digest(intent.target())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.external_binding"))?,
backup_name,
backup_aad: current_artifact_aad(),
activated: false,
compensated: false,
native_restoration: None,
created_directories,
};
if let (Some(snapshot), Some(name)) = (&before, &marker.backup_name) {
let sealed = self
.seal_backup(&marker, &snapshot.bytes)
.map_err(|_| port(PortErrorCode::Crypto, "artifact.backup.seal"))?;
atomic_write(&self.restore_root.join(name), &sealed, 0o600, true)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.backup"))?;
}
self.save_marker(&marker)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.marker.prepare"))?;
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.backup.validate"))?;
if !marker.after_exists && !marker.before_exists {
return Ok(Self::effect(&marker));
}
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.stage"))?;
atomic_write(&stage, desired, marker.after_mode, marker.sensitive)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.stage.write"))?;
if marker.rendered && !marker.after_exists && marker.kind == OwnedEffectKind::AgentArtifact
{
untouched.insert(
(marker.operation_id.clone(), marker.effect_id.clone()),
CanonicalDigest::of(&marker)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.deletion.identity"))?,
);
}
Ok(Self::effect(&marker))
}
}
impl ManagedArtifactStore {
pub fn current_external_fingerprint(
&self,
target: &str,
) -> PortResult<Option<CanonicalDigest>> {
let path = self
.target_path(target)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.target"))?;
Ok(read_artifact(&path)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.fingerprint"))?
.map(|snapshot| snapshot.fingerprint))
}
pub fn apply_artifact(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
) -> PortResult<OwnedEffectV1> {
let desired = serde_json::to_vec(intent.desired())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.encode"))?;
self.apply_external_bytes(
operation_id,
intent,
&desired,
false,
intent.sensitive(),
true,
)
}
pub fn observe_artifact(
&self,
operation_id: &OperationId,
intent: &ExternalEffectIntentV1,
) -> PortResult<EffectReconciliation> {
let Some(marker) = self
.load_marker(operation_id, intent.effect_id())
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.marker.observe"))?
else {
if let Some(state) = self.observe_native_file_reference(operation_id, intent)? {
return Ok(state);
}
if let Some(state) = self.observe_unstaged_native_restoration(operation_id, intent)? {
return Ok(state);
}
return Ok(EffectReconciliation::Missing);
};
if marker.compensated {
return Ok(EffectReconciliation::Missing);
}
if marker.kind != intent.kind()
|| marker.target != intent.target()
|| marker.before_digest.as_ref() != intent.before_fingerprint()
|| marker.after_mode != intent.desired_mode()
|| (!marker.rendered && marker.sensitive != intent.sensitive())
{
return Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker)));
}
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.backup.validate"))?;
if marker.rendered {
if marker.intent_digest.as_ref()
!= Some(
&CanonicalDigest::of(intent.desired())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.intent_digest"))?,
)
{
return Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker)));
}
} else {
let desired = serde_json::to_vec(intent.desired())
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.encode"))?;
if artifact_fingerprint(&desired, intent.desired_mode())
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.intent_fingerprint"))?
!= marker.after_digest
{
return Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker)));
}
}
let target = self
.target_path(&marker.target)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.target"))?;
let current = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.observe"))?;
let current_digest = current
.as_ref()
.map(|snapshot| snapshot.fingerprint.clone());
if let Some(receipt) = &marker.native_restoration {
return Ok(
if marker.activated && current_digest == receipt.fingerprint {
EffectReconciliation::Applied(Self::effect(&marker))
} else {
EffectReconciliation::OwnershipLost(Self::effect(&marker))
},
);
}
if marker.activated
&& current_digest.as_ref() == marker.after_exists.then_some(&marker.after_digest)
{
Ok(EffectReconciliation::Applied(Self::effect(&marker)))
} else if marker.activated {
Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker)))
} else if current_digest.as_ref() == marker.after_exists.then_some(&marker.after_digest) {
// rename succeeded and marker persistence crashed; Activate can safely finalize it.
Ok(EffectReconciliation::Staged(Self::effect(&marker)))
} else if current_digest == marker.before_digest
|| (!marker.before_exists && current.is_none())
{
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.stage"))?;
match read_artifact(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.stage.observe"))?
{
Some(snapshot) if snapshot.fingerprint == marker.after_digest => {
Ok(EffectReconciliation::Staged(Self::effect(&marker)))
}
None => Ok(EffectReconciliation::Missing),
Some(_) => Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker))),
}
} else {
Ok(EffectReconciliation::OwnershipLost(Self::effect(&marker)))
}
}
pub fn activate_artifact(&self, effect: &OwnedEffectV1) -> PortResult<OwnedEffectV1> {
if self.authenticate_native_file_reference_effect(effect)? {
if self.current_external_fingerprint(&effect.target)? != effect.after_fingerprint {
return Err(port(PortErrorCode::Conflict, "native.reference.changed"));
}
return Ok(effect.clone());
}
let mut untouched = self
.untouched_deletions
.lock()
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.deletion.lock"))?;
let operation_id = effect
.compensation
.get("operation_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "artifact.activate.operation"))?;
let operation_id = OperationId::parse(operation_id)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.activate.operation"))?;
let effect_id = effect
.compensation
.get("effect_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "artifact.activate.effect"))?;
let mut marker = self
.load_marker(&operation_id, effect_id)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.marker"))?
.ok_or_else(|| port(PortErrorCode::NotFound, "artifact.activate.marker"))?;
if marker.compensated {
return Err(port(
PortErrorCode::Conflict,
"artifact.activate.compensated",
));
}
if marker.activated {
return Ok(Self::effect(&marker));
}
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.activate.backup"))?;
let target = self
.target_path(&marker.target)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.activate.target"))?;
let current = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.current"))?;
let current_digest = current
.as_ref()
.map(|snapshot| snapshot.fingerprint.clone());
if current_digest.as_ref() != marker.after_exists.then_some(&marker.after_digest) {
if current_digest != marker.before_digest
&& !(!marker.before_exists && current.is_none())
{
return Err(port(PortErrorCode::Conflict, "artifact.activate.ownership"));
}
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.activate.stage"))?;
let staged = read_artifact(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.stage"))?
.ok_or_else(|| port(PortErrorCode::NotFound, "artifact.activate.stage"))?;
if staged.fingerprint != marker.after_digest {
return Err(port(
PortErrorCode::Conflict,
"artifact.activate.stage_ownership",
));
}
// Clear before the first target mutation, including uncertain I/O failures.
untouched.remove(&(marker.operation_id.clone(), marker.effect_id.clone()));
if marker.after_exists {
#[cfg(windows)]
hiroute_platform::durable::rename_windows_sealed_file(&stage, &target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.rename"))?;
#[cfg(not(windows))]
fs::rename(&stage, &target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.rename"))?;
} else {
if current.is_some() {
fs::remove_file(&target).map_err(|_| {
port(PortErrorCode::Unavailable, "artifact.activate.remove")
})?;
}
fs::remove_file(&stage).map_err(|_| {
port(PortErrorCode::Unavailable, "artifact.activate.remove_stage")
})?;
}
sync_parent(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.sync"))?;
}
// Also consume proof when absence was already observed, before finalization.
untouched.remove(&(marker.operation_id.clone(), marker.effect_id.clone()));
let activated = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.verify"))?;
if activated.as_ref().map(|snapshot| &snapshot.fingerprint)
!= marker.after_exists.then_some(&marker.after_digest)
{
return Err(port(PortErrorCode::Corrupt, "artifact.activate.verify"));
}
// A replay may observe the intended absence before consuming the empty stage.
// Delete only our exact staged artifact, never a replacement at that path.
if !marker.after_exists {
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.activate.stage"))?;
if let Some(staged) = read_artifact(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.stage"))?
{
if staged.fingerprint != marker.after_digest {
return Err(port(
PortErrorCode::Conflict,
"artifact.activate.stage_ownership",
));
}
fs::remove_file(&stage).map_err(|_| {
port(PortErrorCode::Unavailable, "artifact.activate.remove_stage")
})?;
sync_parent(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.sync"))?;
}
}
marker.activated = true;
self.save_marker(&marker)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.activate.mark"))?;
Ok(Self::effect(&marker))
}
pub fn compensate_artifact(&self, effect: &OwnedEffectV1) -> PortResult<CompensationOutcome> {
let mut untouched = self
.untouched_deletions
.lock()
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.deletion.lock"))?;
// A semantic acknowledgment did not write the client file; it never authorizes undoing
// the user's cleanup, including recovery of a failed enclosing operation.
if effect.compensation["schema"] == native_restoration_ack::ACK_SCHEMA {
return Ok(CompensationOutcome::OwnershipLost);
}
if self.authenticate_native_file_reference_effect(effect)? {
return Ok(CompensationOutcome::AlreadyCompensated);
}
let operation_id = effect
.compensation
.get("operation_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "artifact.compensate.metadata"))?;
let operation_id = OperationId::parse(operation_id)
.map_err(|_| port(PortErrorCode::InvalidData, "artifact.compensate.operation"))?;
let effect_id = effect
.compensation
.get("effect_id")
.and_then(Value::as_str)
.ok_or_else(|| port(PortErrorCode::InvalidData, "artifact.compensate.effect"))?;
let mut marker = self
.load_marker(&operation_id, effect_id)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.marker"))?
.ok_or_else(|| port(PortErrorCode::NotFound, "artifact.compensate.marker"))?;
if marker.native_restoration.is_some() {
return Ok(CompensationOutcome::OwnershipLost);
}
if marker.compensated {
return Ok(CompensationOutcome::AlreadyCompensated);
}
self.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.compensate.backup"))?;
let target = self
.target_path(&marker.target)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.compensate.target"))?;
let current = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.read"))?;
let current_digest = current
.as_ref()
.map(|snapshot| snapshot.fingerprint.clone());
if !marker.activated {
let stage = self
.stage_path(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.compensate.stage"))?;
let staged = read_artifact(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.stage"))?;
let stage_present = staged.is_some();
let key = (marker.operation_id.clone(), marker.effect_id.clone());
let fresh_delete = marker.rendered
&& !marker.after_exists
&& marker.kind == OwnedEffectKind::AgentArtifact
&& untouched.get(&key)
== Some(&CanonicalDigest::of(&marker).map_err(|_| {
port(PortErrorCode::InvalidData, "artifact.deletion.identity")
})?);
if let Some(snapshot) = &staged
&& snapshot.fingerprint != marker.after_digest
{
return Ok(CompensationOutcome::OwnershipLost);
}
// An intact rendered stage proves rename has not happened. Discard only our
// stage and preserve a concurrent user edit; no target write needs undoing.
// Without the stage, a crash after rename remains uncertain and fails closed.
if !(marker.rendered && (marker.after_exists || fresh_delete) && stage_present)
&& current_digest != marker.before_digest
&& !(!marker.before_exists && current.is_none())
{
return Ok(CompensationOutcome::OwnershipLost);
}
if stage_present {
fs::remove_file(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.stage"))?;
sync_parent(&stage)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.sync"))?;
}
marker.compensated = true;
self.save_marker(&marker)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.mark"))?;
untouched.remove(&key);
return Ok(CompensationOutcome::Compensated);
}
if current_digest != marker.after_exists.then(|| marker.after_digest.clone()) {
if current_digest == marker.before_digest
|| (!marker.before_exists && current.is_none())
{
marker.compensated = true;
self.save_marker(&marker)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.mark"))?;
return Ok(CompensationOutcome::AlreadyCompensated);
}
return Ok(CompensationOutcome::OwnershipLost);
}
if marker.before_exists {
let before = self
.validated_backup(&marker)
.map_err(|_| port(PortErrorCode::Corrupt, "artifact.compensate.backup"))?
.ok_or_else(|| port(PortErrorCode::Corrupt, "artifact.compensate.backup"))?;
#[cfg(windows)]
hiroute_platform::durable::write_windows_atomic(
&target,
&before,
marker
.before_windows_permissions
.as_ref()
.ok_or_else(|| port(PortErrorCode::Corrupt, "artifact.native_permissions"))?,
)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.write"))?;
#[cfg(not(windows))]
atomic_write(
&target,
&before,
marker
.before_mode
.ok_or_else(|| port(PortErrorCode::Corrupt, "artifact.before_mode"))?,
false,
)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.write"))?;
} else if current.is_some() {
fs::remove_file(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.remove"))?;
sync_parent(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.sync"))?;
}
let restored = read_artifact(&target)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.verify"))?;
let restored_digest = restored
.as_ref()
.map(|snapshot| snapshot.fingerprint.clone());
if restored_digest != marker.before_digest && !(!marker.before_exists && restored.is_none())
{
return Err(port(PortErrorCode::Corrupt, "artifact.compensate.verify"));
}
marker.compensated = true;
self.save_marker(&marker)
.map_err(|_| port(PortErrorCode::Unavailable, "artifact.compensate.mark"))?;
Ok(CompensationOutcome::Compensated)
}
}
fn validate_external_target_location(path: &Path) -> Result<(), LocalStorageError> {
if !path.is_absolute()
|| path.parent().is_none()
|| path
.components()
.any(|component| matches!(component, Component::ParentDir | Component::CurDir))
{
return Err(LocalStorageError::InvalidData);
}
Ok(())
}
fn validate_external_target_path(path: &Path) -> Result<(), LocalStorageError> {
validate_external_target_location(path)?;
let parent = path.parent().ok_or(LocalStorageError::InvalidData)?;
native_directories::validate_parent(parent)?;
#[cfg(windows)]
match hiroute_platform::windows::security::open_identity(path, false) {
Ok(_held) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(error.into()),
}
match fs::symlink_metadata(path) {
Ok(metadata) => {
if metadata.file_type().is_symlink() || !metadata.file_type().is_file() {
return Err(LocalStorageError::Permission);
}
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
if metadata.nlink() != 1 {
return Err(LocalStorageError::Permission);
}
}
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(error.into()),
}
Ok(())
}
fn validate_owner_directory_metadata(metadata: &fs::Metadata) -> Result<(), LocalStorageError> {
if metadata.file_type().is_symlink() || !metadata.file_type().is_dir() {
return Err(LocalStorageError::Permission);
}
Ok(())
}
fn read_optional_regular_file(
path: &Path,
) -> Result<Option<Zeroizing<Vec<u8>>>, LocalStorageError> {
#[cfg(windows)]
{
let mut file = match hiroute_platform::windows::security::open_identity(path, false) {
Ok(file) => file,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => return Err(error.into()),
};
let mut bytes = Zeroizing::new(Vec::new());
file.read_to_end(&mut bytes)?;
return Ok(Some(bytes));
}
#[cfg(not(windows))]
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.file_type().is_file() => Ok(Some(Zeroizing::new(fs::read(path)?))),
Ok(_) => Err(LocalStorageError::InvalidData),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(None),
Err(error) => Err(error.into()),
}
}
struct ArtifactSnapshot {
bytes: Zeroizing<Vec<u8>>,
mode: u32,
fingerprint: CanonicalDigest,
windows_permissions: Option<hiroute_platform::file_security::WindowsPermissions>,
}
fn read_artifact(path: &Path) -> Result<Option<ArtifactSnapshot>, LocalStorageError> {
#[cfg(windows)]
{
return native_permissions::read_windows_artifact(path);
}
#[cfg(not(windows))]
{
let Some(bytes) = read_optional_regular_file(path)? else {
return Ok(None);
};
#[cfg(unix)]
let mode = {
use std::os::unix::fs::MetadataExt;
fs::metadata(path)?.mode() & 0o7777
};
#[cfg(not(unix))]
return Err(LocalStorageError::InvalidData);
if !supported_artifact_mode(mode) {
return Err(LocalStorageError::Permission);
}
let windows_permissions = None;
let fingerprint = artifact_fingerprint(&bytes, mode)?;
Ok(Some(ArtifactSnapshot {
bytes,
mode,
fingerprint,
windows_permissions,
}))
}
}
fn artifact_fingerprint(bytes: &[u8], mode: u32) -> Result<CanonicalDigest, LocalStorageError> {
if !supported_artifact_mode(mode) {
return Err(LocalStorageError::Permission);
}
#[cfg(windows)]
{
return windows_artifact_fingerprint(
bytes,
&hiroute_platform::file_security::private_defaults(mode & 0o200 == 0)?,
);
}
#[cfg(not(windows))]
CanonicalDigest::of(&json!({
"schema": "hiroute.posix-artifact-fingerprint/v1",
"content": CanonicalDigest::of_bytes(bytes),
"mode": mode,
}))
.map_err(|_| LocalStorageError::InvalidData)
}
const fn supported_artifact_mode(mode: u32) -> bool {
mode & !0o7777 == 0
}
fn artifact_backup_aad(marker: &ArtifactMarker) -> String {
let base = format!(
"hiroute.managed-artifact-backup/v2\0{}\0{}\0{}\0{}\0{}\0{}\0{}\0{}\0{}",
marker.restore_store_uuid,
marker.restore_key_id,
marker.operation_id,
marker.effect_id,
marker.target,
marker
.before_digest
.as_ref()
.map_or("absent", CanonicalDigest::as_str),
marker
.before_mode
.map_or_else(|| "absent".to_owned(), |mode| format!("{mode:o}")),
marker.after_mode,
marker.sensitive,
);
match marker.backup_aad {
ArtifactBackupAad::LegacyV2 => base,
ArtifactBackupAad::LegacyV3 => format!("{base}\0v3\0{}", marker.after_exists),
ArtifactBackupAad::CurrentV4 => format!("{base}\0v4\0{}", marker.after_exists),
ArtifactBackupAad::CurrentWindowsV5 => format!(
"{base}\0windows-v5\0{}\0{}\0{}",
marker.after_exists,
marker.after_digest,
CanonicalDigest::of(&json!({"before": marker.before_windows_permissions,
"after": marker.after_windows_permissions}))
.expect("permission facts are serializable")
),
}
}
fn load_or_create_restore_key(
path: &Path,
restore_root: &Path,
) -> Result<RestoreKeyMaterial, LocalStorageError> {
match fs::symlink_metadata(path) {
Ok(metadata) => {
validate_owner_regular_file(&metadata).map_err(|_| LocalStorageError::Locked)?;
let mut file = hiroute_platform::private_fs::open_private_file(path)?;
let mut header = [0_u8; 8];
file.read_exact(&mut header)?;
if &header != RESTORE_KEY_HEADER {
return Err(LocalStorageError::Locked);
}
let mut store_uuid = vec![0_u8; RESTORE_STORE_UUID_BYTES * 2];
let mut key_id = vec![0_u8; 71];
let mut bytes = Zeroizing::new(vec![0_u8; RESTORE_KEY_BYTES]);
file.read_exact(&mut store_uuid)?;
file.read_exact(&mut key_id)?;
file.read_exact(&mut bytes)?;
let mut trailing = [0_u8; 1];
if file.read(&mut trailing)? != 0 {
return Err(LocalStorageError::Locked);
}
let store_uuid =
String::from_utf8(store_uuid).map_err(|_| LocalStorageError::Locked)?;
let key_id = CanonicalDigest::parse(
String::from_utf8(key_id).map_err(|_| LocalStorageError::Locked)?,
)
.map_err(|_| LocalStorageError::Locked)?;
if restore_key_id(&bytes) != key_id {
return Err(LocalStorageError::Locked);
}
Ok(RestoreKeyMaterial {
bytes,
store_uuid,
key_id,
})
}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
if fs::read_dir(restore_root)?.next().is_some() {
return Err(LocalStorageError::Locked);
}
let mut bytes = Zeroizing::new(vec![0_u8; RESTORE_KEY_BYTES]);
let mut uuid = [0_u8; RESTORE_STORE_UUID_BYTES];
getrandom::fill(&mut bytes).map_err(|_| LocalStorageError::Crypto)?;
getrandom::fill(&mut uuid).map_err(|_| LocalStorageError::Crypto)?;
let store_uuid = hex_restore(&uuid);
let key_id = restore_key_id(&bytes);
let mut complete = Zeroizing::new(Vec::new());
complete.extend_from_slice(RESTORE_KEY_HEADER);
complete.extend_from_slice(store_uuid.as_bytes());
complete.extend_from_slice(key_id.as_str().as_bytes());
complete.extend_from_slice(&bytes);
hiroute_platform::durable::write_private_new(path, &complete)?;
validate_owner_regular_file(&fs::metadata(path)?)?;
Ok(RestoreKeyMaterial {
bytes,
store_uuid,
key_id,
})
}
Err(error) => Err(error.into()),
}
}
fn restore_key_id(bytes: &[u8]) -> CanonicalDigest {
let mut material = b"hiroute-restore-key-id-v1\0".to_vec();
material.extend_from_slice(bytes);
CanonicalDigest::of_bytes(&material)
}
fn hex_restore(bytes: &[u8]) -> String {
use std::fmt::Write as _;
let mut encoded = String::with_capacity(bytes.len() * 2);
for byte in bytes {
write!(&mut encoded, "{byte:02x}").expect("writing to String cannot fail");
}
encoded
}
fn validate_owner_regular_file(metadata: &fs::Metadata) -> Result<(), LocalStorageError> {
if metadata.file_type().is_symlink() || !metadata.file_type().is_file() {
return Err(LocalStorageError::Permission);
}
Ok(())
}
fn atomic_write(
path: &Path,
bytes: &[u8],
mode: u32,
sensitive: bool,
) -> Result<(), LocalStorageError> {
if !supported_artifact_mode(mode) || (sensitive && mode != 0o600) {
return Err(LocalStorageError::Permission);
}
#[cfg(windows)]
{
hiroute_platform::durable::write_windows_atomic(
path,
bytes,
&hiroute_platform::file_security::private_defaults(mode & 0o200 == 0)?,
)?;
return Ok(());
}
#[cfg(not(windows))]
{
let parent = path.parent().ok_or(LocalStorageError::InvalidData)?;
let parent_metadata = fs::symlink_metadata(parent)?;
if parent_metadata.file_type().is_symlink() || !parent_metadata.file_type().is_dir() {
return Err(LocalStorageError::Permission);
}
let temporary = path.with_extension("hiroute-tmp");
if temporary.exists() {
fs::remove_file(&temporary)?;
}
let mut options = OpenOptions::new();
options.write(true).create_new(true);
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt;
options.mode(0o600);
}
let mut file = options.open(&temporary)?;
file.write_all(bytes)?;
file.sync_all()?;
drop(file);
#[cfg(unix)]
{
use std::os::unix::fs::PermissionsExt;
fs::set_permissions(&temporary, fs::Permissions::from_mode(mode))?;
}
fs::rename(&temporary, path)?;
sync_parent(path)?;
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
if fs::metadata(path)?.mode() & 0o7777 != mode {
return Err(LocalStorageError::Permission);
}
}
Ok(())
}
}
fn sync_parent(path: &Path) -> Result<(), LocalStorageError> {
let parent = path.parent().ok_or(LocalStorageError::InvalidData)?;
hiroute_platform::durable::directory_barrier(parent)?;
Ok(())
}
mod delegation;
impl ExternalEffectPort for ManagedArtifactStore {
fn current_external_fingerprint(&self, target: &str) -> PortResult<Option<CanonicalDigest>> {
ManagedArtifactStore::current_external_fingerprint(self, target)
}
fn apply_external(
&self,
operation: &OperationV1,
intent: &ExternalEffectIntentV1,
) -> PortResult<OwnedEffectV1> {
self.apply_artifact(&operation.operation_id, intent)
}
fn observe_external(
&self,
operation: &OperationV1,
intent: &ExternalEffectIntentV1,
) -> PortResult<EffectReconciliation> {
self.observe_artifact(&operation.operation_id, intent)
}
fn activate_external(
&self,
_operation: &OperationV1,
effect: &OwnedEffectV1,
) -> PortResult<OwnedEffectV1> {
self.activate_artifact(effect)
}
fn compensate_external(
&self,
_operation: &OperationV1,
effect: &OwnedEffectV1,
) -> PortResult<CompensationOutcome> {
self.compensate_artifact(effect)
}
}