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
//! Sealed admission for command-specific typed planners.
//!
//! Application either reproduces a typed plan or seals a one-shot ordinary-publication
//! constructor that runs inside the writer. The production adapter may carry it to this coordinator, but cannot deserialize or
//! manufacture one. Admission therefore retains the exact generic ordering and the single
//! operation-journal writer boundary.
use hiroute_application_api::{
APPLY_COMPUTE_SAVE_OPERATION_V2, APPLY_SUBSCRIPTION_CHECK_OPERATION_V2, ApplyRequestV1,
CommandKind, command_by_id,
};
use hiroute_domain::{
BeginOperationOutcome, CanonicalDigest, IdempotencyScopeV1, OperationId, OperationV1,
ProtectedApplyCapability, RevisionSetV1, SecretMutationKind, TransactionPlanV1, WorkspaceId,
compare_revisions,
};
use super::{
AcceptedApply, TransactionCoordinator, TransactionError, VerifiedPrincipal,
apply_request_digest,
};
use crate::change::validate_feature_gate;
use crate::compute_management::ComputePreparedDiscoveryGuardV1;
/// One command-specific plan reproduced by an Application-owned typed planner.
///
/// Fields and constructors are crate-private, and this type intentionally implements neither
/// `Deserialize` nor `Clone`; an adapter can only move the exact value back to Application's
/// transaction coordinator.
pub struct PreparedTransactionV1 {
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: PreparedPlan,
operation_kind: String,
revalidate: Option<Box<dyn FnOnce() -> Result<(), TransactionError> + Send>>,
discovery_guards: Vec<ComputePreparedDiscoveryGuardV1>,
}
enum PreparedPlan {
Reproduced(Box<TransactionPlanV1>),
Publication(Box<dyn FnOnce() -> Result<TransactionPlanV1, TransactionError> + Send>),
}
impl PreparedTransactionV1 {
/// A composition owner may add a current-facts fence to a sealed plan. Existing checks
/// always run first; this cannot replace the planner's authority or recovery validation.
pub fn with_current_facts_check(
mut self,
check: impl FnOnce() -> Result<(), TransactionError> + Send + 'static,
) -> Self {
let previous = self.revalidate.take();
self.revalidate = Some(Box::new(move || {
if let Some(previous) = previous {
previous()?;
}
check()
}));
self
}
pub(crate) fn for_setup(
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
) -> Result<Self, TransactionError> {
if request.spec != *plan.spec() || !prepared_command_is_allowed(&request.spec.command_id) {
return Err(TransactionError::InvalidArguments);
}
let operation_kind = registered_apply_operation_kind(&request.spec.command_id)?;
Ok(Self {
request,
reproduced_digest,
plan: PreparedPlan::Reproduced(Box::new(plan)),
operation_kind,
revalidate: None,
discovery_guards: Vec::new(),
})
}
/// The registered restore descriptor has its own confirmation and idempotency scope.
/// Only an exact restore-only settings plan can use that authority.
pub(crate) fn for_agent_settings_restore(
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
) -> Result<Self, TransactionError> {
if !settings_restore_plan(plan.spec()) {
return Err(TransactionError::InvalidArguments);
}
let mut prepared = Self::for_setup(request, reproduced_digest, plan)?;
prepared.operation_kind = command_by_id("agents.restore.apply")
.filter(|descriptor| descriptor.kind == CommandKind::Apply)
.ok_or(TransactionError::InvalidArguments)?
.operation_id;
Ok(prepared)
}
/// The source-level management API has a distinct public operation identity while reusing
/// the registered compute connection command and its sealed transaction plan.
pub(crate) fn for_compute_management(
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
discovery_guards: Vec<ComputePreparedDiscoveryGuardV1>,
) -> Result<Self, TransactionError> {
if plan.spec().command_id != "compute.connection.apply" {
return Err(TransactionError::InvalidArguments);
}
let mut prepared = Self::for_setup(request, reproduced_digest, plan)?;
prepared.operation_kind = APPLY_COMPUTE_SAVE_OPERATION_V2.to_owned();
prepared.discovery_guards = discovery_guards;
Ok(prepared)
}
/// Operation A has its own authority and durable identity. Its plan contains only the safe
/// candidate/evidence binding; the protected native source is resolved by the adapter after
/// this Operation has been durably admitted.
pub(crate) fn for_subscription_check(
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
) -> Result<Self, TransactionError> {
if request.spec != *plan.spec()
|| request.spec.command_id != hiroute_domain::COMPUTE_SUBSCRIPTION_CHECK_COMMAND_ID_V2
{
return Err(TransactionError::InvalidArguments);
}
Ok(Self {
request,
reproduced_digest,
plan: PreparedPlan::Reproduced(Box::new(plan)),
operation_kind: APPLY_SUBSCRIPTION_CHECK_OPERATION_V2.to_owned(),
revalidate: None,
discovery_guards: Vec::new(),
})
}
pub(crate) fn for_worker_dependency_selection(
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
) -> Result<Self, TransactionError> {
if request.spec != *plan.spec()
|| request.spec.command_id != "worker.dependencies.select"
|| plan.worker_dependency_selection().is_none()
|| !request.expected_revisions.dependencies.is_empty()
{
return Err(TransactionError::InvalidArguments);
}
Ok(Self {
request,
reproduced_digest,
plan: PreparedPlan::Reproduced(Box::new(plan)),
operation_kind: hiroute_application_api::WORKER_DEPENDENCIES_SELECT_OPERATION_V1
.to_owned(),
revalidate: None,
discovery_guards: Vec::new(),
})
}
pub(crate) fn for_plan_content(
request: ApplyRequestV1,
build: impl FnOnce() -> Result<TransactionPlanV1, TransactionError> + Send + 'static,
) -> Result<Self, TransactionError> {
if request.spec.command_id != "routing.apply"
|| request
.spec
.desired_state
.get("schema")
.and_then(serde_json::Value::as_str)
!= Some(hiroute_application_api::PLAN_CONTENT_CHANGE_SCHEMA_V2)
{
return Err(TransactionError::InvalidArguments);
}
Ok(Self {
reproduced_digest: request.accept_digest.clone(),
request,
plan: PreparedPlan::Publication(Box::new(build)),
operation_kind: "ApplyAgentPlanChange".into(),
revalidate: None,
discovery_guards: Vec::new(),
})
}
/// Application-owned typed fact reproduction, executed only inside the writer boundary.
/// The durable plan carries effect identities; this callback is admission-only.
pub(crate) fn with_revalidation(
mut self,
check: impl FnOnce() -> Result<(), TransactionError> + Send + 'static,
) -> Self {
self.revalidate = Some(Box::new(check));
self
}
}
fn prepared_command_is_allowed(command_id: &str) -> bool {
matches!(
command_id,
"agents.config-permissions.apply"
| "compute.connection.apply"
| "compute.credential.add"
| "routing.apply"
| "agents.connect.apply"
| "prices.override.apply"
| "agents.settings.apply"
)
}
fn registered_apply_operation_kind(command_id: &str) -> Result<String, TransactionError> {
// V2 settings use the existing connect descriptor/confirmation authority; their internal
// journal command remains explicit so legacy V1 payloads cannot be reinterpreted.
let descriptor_id = if command_id == "agents.settings.apply" {
"agents.connect.apply"
} else {
command_id
};
command_by_id(descriptor_id)
.filter(|descriptor| descriptor.kind == CommandKind::Apply)
.map(|descriptor| descriptor.operation_id)
.filter(|operation_kind| !operation_kind.is_empty())
.ok_or(TransactionError::InvalidArguments)
}
fn settings_restore_plan(spec: &hiroute_domain::ChangeSpecV1) -> bool {
spec.command_id == "agents.settings.apply"
&& serde_json::from_value::<hiroute_domain::AgentSettingsSpecV2>(spec.desired_state.clone())
.is_ok_and(|settings| {
settings.schema_version == hiroute_domain::AGENT_SETTINGS_SCHEMA_V2
&& spec.resource_id.as_deref() == Some(settings.context_id.as_str())
&& settings.is_restore_only()
})
}
impl<'a, C, S, R, E, I> TransactionCoordinator<'a, C, S, R, E, I>
where
C: hiroute_domain::ControlRepositoryPort
+ hiroute_domain::ComputeSourceControlPort
+ hiroute_domain::CredentialPoolControlPort
+ crate::ConnectionOptionAuthorizationPort,
S: hiroute_domain::SecretStorePort,
R: hiroute_domain::RuntimeStatePort,
E: hiroute_domain::ExternalEffectPort,
I: crate::ProtectedInputPort,
{
/// Admits one setup step produced by a sealed typed planner, then leaves execution to the
/// same fixed six-step journal used by every other Application mutation.
pub fn accept_prepared(
&self,
workspace: &WorkspaceId,
principal: &VerifiedPrincipal,
prepared: PreparedTransactionV1,
) -> Result<AcceptedApply, TransactionError> {
let PreparedTransactionV1 {
request,
reproduced_digest,
plan,
operation_kind,
revalidate,
discovery_guards,
} = prepared;
let plan = match plan {
PreparedPlan::Publication(build) => {
if revalidate.is_some()
|| !discovery_guards.is_empty()
|| operation_kind != "ApplyAgentPlanChange"
|| request.spec.command_id != "routing.apply"
{
return Err(TransactionError::InvalidArguments);
}
return self.accept_with_reproduced_plan(
workspace,
principal,
&operation_kind,
request,
move |_current, _request| {
let plan = build()?;
self.validate_prepared_external(&plan)?;
Ok((reproduced_digest, plan))
},
);
}
PreparedPlan::Reproduced(plan) => *plan,
};
let worker_dependency_selection = plan.worker_dependency_selection().cloned();
let kind_matches = if worker_dependency_selection.is_some() {
operation_kind == hiroute_application_api::WORKER_DEPENDENCIES_SELECT_OPERATION_V1
&& plan.spec().command_id == "worker.dependencies.select"
} else if plan.spec().command_id == hiroute_domain::COMPUTE_SUBSCRIPTION_CHECK_COMMAND_ID_V2
{
operation_kind == APPLY_SUBSCRIPTION_CHECK_OPERATION_V2
} else if settings_restore_plan(plan.spec()) {
// The internal settings command is shared, but restore-only plans must never
// reach the journal through Change authority, including internal callers.
operation_kind == "ApplyAgentConnectionRestore"
} else {
(registered_apply_operation_kind(&request.spec.command_id)? == operation_kind)
|| (operation_kind == APPLY_COMPUTE_SAVE_OPERATION_V2
&& plan.spec().command_id == "compute.connection.apply")
};
if !kind_matches {
return Err(TransactionError::InvalidArguments);
}
if let Some(change) = worker_dependency_selection {
return self.accept_worker_dependency_selection(
workspace,
principal,
request,
reproduced_digest,
plan,
change,
revalidate,
);
}
self.accept_with_reproduced_plan(
workspace,
principal,
&operation_kind,
request,
move |_current, _request| {
if matches!(
plan.spec().command_id.as_str(),
"routing.apply" | "agents.connect.apply" | "agents.settings.apply"
) {
revalidate.ok_or(TransactionError::ChangePreviewStale)?()?;
} else if let Some(check) = revalidate {
check()?;
}
for guard in discovery_guards {
self.protected_inputs
.validate_discovery_evidence(&guard.input_slot, &guard.evidence_digest)
.map_err(|_| TransactionError::ChangePreviewStale)?;
if !guard.materializes_secret {
continue;
}
let mutation = plan
.secrets()
.iter()
.find(|mutation| {
mutation.kind() == SecretMutationKind::Upsert
&& mutation.input_slot() == Some(guard.input_slot.as_str())
})
.ok_or(TransactionError::ChangePreviewStale)?;
let secret = self
.protected_inputs
.read_secret(&guard.input_slot)
.map_err(|_| TransactionError::ChangePreviewStale)?;
let observed = self.secrets.fingerprint(&secret)?;
if mutation.fingerprint() != Some(&observed) {
return Err(TransactionError::ChangePreviewStale);
}
}
self.validate_prepared_external(&plan)?;
Ok((reproduced_digest, plan))
},
)
}
fn validate_prepared_external(&self, plan: &TransactionPlanV1) -> Result<(), TransactionError> {
for intent in plan.external() {
self.external.validate_external_admission(intent)?;
if self
.external
.current_external_fingerprint(intent.target())?
!= intent.before_fingerprint().cloned()
{
return Err(TransactionError::ChangePreviewStale);
}
}
Ok(())
}
#[allow(clippy::too_many_arguments)]
fn accept_worker_dependency_selection(
&self,
workspace: &WorkspaceId,
principal: &VerifiedPrincipal,
request: ApplyRequestV1,
reproduced_digest: CanonicalDigest,
plan: TransactionPlanV1,
change: hiroute_domain::WorkerDependencySelectionChangeV1,
revalidate: Option<Box<dyn FnOnce() -> Result<(), TransactionError> + Send>>,
) -> Result<AcceptedApply, TransactionError> {
let _writer = self.admission.lock_writer()?;
if !self
.admission
.writes_open
.load(std::sync::atomic::Ordering::Acquire)
{
return Err(TransactionError::RecoveryRequired);
}
if hiroute_domain::CHANGE_SPEC_SCHEMA_V1
.negotiate(request.schema_version)
.is_none()
|| !principal.local_control
|| request.apply_capability.is_some()
|| !request.expected_revisions.dependencies.is_empty()
|| request.expected_revisions.target != change.before_revision
{
return Err(TransactionError::InvalidArguments);
}
let operation_kind = hiroute_application_api::WORKER_DEPENDENCIES_SELECT_OPERATION_V1;
let scope = IdempotencyScopeV1::new(
principal.scope.clone(),
operation_kind,
request.idempotency_key.clone(),
)?;
let request_digest = apply_request_digest(&request)?;
if let Some(existing) = self.control.operation_for_idempotency(workspace, &scope)? {
if existing.accepted_digest == request.accept_digest {
return Ok(AcceptedApply {
operation: existing,
existing: true,
});
}
return Err(TransactionError::IdempotencyKeyReused);
}
let current_revision = self
.control
.worker_dependency_selection_revision(workspace, change.after_selection.harness)?;
if current_revision != change.before_revision {
return Err(TransactionError::RevisionConflict(
hiroute_domain::RevisionMismatch::Target,
));
}
if let Some(check) = revalidate {
check()?;
}
if reproduced_digest != request.accept_digest
|| plan.spec() != &request.spec
|| plan.worker_dependency_selection() != Some(&change)
{
return Err(TransactionError::ChangePreviewStale);
}
let operation_id = OperationId::derive(workspace, &scope, &request_digest);
let operation = OperationV1::new(
operation_id,
workspace.clone(),
scope,
request_digest,
request.accept_digest,
request.expected_revisions,
plan,
)?;
match self
.control
.begin_local_operation(&operation)
.map_err(|error| {
if error.code == hiroute_domain::PortErrorCode::Conflict {
TransactionError::ChangePreviewStale
} else {
TransactionError::Port(error)
}
})? {
BeginOperationOutcome::Created => Ok(AcceptedApply {
operation,
existing: false,
}),
BeginOperationOutcome::ExistingSame(existing) => Ok(AcceptedApply {
operation: *existing,
existing: true,
}),
BeginOperationOutcome::ExistingDifferent => Err(TransactionError::IdempotencyKeyReused),
BeginOperationOutcome::RevisionChanged(mismatch) => {
Err(TransactionError::RevisionConflict(mismatch))
}
}
}
pub(super) fn accept_with_reproduced_plan<F>(
&self,
workspace: &WorkspaceId,
principal: &VerifiedPrincipal,
operation_kind: &str,
request: ApplyRequestV1,
reproduce: F,
) -> Result<AcceptedApply, TransactionError>
where
F: FnOnce(
&RevisionSetV1,
&ApplyRequestV1,
) -> Result<(CanonicalDigest, TransactionPlanV1), TransactionError>,
{
let _writer = self.admission.lock_writer()?;
if !self
.admission
.writes_open
.load(std::sync::atomic::Ordering::Acquire)
{
return Err(TransactionError::RecoveryRequired);
}
if hiroute_domain::CHANGE_SPEC_SCHEMA_V1
.negotiate(request.schema_version)
.is_none()
|| operation_kind.is_empty()
{
return Err(TransactionError::InvalidArguments);
}
let scope = IdempotencyScopeV1::new(
principal.scope.clone(),
operation_kind,
request.idempotency_key.clone(),
)?;
let request_digest = apply_request_digest(&request)?;
if let Some(existing) = self.control.operation_for_idempotency(workspace, &scope)? {
if existing.accepted_digest == request.accept_digest {
return Ok(AcceptedApply {
operation: existing,
existing: true,
});
}
return Err(TransactionError::IdempotencyKeyReused);
}
// Routing changes have already passed their strict draft/content/lifecycle planner.
// A REST classifier endpoint is a typed, validated routing field, not an arbitrary
// effect URL from the generic setup command.
if !matches!(
request.spec.command_id.as_str(),
"routing.apply" | "decision.services.apply"
) {
validate_feature_gate(&request.spec.desired_state)?;
}
let current = self.control.current_revisions(workspace)?;
compare_revisions(&request.expected_revisions, ¤t)
.map_err(TransactionError::RevisionConflict)?;
let authorization = if principal.local_control {
if request.apply_capability.is_some() {
return Err(TransactionError::InvalidArguments);
}
None
} else {
let capability = request
.apply_capability
.clone()
.ok_or(TransactionError::CapabilityDenied)
.and_then(|value| {
ProtectedApplyCapability::new(value)
.map_err(|_| TransactionError::CapabilityDenied)
})?;
Some(
self.control
.verify_apply_authorization(
&capability,
workspace,
&principal.scope,
&scope.operation_kind,
&request.accept_digest,
&request.expected_revisions,
)
.map_err(|error| {
if error.code == hiroute_domain::PortErrorCode::PermissionDenied {
TransactionError::CapabilityDenied
} else {
TransactionError::Port(error)
}
})?,
)
};
let (reproduced_digest, plan) = reproduce(¤t, &request)?;
if reproduced_digest != request.accept_digest || plan.spec() != &request.spec {
return Err(TransactionError::ChangePreviewStale);
}
let operation_id = OperationId::derive(workspace, &scope, &request_digest);
let operation = OperationV1::new(
operation_id,
workspace.clone(),
scope,
request_digest,
request.accept_digest,
request.expected_revisions,
plan,
)?;
// Another accepted Operation can hold the durable claim between accept and run.
// This atomic admission failed without consuming this capability or creating a row.
// Keep this conversion here: post-admission effect failures retain recovery semantics.
let admission = (if principal.local_control {
self.control.begin_local_operation(&operation)
} else {
self.control.begin_operation(
&operation,
authorization.as_ref().expect("protected authorization"),
)
})
.map_err(|error| {
if error.code == hiroute_domain::PortErrorCode::Conflict {
TransactionError::ChangePreviewStale
} else {
TransactionError::Port(error)
}
})?;
match admission {
BeginOperationOutcome::Created => Ok(AcceptedApply {
operation,
existing: false,
}),
BeginOperationOutcome::ExistingSame(existing) => Ok(AcceptedApply {
operation: *existing,
existing: true,
}),
BeginOperationOutcome::ExistingDifferent => Err(TransactionError::IdempotencyKeyReused),
BeginOperationOutcome::RevisionChanged(mismatch) => {
Err(TransactionError::RevisionConflict(mismatch))
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn prepared_agent_connection_uses_registered_operation_kind() {
for command in ["agents.connect.apply", "agents.settings.apply"] {
assert_eq!(
registered_apply_operation_kind(command).unwrap(),
"ApplyAgentConnectionChange"
);
}
}
#[test]
fn prepared_kind_resolution_fails_closed() {
assert!(registered_apply_operation_kind("agents.connect.preview").is_err());
assert!(registered_apply_operation_kind("unregistered.apply").is_err());
}
}