// Durable phase of one authority canister's restore fence.
type AuthorityRestoreFencePhase = variant { Open; Sealed };
// Current durable authority snapshot/restore-fence state.
type AuthorityRestoreFenceStatusResponse = record {
history_total_num_changes : opt nat64;
authority_canister : principal;
operation_id : opt blob;
phase : AuthorityRestoreFencePhase;
changed_at_ns : opt nat64;
};
// Controller-selected identity for one authority snapshot operation.
type AuthoritySnapshotRequest = record { operation_id : blob };
type BootstrapStatusResponse = record {
last_error : opt text;
phase : text;
ready : bool;
};
type CanicMetadataResponse = record {
package_description : text;
canister_version : nat64;
canic_version : text;
package_version : text;
package_name : text;
};
//
// ComponentChildFundingPolicy
//
// Compiled child-level funding limits without configuration-only deserializers.
//
type ComponentChildFundingPolicy = record {
max_per_child : nat;
max_per_request : nat;
cooldown_secs : nat64;
};
//
// ComponentChildKind
//
// Lifecycle class for a managed Component child at any tree depth.
//
type ComponentChildKind = variant { instance; shard; replica; singleton };
//
// ComponentChildSpec
//
// One canonically ordered role permitted anywhere below a Component.
//
type ComponentChildSpec = record {
kind : ComponentChildKind;
role : text;
cycles_funding : ComponentChildFundingPolicy;
};
// Canonical compiled App authority required to validate provisioning without source TOML.
type ComponentDeploymentConfiguration = record {
fleet_service_topology : FleetServiceTopology;
deployment_topology : ComponentGroupDeploymentTopology;
component_group_topology : ComponentGroupTopology;
component_topology : ComponentTopology;
};
// One bounded inert metadata label on a flattened Component occurrence.
type ComponentDeploymentLabel = record { key : text; value : text };
// Fully effective quotas inherited by every placement of one member occurrence.
type ComponentDeploymentLimits = record {
maximum_descendants : nat32;
maximum_registry_bytes : nat64;
spawn_grant_reductions : vec ComponentDeploymentSpawnGrantLimit;
};
// Canonical reduction-only declaration for one exact flattened member.
type ComponentDeploymentMemberLimit = record {
maximum_descendants : opt nat32;
member : vec text;
maximum_registry_bytes : opt nat64;
spawn_grants : vec ComponentDeploymentSpawnGrantLimit;
};
// Exact typed purpose resolved for one flattened deployment occurrence.
type ComponentDeploymentPurpose = variant {
FleetServiceMember : record {
"service" : text;
member_purpose : FleetServiceMemberPurpose;
};
Ordinary;
};
// Canonical reduced ceiling for one exact Component Spec spawn grant.
type ComponentDeploymentSpawnGrantLimit = record {
child_role : text;
maximum_instances_per_parent : nat32;
parent_role : text;
};
// One canonical independently scalable Component Group selection.
type ComponentGroupDeploymentSpec = record {
members : vec FlattenedComponentGroupDeploymentMember;
initial_placements : nat32;
member_limits : vec ComponentDeploymentMemberLimit;
placement : ComponentGroupPlacementPolicy;
component_group : text;
deployment : text;
labels : vec ComponentDeploymentLabel;
service_purpose : opt FleetServiceMemberPurpose;
maximum_placements : nat32;
};
// Canonical independent Component Group deployments in raw deployment-ID order.
type ComponentGroupDeploymentTopology = record {
component_group_deployments : vec ComponentGroupDeploymentSpec;
};
// Typed declaration kind for one flattened Component Group leaf.
type ComponentGroupLeafKind = variant {
FleetService : record { "service" : text };
Ordinary;
};
// One direct declaration member; included groups remain configuration-only edges.
type ComponentGroupMember = variant {
Group : record {
member : text;
component_group : text;
labels : vec ComponentDeploymentLabel;
service_purpose : opt FleetServiceMemberPurpose;
};
Component : record {
member : text;
kind : ComponentGroupLeafKind;
labels : vec ComponentDeploymentLabel;
service_purpose : opt FleetServiceMemberPurpose;
component_spec : text;
};
};
// Durable Fleet-scoped identity of one materialized Component Group deployment copy.
type ComponentGroupPlacementId = record { deployment : text; ordinal : nat32 };
// One materialized copy of a completely flattened Component Group.
type ComponentGroupPlacementPlan = record {
component_group : text;
entries : vec ComponentGroupPlanEntry;
group_placement : ComponentGroupPlacementId;
};
// Protected density and spread envelope before concrete roots are selected.
type ComponentGroupPlacementPolicy = record {
maximum_per_root : nat32;
minimum_distinct_roots : nat32;
};
// One exact top-level Component occurrence within a group placement.
type ComponentGroupPlanEntry = record {
labels : vec ComponentDeploymentLabel;
member_path : vec text;
component_spec : text;
spec_hash : blob;
purpose : ComponentDeploymentPurpose;
limits : ComponentDeploymentLimits;
};
// One canonical Component Group declaration.
type ComponentGroupSpec = record {
members : vec ComponentGroupMember;
component_group : text;
};
// Canonical checked-in Component Group declaration graph.
type ComponentGroupTopology = record {
component_groups : vec ComponentGroupSpec;
};
//
// ComponentLimits
//
// Explicit aggregate quotas compiled for every concrete instance of one Spec.
//
type ComponentLimits = record {
maximum_descendants : nat32;
maximum_registry_bytes : nat64;
cycles_funding : CyclesFundingBudget;
};
//
// ComponentProvisioningGrant
//
// Non-parent authorization for one requester Spec to create one exact peer Spec.
//
type ComponentProvisioningGrant = record {
requester_component_spec : text;
maximum_instances_per_requester_per_root : nat32;
target_component_spec : text;
};
//
// ComponentSpawnGrant
//
// One explicit parent-role capability to create one direct child role.
//
type ComponentSpawnGrant = record {
child_role : text;
maximum_instances_per_parent : nat32;
// Exact configured sharding/scaling children created before the parent may become ready.
initial_instances_per_parent : nat32;
parent_role : text;
};
//
// ComponentSpec
//
// One compiled Component role, immutable Spec hash, limits, and child-role catalog.
//
type ComponentSpec = record {
children : vec ComponentChildSpec;
component_role : text;
component_spec : text;
spec_hash : blob;
spawn_grants : vec ComponentSpawnGrant;
limits : ComponentLimits;
maximum_fleet_instances : nat32;
};
//
// ComponentSpecAdmission
//
// Immutable permission and concrete-instance ceiling for one Spec on one Fleet Subnet Root.
//
type ComponentSpecAdmission = record {
maximum_root_instances : nat32;
component_spec : text;
spec_hash : blob;
};
//
// ComponentTopology
//
// Canonically ordered Fleet Component admissions and flat potential child-role catalogs.
//
type ComponentTopology = record {
provisioning_grants : vec ComponentProvisioningGrant;
component_specs : vec ComponentSpec;
};
// Closed controller command union for the Fleet Coordinator.
type CoordinatorCommand = variant {
JoinRoot : FleetSubnetRootJoinRequest;
StageFundingPolicyRotationRoot : FleetFundingPolicyRotationStageRootRequest;
ActivateRegistry : FleetRegistryActivationRequest;
SetRootFunding : SetCyclesFundingRequest;
AcknowledgeRootSnapshot : FleetSubnetRootSnapshotAcknowledgementRequest;
Retire : FleetRetirementRequest;
RequestRootFunding : FleetRootFundingRequest;
BeginFundingPolicyRotation : FleetFundingPolicyRotationBeginRequest;
ApplyFundingPolicyRotation : FleetFundingPolicyRotationApplyRequest;
PrepareRootDeletionExecution : FleetSubnetRootDeletionExecutionRequest;
ResumeAuthoritySnapshot : AuthoritySnapshotRequest;
MutateAdmission : FleetAdmissionMutationRequest;
ProvisionComponents : FleetComponentProvisioningPrepareRequest;
RemoveRoot : FleetSubnetRootDrainingReservationRequest;
CompleteRootDeletion : FleetSubnetRootDeletionCompletionRequest;
PrepareAuthoritySnapshot : AuthoritySnapshotRequest;
};
// Closed correlated success union for Fleet Coordinator commands.
type CoordinatorCommandResponse = variant {
JoinRoot : FleetSubnetRootJoinResponse;
ActivateRegistry : FleetRegistryActivationResponse;
SetRootFunding : SetStateResponse;
AcknowledgeRootSnapshot : FleetSubnetRootSnapshotAcknowledgement;
Retire : FleetRetirementStatus;
RequestRootFunding : FleetRootFundingResponse;
PrepareRootDeletionExecution : FleetSubnetRootDeletionExecutionResponse;
ResumeAuthoritySnapshot : AuthorityRestoreFenceStatusResponse;
MutateAdmission : FleetAdmissionMutationResponse;
OperationAccepted : OperationReceipt;
CompleteRootDeletion : FleetSubnetRootDeletionResponse;
PrepareAuthoritySnapshot : AuthorityRestoreFenceStatusResponse;
};
// Controller-only Coordinator treasury policy, headroom and per-Root usage.
type CoordinatorFundingStatusResponse = record {
rotation : opt FleetFundingPolicyRotationStatusResponse;
funding_enabled : bool;
automatic_grants : nat32;
current_cycles : nat;
fleet_window : opt CoordinatorFundingWindowStatusResponse;
rotation_checkpoint_root_count : nat32;
historical_automatic_grants : nat64;
funding_profile : opt FleetFundingProfile;
policy_generation : nat64;
automatic_cycles : nat;
rotation_checkpoint_count : nat32;
historical_automatic_cycles : nat;
roots : vec CoordinatorRootFundingStatusResponse;
coordinator : principal;
policy : opt FleetCoordinatorRootFundingPolicy;
rotation_checkpoint_root_capacity_remaining : nat32;
};
// Current spent and reserved cycles in one exact epoch-anchored funding window.
type CoordinatorFundingWindowStatusResponse = record {
spent_cycles : nat;
window_start_secs : nat64;
reserved_cycles : nat;
};
type CoordinatorOperationReadRequest = variant { Operation : OperationReceipt };
type CoordinatorOperationReadResponse = variant {
Operation : CoordinatorOperationStatusResponse;
};
// Coordinator-owned durable operation detail selected by one operation ID.
type CoordinatorOperationStatusResponse = variant {
Admission : FleetAdmissionOperationStatusResponse;
FundingPolicyRotation : FleetFundingPolicyRotationStatusResponse;
RootRemoval : CoordinatorRootRemovalOperationStatus;
Retirement : FleetRetirementStatus;
ComponentProvisioning : FleetComponentProvisioningStatusResponse;
};
type CoordinatorRegistryReadRequest = variant { Registry };
type CoordinatorRegistryReadResponse = variant { Registry : FleetRegistry };
// Controller-only funding usage and operation state for one registered Root.
type CoordinatorRootFundingStatusResponse = record {
automatic_grants : nat32;
window : CoordinatorFundingWindowStatusResponse;
last_result : opt FleetRootFundingResponse;
historical_automatic_grants : nat64;
last_successful_grant_at_ns : opt nat64;
automatic_cycles : nat;
policy_hash : blob;
fleet_subnet_root : principal;
current_operation : opt FleetRootFundingRequest;
historical_automatic_cycles : nat;
lifecycle_status : FleetSubnetRootStatus;
policy : FleetSubnetRootFundingPolicy;
};
// Coordinator-owned progress across the existing durable root-removal boundaries.
type CoordinatorRootRemovalOperationStatus = record {
completion : opt FleetSubnetRootDeletionResponse;
readiness_intent : opt FleetSubnetRootDeletionReadinessIntentResponse;
operation_id : blob;
draining : opt FleetSubnetRootDrainingPublicationResponse;
reservation : FleetSubnetRootDrainingReservationResponse;
execution : opt FleetSubnetRootDeletionExecutionResponse;
removal : opt FleetSubnetRootRemovalPublicationResponse;
readiness : opt FleetSubnetRootDeletionReadinessResponse;
};
//
// CyclesFundingBudget
//
// Positive aggregate cycles-funding ceiling applied over one bounded window.
//
type CyclesFundingBudget = record { window_secs : nat64; maximum_cycles : nat };
//
// Error
//
// Public API error payload. Only registered runtime reasons may originate a
// value; Candid/Serde decoding may still preserve any raw `u16`.
//
type Error = record { code : nat16 };
// One exact flattened Component occurrence within an independent deployment.
type FlattenedComponentGroupDeploymentMember = record {
labels : vec ComponentDeploymentLabel;
component_spec_hash : blob;
member_path : vec text;
component_spec : text;
purpose : ComponentDeploymentPurpose;
limits : ComponentDeploymentLimits;
};
// One closed Fleet-admission membership action.
type FleetAdmissionMutationAction = variant { Add; Remove };
// Public semantic outcome of one accepted request.
type FleetAdmissionMutationOutcome = variant {
CatalogChanged;
AlreadyPresent;
Planned;
AlreadyAbsent;
Converged;
};
// One exact controller-authorized Fleet-admission mutation.
type FleetAdmissionMutationRequest = record {
"principal" : principal;
action : FleetAdmissionMutationAction;
participant_catalog_digest : blob;
operation_id : blob;
expected_policy_digest : blob;
expected_generation : nat64;
successor_policy_digest : blob;
selector : FleetAdmissionSelector;
authority : FleetCoordinatorBinding;
participant_count : nat32;
};
// Exact accepted mutation result, including idempotent outcomes.
type FleetAdmissionMutationResponse = record {
policy_digest : blob;
generation : nat64;
operation_id : blob;
outcome : FleetAdmissionMutationOutcome;
};
// Durable state of one current or retained Coordinator admission operation.
type FleetAdmissionOperationPhase = variant {
Opening : record { successor : FleetAdmissionPolicyStatus };
Releasing : record { successor : FleetAdmissionPolicyStatus };
PerimeterFenced : record { successor : FleetAdmissionPolicyStatus };
Planned : record { successor : FleetAdmissionPolicyStatus };
Activating : record { successor : FleetAdmissionPolicyStatus };
Preparing : record { successor : FleetAdmissionPolicyStatus };
Completed : FleetAdmissionMutationResponse;
};
// Protected operation detail selected by exact operation identity.
type FleetAdmissionOperationStatusResponse = record {
"principal" : principal;
action : FleetAdmissionMutationAction;
operation_id : blob;
selector : FleetAdmissionSelector;
phase : FleetAdmissionOperationPhase;
};
// One exact Coordinator-owned Fleet admission policy.
type FleetAdmissionPolicy = record {
policy_digest : blob;
fleet : FleetBinding;
generation : nat64;
schema_version : nat16;
fleet_principals : vec principal;
rules : vec FleetAdmissionRule;
};
// Compact current or successor policy identity and bounded counts.
type FleetAdmissionPolicyStatus = record {
policy_digest : blob;
generation : nat64;
fleet_principal_count : nat16;
narrower_rule_count : nat16;
narrower_principal_reference_count : nat16;
};
// One canonical narrower admission rule.
type FleetAdmissionRule = record {
selector : FleetAdmissionSelector;
principals : vec principal;
};
// Exact policy scope selected by protected input or a controller mutation.
type FleetAdmissionSelector = variant {
fleet;
component_instance : text;
fleet_subnet_root : principal;
component_spec : text;
};
// Protected selector and page requested from the current active policy.
type FleetAdmissionStatusRequest = record {
page : PageRequest;
selector : FleetAdmissionSelector;
};
// Controller-only current policy, bounded membership page and replay state.
type FleetAdmissionStatusResponse = record {
fleet : FleetBinding;
active : FleetAdmissionPolicyStatus;
last_result : opt FleetAdmissionOperationStatusResponse;
selector : FleetAdmissionSelector;
principals : Page;
current_operation : opt FleetAdmissionOperationStatusResponse;
maximum_page_size : nat16;
};
//
// FleetBinding
//
// Immutable binding between one installed Fleet and its source App.
//
type FleetBinding = record { app : text; fleet : FleetKey };
// Exact root-local runtime-activation cursor copied from passive Coordinator status.
type FleetComponentActivationRootProgress = record {
activated_component_count : nat32;
root_runtime_active : bool;
fleet_subnet_root : principal;
component_count : nat32;
};
// Fresh-install or monotonic scale-out scope covered by one plan.
type FleetComponentProvisioningOperation = variant {
FreshInstall;
ScaleOut : record {
deployment : text;
requested_placements : nat32;
previous_placements : nat32;
};
};
// Durable Coordinator progress exposed without returning the complete plan.
type FleetComponentProvisioningPhase = variant {
ComponentsProvisioned;
RootsAccepted;
ConfirmingDirectories;
Planned;
ActivatingRuntimes;
AcceptingRoots;
ServiceTopologyPublished;
RuntimesActivated;
DirectoriesConfirmed;
ProvisioningRoots;
};
// Complete canonical provisioning authority retained before any root effect.
type FleetComponentProvisioningPlan = record {
fleet_registry : FleetRegistryVersion;
fleet : FleetBinding;
directory_confirmation_roots : vec principal;
operation : FleetComponentProvisioningOperation;
batches : vec FleetSubnetRootProvisioningBatch;
configuration_digest : blob;
};
// Controller-authenticated command that durably freezes one complete plan.
type FleetComponentProvisioningPrepareRequest = record {
plan : FleetComponentProvisioningPlan;
operation_id : blob;
};
// Exact Coordinator step whose current Root call most recently failed.
type FleetComponentProvisioningRetryStage = variant {
RootAcceptance;
RootProvisioning;
DirectoryConfirmation;
RuntimeActivation;
};
// Bounded typed diagnostic retained for the Root call that remains retryable.
type FleetComponentProvisioningRootFailure = record {
origin : opt ProvisioningFailureOrigin;
stage : FleetComponentProvisioningRetryStage;
fleet_subnet_root : principal;
failed_at_ns : nat64;
diagnostic_code : nat16;
};
// Exact root-local cursor copied from passive Coordinator status before one advance.
type FleetComponentProvisioningRootProgress = record {
claimed_component_count : nat32;
installed_component_count : nat32;
fleet_subnet_root : principal;
reserved_component_count : nat32;
registry_committed_component_count : nat32;
component_count : nat32;
};
// Compact exact status for one Coordinator-owned provisioning operation.
type FleetComponentProvisioningStatusResponse = record {
runtime_activated_root_count : nat32;
fleet_registry : FleetRegistryVersion;
current_synchronization : opt FleetComponentSynchronizationRootProgress;
components_provisioned_at_ns : opt nat64;
directory_confirmed_root_count : nat32;
provisioned_root_count : nat32;
directories_confirmed_at_ns : opt nat64;
plan_hash : blob;
current_activation : opt FleetComponentActivationRootProgress;
group_placement_count : nat32;
pending_root_failure : opt FleetComponentProvisioningRootFailure;
provisioning_in_flight_root : opt principal;
service_topology_published_at_ns : opt nat64;
planned_at_ns : nat64;
operation_id : blob;
runtimes_activated_at_ns : opt nat64;
acceptance_in_flight_root : opt principal;
roots_accepted_at_ns : opt nat64;
published_fleet_registry : opt FleetRegistryVersion;
operation : FleetComponentProvisioningOperation;
accepted_root_count : nat32;
current_root : opt FleetComponentProvisioningRootProgress;
estate_funding_required : opt RootEstateFundingRequired;
current_publication : opt FleetComponentPublicationRootProgress;
phase : FleetComponentProvisioningPhase;
root_batch_count : nat32;
activation_in_flight_root : opt principal;
directory_confirmation_root_count : nat32;
configuration_digest : blob;
component_count : nat32;
publication_in_flight_root : opt principal;
};
// Exact root-local Directory cursor copied from passive Coordinator status.
type FleetComponentPublicationRootProgress = record {
published_component_count : nat32;
fleet_subnet_root : principal;
component_count : nat32;
};
//
// FleetComponentSpecEntry
//
// Fleet-wide immutable Component Spec declaration projected into the Registry.
//
type FleetComponentSpecEntry = record {
component_role : text;
component_spec : text;
spec_hash : blob;
maximum_fleet_instances : nat32;
};
// Exact affected-service synchronization cursor copied from passive Coordinator status.
type FleetComponentSynchronizationRootProgress = record {
affected_component_count : nat32;
synchronized_component_count : nat32;
complete : bool;
fleet_subnet_root : principal;
};
//
// FleetCoordinatorBinding
//
// Immutable identity and exact physical placement of one Fleet Coordinator.
//
type FleetCoordinatorBinding = record {
fleet : FleetBinding;
coordinator_subnet : principal;
coordinator : principal;
};
//
// FleetCoordinatorInitArgs
//
// Exact authority and compiled provisioning configuration installed into a fresh Coordinator.
//
type FleetCoordinatorInitArgs = record {
root_funding : opt FleetCoordinatorRootFundingPolicy;
admission : FleetAdmissionPolicy;
component_deployment_configuration : ComponentDeploymentConfiguration;
authority : FleetRegistryAuthority;
configured_app : text;
};
//
// FleetCoordinatorRootFundingPolicy
//
// Immutable Fleet-wide reserve and grant-budget authority installed into one Coordinator.
//
type FleetCoordinatorRootFundingPolicy = record {
maximum_automatic_cycles : nat;
minimum_reserve_cycles : nat;
funding_profile : FleetFundingProfile;
maximum_automatic_grants : nat32;
budget : CyclesFundingBudget;
};
// Start or exactly resume the fully staged rotation operation.
type FleetFundingPolicyRotationApplyRequest = record {
plan_digest : blob;
operation_id : blob;
expected_predecessor_generation : nat64;
};
// Begin staging one accepted no-effect rotation plan.
type FleetFundingPolicyRotationBeginRequest = record {
plan_digest : blob;
operation_id : blob;
header : FleetFundingPolicyRotationPlanHeader;
};
// Sole future value source authorized by a funding-policy rotation.
type FleetFundingPolicyRotationFundingSource = variant { CoordinatorTreasury };
// Exact protected physical-placement evidence reviewed for one rotation.
type FleetFundingPolicyRotationPlacementEvidence = record {
node_count : nat64;
cost_multiplier_numerator : nat64;
acknowledge_fiduciary_cost : bool;
cost_multiplier_denominator : nat64;
subnet : principal;
fiduciary : bool;
};
// Immutable header of one no-effect operator-reviewed rotation plan.
type FleetFundingPolicyRotationPlanHeader = record {
topology_catalog_digest : blob;
funding_source : FleetFundingPolicyRotationFundingSource;
predecessor_coordinator_policy_hash : blob;
apply_operator_debit : nat;
maximum_new_automatic_cycles : nat;
coordinator_placement : FleetFundingPolicyRotationPlacementEvidence;
successor_generation : nat64;
predecessor_usage : FleetFundingPolicyUsage;
proposed_coordinator_policy : FleetCoordinatorRootFundingPolicy;
affected_root_count : nat32;
predecessor_generation : nat64;
predecessor_registry : FleetRegistryVersion;
roots_digest : blob;
};
// Terminal Coordinator receipt for a converged policy generation.
type FleetFundingPolicyRotationReceipt = record {
successor_registry : FleetRegistryVersion;
plan_digest : blob;
completed_at_ns : nat64;
successor_policy_set_hash : blob;
retained_historical_automatic_grants : nat64;
operation_id : blob;
apply_operator_debit : nat;
maximum_new_automatic_cycles : nat;
successor_generation : nat64;
retained_historical_automatic_cycles : nat;
affected_root_count : nat32;
predecessor_generation : nat64;
predecessor_registry : FleetRegistryVersion;
};
// Exact current and proposed authority for one affected Root.
type FleetFundingPolicyRotationRootPlan = record {
proposed_policy : FleetSubnetRootFundingPolicy;
placement : FleetFundingPolicyRotationPlacementEvidence;
fleet_subnet_root : principal;
predecessor_usage : FleetFundingPolicyUsage;
predecessor_policy_hash : blob;
};
// Stage one digest-bound Root policy beneath the current rotation.
type FleetFundingPolicyRotationStageRootRequest = record {
plan_digest : blob;
root : FleetFundingPolicyRotationRootPlan;
operation_id : blob;
};
// Protected durable phase of one Coordinator-owned policy rotation.
type FleetFundingPolicyRotationStatusPhase = variant {
PreparingRoots : record {
expected_root_count : nat32;
prepared_root_count : nat32;
};
ActivatingRoots : record {
successor_registry : FleetRegistryVersion;
activated_root_count : nat32;
expected_root_count : nat32;
};
Completed : FleetFundingPolicyRotationReceipt;
Staging : record { expected_root_count : nat32; staged_root_count : nat32 };
};
// Controller-only status of one exact current or terminal rotation.
type FleetFundingPolicyRotationStatusResponse = record {
plan_digest : blob;
operation_id : blob;
successor_generation : nat64;
phase : FleetFundingPolicyRotationStatusPhase;
predecessor_generation : nat64;
};
// Current-generation and retained predecessor automatic-funding usage.
type FleetFundingPolicyUsage = record {
generation_automatic_cycles : nat;
historical_automatic_grants : nat64;
generation_automatic_grants : nat32;
historical_automatic_cycles : nat;
};
// Protected physical-topology class that selects the minimum Root funding baseline.
type FleetFundingProfile = variant {
multi_subnet;
preview_multi_subnet;
single_subnet;
};
//
// FleetKey
//
// Complete network-qualified Fleet identity.
//
type FleetKey = record { fleet_id : text; canonical_network_id : text };
// Exact default-account transfer retained before a Fleet retirement Ledger call.
type FleetLedgerTransferIntent = record {
fee : nat;
destination : principal;
source : principal;
memo : blob;
balance_before : nat;
created_at_time : nat64;
};
// Verified retirement transfer; an initially empty account has no Ledger block.
type FleetLedgerTransferReceipt = record {
block_index : opt nat;
intent : FleetLedgerTransferIntent;
};
//
// FleetRegistry
//
// Complete canonical Fleet Registry snapshot distributed by one Coordinator.
//
type FleetRegistry = record {
fleet_subnet_roots : vec FleetSubnetRootEntry;
component_specs : vec FleetComponentSpecEntry;
admission : FleetAdmissionPolicy;
authority : FleetRegistryAuthority;
revision : nat64;
services : vec FleetServiceBinding;
};
//
// FleetRegistryActivationRequest
//
// Controller compare-and-commit command for the complete acknowledged `Joining` root set.
//
type FleetRegistryActivationRequest = record {
expected_registry : FleetRegistryVersion;
};
//
// FleetRegistryActivationResponse
//
// Durable response authority for one atomic all-`Active` Registry transition.
//
type FleetRegistryActivationResponse = record {
version : FleetRegistryVersion;
previous_version : FleetRegistryVersion;
};
//
// FleetRegistryAuthority
//
// Exact Coordinator binding and reinstall-local authority epoch for one Fleet Registry.
//
type FleetRegistryAuthority = record {
epoch : nat64;
binding : FleetCoordinatorBinding;
};
//
// FleetRegistryManifest
//
// Compact current-head evidence for one complete canonical Registry snapshot.
//
type FleetRegistryManifest = record {
content_hash : blob;
byte_length : nat64;
authority : FleetRegistryAuthority;
revision : nat64;
};
//
// FleetRegistryVersion
//
// Compact immutable identity used by mirrors, acknowledgements, and journals.
//
type FleetRegistryVersion = record {
content_hash : blob;
authority : FleetRegistryAuthority;
revision : nat64;
};
// Controller authority for returning a fully removed Fleet's Ledger balance.
type FleetRetirementRequest = record {
destination : principal;
maximum_ledger_fee : nat;
operation_id : blob;
expected_registry : FleetRegistryVersion;
};
// Coordinator retirement progress retained until the operator deletes the Coordinator.
type FleetRetirementStatus = record {
request : FleetRetirementRequest;
prepared_at_ns : nat64;
ledger_receipt : opt FleetLedgerTransferReceipt;
ledger_transfer : opt FleetLedgerTransferIntent;
};
// Root-authored exact receipt for one fresh or replayed grant acceptance.
type FleetRootFundingAcceptanceReceipt = record {
request : FleetRootFundingAcceptanceRequest;
accepted_at_ns : nat64;
fleet_subnet_root : principal;
coordinator : principal;
};
// Coordinator-authored exact same-Root acceptance request carrying cycles.
type FleetRootFundingAcceptanceRequest = record {
operation_sequence : nat64;
granted_cycles : nat;
operation_id : blob;
policy_hash : blob;
observed_balance : nat;
expected_registry : FleetRegistryVersion;
};
// Terminal reason that one authenticated request transferred no cycles.
type FleetRootFundingNoGrantReason = variant {
RootWindowExhausted;
FundingDisabled;
FleetAutomaticCapExhausted;
CooldownActive;
RootRejected;
RootAutomaticCapExhausted;
RootIneligible;
RegistryStale;
InvalidRequest;
FleetWindowExhausted;
CoordinatorReserveUnavailable;
PolicyMismatch;
};
// Durable exact zero-transfer result for one Root operation.
type FleetRootFundingNoGrantReceipt = record {
decided_at_ns : nat64;
request : FleetRootFundingRequest;
reason : FleetRootFundingNoGrantReason;
};
// Root-authored request for one exact Coordinator operating-cycle decision.
type FleetRootFundingRequest = record {
operation_sequence : nat64;
operation_id : blob;
policy_hash : blob;
observed_balance : nat;
requested_cycles : nat;
expected_registry : FleetRegistryVersion;
};
// Exact terminal outcome returned to the authenticated requesting Root.
type FleetRootFundingResponse = variant {
NoGrant : FleetRootFundingNoGrantReceipt;
Granted : FleetRootFundingAcceptanceReceipt;
};
// Complete configured member set for one logical Fleet service.
//
// This is topology intent only. It deliberately carries no health, readiness,
// replication progress, promotion, consistency or load-balancer eligibility.
type FleetServiceBinding = record {
"service" : text;
members : vec FleetServiceComponentBinding;
placement : FleetServicePlacementPolicy;
mode : FleetServiceMode;
role : text;
component_spec : text;
};
// One exact configured Component member of a published Fleet service.
type FleetServiceComponentBinding = record {
component : text;
canister_id : principal;
member_path : vec text;
member_purpose : FleetServiceMemberPurpose;
fleet_subnet_root : principal;
group_placement : ComponentGroupPlacementId;
};
// Exact semantic purpose assigned to one Fleet-service Component occurrence.
type FleetServiceMemberPurpose = variant { replica; authority; pool_member };
// Published service mode after configuration-only Authority selectors have been resolved.
type FleetServiceMode = variant { AuthorityReplica; ActivePool };
// Service-wide density and spread envelope independent of deployment placement.
type FleetServicePlacementPolicy = record {
minimum_distinct_roots : nat32;
maximum_members_per_root : nat32;
};
// One canonical logical Fleet-service target.
type FleetServiceTarget = record {
"service" : text;
placement : FleetServicePlacementPolicy;
mode : FleetServiceTargetMode;
role : text;
component_spec : text;
};
// Mode-specific target contract before concrete service members exist.
type FleetServiceTargetMode = variant {
AuthorityReplica : record {
authority_deployment : text;
authority_member : vec text;
};
ActivePool;
};
// Canonical Fleet-service targets in raw service-ID order.
type FleetServiceTopology = record { targets : vec FleetServiceTarget };
//
// FleetSubnetCanisterPoolConfig
//
// Immutable prepaid empty-Canister inventory policy for one Fleet Subnet Root.
//
type FleetSubnetCanisterPoolConfig = record {
// Ceiling for standby and operator-imported pool assets.
//
// Recycled assets remain tracked even when their return temporarily exceeds this target.
maximum_size : nat32;
// Native cycles retained above the Ready floor while a newly created asset is
// created, inspected, controller-checked, and admitted to the pool.
creation_execution_margin : nat;
// Ready empty Canisters automatically maintained for the root.
minimum_size : nat32;
// Minimum retained balance required before a pool asset becomes Ready.
canister_cycles : nat;
};
//
// FleetSubnetRootAutomaticIcpRefillPolicy
//
// Optional emergency trigger and target subordinate to one root's ICP-refill policy.
//
type FleetSubnetRootAutomaticIcpRefillPolicy = record {
maximum_automatic_refills : nat32;
target_balance : nat;
maximum_automatic_refill_e8s : nat64;
emergency_threshold : nat;
};
//
// FleetSubnetRootBinding
//
// Complete immutable identity, placement, admissions, and limits of one Fleet Subnet Root.
//
type FleetSubnetRootBinding = record {
placement_subnet : principal;
component_topology_digest : blob;
fleet_subnet_root : principal;
authority : FleetRegistryAuthority;
component_admissions : vec ComponentSpecAdmission;
limits : FleetSubnetRootLimits;
funding : FleetSubnetRootFundingAuthority;
};
// Controller request confirming typed root absence under one durable execution intent.
type FleetSubnetRootDeletionCompletionRequest = record {
operation_id : blob;
observed_absent_at_ns : nat64;
fleet_subnet_root : principal;
expected_execution_hash : blob;
};
// Controller command freezing independently observed root authority before stop/delete.
type FleetSubnetRootDeletionExecutionRequest = record {
observed_controllers : vec principal;
observed_reserved_cycles : nat;
observed_freezing_threshold_seconds : nat;
operation_id : blob;
observed_cycles_after_reclamation : nat;
fleet_subnet_root : principal;
observed_module_hash : blob;
expected_readiness_hash : blob;
observed_idle_cycles_burned_per_day : nat;
};
// Durable Coordinator intent binding one authenticated external root-deletion executor.
type FleetSubnetRootDeletionExecutionResponse = record {
execution_hash : blob;
request : FleetSubnetRootDeletionExecutionRequest;
prepared_at_ns : nat64;
executor : principal;
};
// Root-authenticated command freezing its pre-transfer physical-deletion readiness authority.
type FleetSubnetRootDeletionReadinessIntentRequest = record {
retained_cycles_target : nat;
observed_cycles_before_reclamation : nat;
observed_reserved_cycles : nat;
observed_freezing_threshold_seconds : nat;
prepared_at_ns : nat64;
operation_id : blob;
store_deletion_hash : blob;
final_inventory_hash : blob;
fleet_subnet_root : principal;
observed_idle_cycles_burned_per_day : nat;
};
// Coordinator receipt proving root-deletion readiness intent is durable before cycle transfer.
type FleetSubnetRootDeletionReadinessIntentResponse = record {
request : FleetSubnetRootDeletionReadinessIntentRequest;
recorded_at_ns : nat64;
intent_hash : blob;
coordinator : principal;
};
// Root-authenticated command recording its converged post-transfer cycle balance.
type FleetSubnetRootDeletionReadinessRequest = record {
expected_intent_hash : blob;
ledger_receipt : FleetLedgerTransferReceipt;
operation_id : blob;
observed_cycles_after_reclamation : nat;
fleet_subnet_root : principal;
cycles_reclaimed_at_ns : nat64;
};
// Coordinator receipt proving one removed root is ready for an external executor.
type FleetSubnetRootDeletionReadinessResponse = record {
retained_cycles_target : nat;
observed_cycles_before_reclamation : nat;
readiness_hash : blob;
observed_reserved_cycles : nat;
observed_freezing_threshold_seconds : nat;
request : FleetSubnetRootDeletionReadinessRequest;
prepared_at_ns : nat64;
recorded_at_ns : nat64;
store_deletion_hash : blob;
final_inventory_hash : blob;
coordinator : principal;
observed_idle_cycles_burned_per_day : nat;
};
// Terminal Coordinator receipt for externally observed Fleet Subnet Root absence.
type FleetSubnetRootDeletionResponse = record {
readiness_hash : blob;
execution_hash : blob;
observed_controllers : vec principal;
completed_at_ns : nat64;
operation_id : blob;
deletion_hash : blob;
observed_absent_at_ns : nat64;
observed_cycles_after_reclamation : nat;
fleet_subnet_root : principal;
executor : principal;
observed_module_hash : blob;
coordinator : principal;
};
//
// FleetSubnetRootDrainingPublicationResponse
//
// Durable response authority for one root's canonical `Active -> Draining` transition.
//
type FleetSubnetRootDrainingPublicationResponse = record {
root_draining : FleetSubnetRootDrainingResponse;
version : FleetRegistryVersion;
previous_version : FleetRegistryVersion;
};
//
// FleetSubnetRootDrainingReservationRequest
//
// Controller command serializing one root's Fleet-wide draining decision against placement.
//
type FleetSubnetRootDrainingReservationRequest = record {
asset_recipient : principal;
operation_id : blob;
expected_root : FleetSubnetRootEntry;
expected_registry : FleetRegistryVersion;
};
//
// FleetSubnetRootDrainingReservationResponse
//
// Durable Coordinator authority that must precede the target root's local draining fence.
//
type FleetSubnetRootDrainingReservationResponse = record {
reservation_hash : blob;
request : FleetSubnetRootDrainingReservationRequest;
prepared_at_ns : nat64;
coordinator : principal;
};
//
// FleetSubnetRootDrainingResponse
//
// Durable root-local admission cutoff and exact active authority frozen at that boundary.
//
type FleetSubnetRootDrainingResponse = record {
placement_subnet : principal;
reservation_hash : blob;
next_allocation_sequence : nat64;
component_topology_digest : blob;
started_at_ns : nat64;
known_created_component_canisters : nat32;
committed_component_instances : nat32;
operation_id : blob;
managed_descendants : nat32;
reserved_component_instances : nat32;
active_release_set : FleetSubnetRootReleaseSet;
root_registry_encoded_bytes : nat64;
active_registry : FleetRegistryVersion;
fleet_subnet_root : principal;
};
//
// FleetSubnetRootEntry
//
// One Fleet Subnet Root's immutable placement and admission facts plus lifecycle state.
//
type FleetSubnetRootEntry = record {
placement_subnet : principal;
status : FleetSubnetRootStatus;
component_topology_digest : blob;
active_release_set : FleetSubnetRootReleaseSet;
fleet_subnet_root : principal;
component_admissions : vec ComponentSpecAdmission;
limits : FleetSubnetRootLimits;
funding : FleetSubnetRootFundingAuthority;
};
//
// FleetSubnetRootFinalInventoryResponse
//
// Exact terminal Component history and retained write-fenced Store authority.
//
type FleetSubnetRootFinalInventoryResponse = record {
placement_subnet : principal;
next_allocation_sequence : nat64;
component_topology_digest : blob;
wasm_store_release_count : nat32;
removed_component_instances : nat32;
wasm_store_gc_prepared_at_secs : nat64;
wasm_store : principal;
operation_id : blob;
terminal_component_history_hash : blob;
wasm_store_catalog_entries : nat32;
active_release_set : FleetSubnetRootReleaseSet;
root_registry_encoded_bytes : nat64;
fleet_subnet_root : principal;
wasm_store_template_count : nat32;
finalized_at_ns : nat64;
registry : FleetRegistryVersion;
inventory_hash : blob;
wasm_store_catalog_hash : blob;
wasm_store_occupied_bytes : nat64;
};
//
// FleetSubnetRootFundingAuthority
//
// Complete immutable Coordinator-grant and optional ICP-refill policy for one root.
//
type FleetSubnetRootFundingAuthority = record {
root_funding : FleetSubnetRootFundingPolicy;
icp_refill : opt FleetSubnetRootIcpRefillPolicy;
};
//
// FleetSubnetRootFundingPolicy
//
// Immutable Coordinator-grant thresholds and budget for one registered root.
//
type FleetSubnetRootFundingPolicy = record {
maximum_automatic_cycles : nat;
funding_profile : FleetFundingProfile;
target_balance : nat;
request_threshold : nat;
maximum_automatic_grants : nat32;
budget : CyclesFundingBudget;
cooldown_secs : nat64;
};
//
// FleetSubnetRootIcpRefillPolicy
//
// Immutable root-owned ICP conversion budget, balance floor, and system-Canister authority.
//
type FleetSubnetRootIcpRefillPolicy = record {
cmc_canister_id : opt principal;
minimum_icp_balance_e8s : nat64;
allow_ic_system_canister_overrides : bool;
automatic : opt FleetSubnetRootAutomaticIcpRefillPolicy;
window_secs : nat64;
min_xdr_permyriad_per_icp : opt nat64;
ledger_canister_id : opt principal;
max_refill_e8s_per_call : nat64;
maximum_refill_e8s : nat64;
};
//
// FleetSubnetRootJoinRequest
//
// Controller command that compare-and-commits one exact root as Registry `Joining`.
//
type FleetSubnetRootJoinRequest = record {
entry : FleetSubnetRootEntry;
expected_registry : FleetRegistryVersion;
};
//
// FleetSubnetRootJoinResponse
//
// Durable response receipt for one exact root's original `Joining` commit.
//
type FleetSubnetRootJoinResponse = record {
entry : FleetSubnetRootEntry;
version : FleetRegistryVersion;
};
//
// FleetSubnetRootLimits
//
// Immutable aggregate policy ceilings for one Fleet Subnet Root.
//
type FleetSubnetRootLimits = record {
maximum_registry_bytes : nat64;
// Maximum accepted or committed Component Group placements on this root.
maximum_group_placements : nat32;
maximum_wasm_store_bytes : nat64;
maximum_component_instances : nat32;
canister_pool : FleetSubnetCanisterPoolConfig;
cycles_funding : CyclesFundingBudget;
};
// One selected root's complete canonical provisioning batch.
type FleetSubnetRootProvisioningBatch = record {
placements : vec ComponentGroupPlacementPlan;
root : FleetSubnetRootBinding;
active_release_set : FleetSubnetRootReleaseSet;
};
//
// FleetSubnetRootReleaseSet
//
// Exact release-build and manifest identity admitted for one Fleet Subnet Root.
//
type FleetSubnetRootReleaseSet = record {
manifest_digest : blob;
release_build_id : text;
};
//
// FleetSubnetRootRemovalPublicationResponse
//
// Durable response authority for one root's canonical `Draining -> Removed` transition.
//
type FleetSubnetRootRemovalPublicationResponse = record {
final_inventory : FleetSubnetRootFinalInventoryResponse;
version : FleetRegistryVersion;
previous_version : FleetRegistryVersion;
};
//
// FleetSubnetRootSnapshotAcknowledgement
//
// Durable Coordinator receipt proving which root acknowledged which version.
//
type FleetSubnetRootSnapshotAcknowledgement = record {
version : FleetRegistryVersion;
fleet_subnet_root : principal;
};
//
// FleetSubnetRootSnapshotAcknowledgementRequest
//
// Root-authenticated acknowledgement of one exact durably staged snapshot.
//
type FleetSubnetRootSnapshotAcknowledgementRequest = record {
version : FleetRegistryVersion;
};
//
// FleetSubnetRootStatus
//
// Lifecycle state of one Fleet Subnet Root in the Fleet Registry snapshot.
//
type FleetSubnetRootStatus = variant { Joining; Draining; Active; Removed };
type ObservabilityRequest = variant {
RootAcknowledgements;
Admission : FleetAdmissionStatusRequest;
RegistryManifest;
Funding;
AuthorityRestore;
RegistryVersion;
};
type ObservabilityResponse = variant {
RootAcknowledgements : vec FleetSubnetRootSnapshotAcknowledgement;
Admission : FleetAdmissionStatusResponse;
RegistryManifest : FleetRegistryManifest;
Funding : CoordinatorFundingStatusResponse;
AuthorityRestore : AuthorityRestoreFenceStatusResponse;
RegistryVersion : FleetRegistryVersion;
};
// Durable identity returned when one role-owned asynchronous command is accepted.
type OperationReceipt = record { operation_id : blob };
type Page = record { total : nat64; entries : vec principal };
type PageRequest = record { offset : nat64; limit : nat64 };
// Protected origin carried through outer provisioning stages without public error expansion.
type ProvisioningFailureOrigin = record {
retry_category : ProvisioningRetryCategory;
operation_id : blob;
stage : ProvisioningFailureStage;
target : principal;
failed_at_ns : nat64;
diagnostic_code : nat16;
};
// Exact owner stage of the latest provisioning failure.
type ProvisioningFailureStage = variant {
ComponentRuntime;
RootActivation;
ComponentMembership;
StoreCatalog;
ComponentChildAllocation;
ComponentAllocation;
StoreStatus;
CoordinatorStatus;
ComponentOrigin;
StoreActivation;
StoreIdentity;
RootPreparation;
Provisioning;
StoreCredential;
ComponentCommit;
};
// Whether another active attempt is justified by the originating failure.
type ProvisioningRetryCategory = variant { ReviewRequired; Backoff };
// Local identity and responsiveness without diagnostic checks or Fleet readiness.
type PublicHealth = record {
role : opt text;
observed_at_ns : nat64;
canister_id : principal;
health : PublicHealthStatus;
};
// Public query responsiveness; no runtime diagnostics or Fleet readiness assessment.
type PublicHealthStatus = variant { responding };
type PublicStatusRequest = variant { Overview; Health };
type PublicStatusResponse = variant {
Overview : RoleOverviewResponse;
Health : PublicHealth;
};
type Result = variant { Ok : CoordinatorCommandResponse; Err : Error };
type Result_1 = variant { Ok : CoordinatorOperationReadResponse; Err : Error };
type Result_2 = variant { Ok : CoordinatorRegistryReadResponse; Err : Error };
type Result_3 = variant { Ok : ObservabilityResponse; Err : Error };
type Result_4 = variant { Ok : PublicStatusResponse; Err : Error };
// Closed compiled capability identity exposed by the immutable role overview.
type RoleCapability = variant {
Sharding;
Scaling;
Root;
FleetCoordinator;
Index;
Icrc21;
ChildProvisioning;
DelegatedTokenIssuer;
FleetAdmissionProjection;
RootDelegation;
RoleAttestationSigner;
WasmStore;
DelegatedTokenVerifier;
RoleAttestationVerifier;
RootControlPlane;
Runtime;
AutomaticTopup;
};
// Immutable role, capability, release, and bootstrap profile-verification response.
type RoleOverviewResponse = record {
capabilities : vec RoleCapability;
metadata : CanicMetadataResponse;
role : text;
bootstrap : BootstrapStatusResponse;
protocol_profile_digest : blob;
};
// Exact durable funding pause for one Root-owned autonomous pool creation.
type RootEstateFundingRequired = record {
retry_at_ns : nat64;
root : principal;
creation_amount : nat;
readiness_floor : nat;
operation_id : blob;
attempt_count : nat32;
available : nat;
shortfall : nat;
ledger_fee : nat;
required : nat;
execution_margin : nat;
management_creation_fee : nat;
last_attempt_at_ns : opt nat64;
cycles_ledger : principal;
};
// Explicit input for changing automatic cycles funding.
type SetCyclesFundingRequest = record { enabled : bool };
type SetStateResponse = record {
previous : bool;
current : bool;
changed : bool;
};
service : (FleetCoordinatorInitArgs) -> {
canic_coordinator_command : (CoordinatorCommand) -> (Result);
canic_coordinator_operation_status : (CoordinatorOperationReadRequest) -> (
Result_1,
) query;
canic_coordinator_registry : (CoordinatorRegistryReadRequest) -> (
Result_2,
) query;
canic_observability : (ObservabilityRequest) -> (Result_3) query;
canic_public_status : (PublicStatusRequest) -> (Result_4) query;
}