feat: add restore and migration network ledgers

go
codex 2 weeks ago
parent e6bb6723a3
commit 25b386f02b

@ -8,7 +8,7 @@ use App\Services\Config;
/** Initializes only the clean-break PHP business and Agent log schemas. */
final class CloudSetup
{
private const SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity';
private const SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers';
private const MAIN_TABLES = [
'cloud_regions', 'cloud_traffic_pool_groups',
'cloud_network_lines', 'cloud_resource_pools',
@ -34,8 +34,10 @@ final class CloudSetup
'cloud_platform_test_policy_rules', 'cloud_instance_snapshots',
'cloud_backup_subscriptions', 'cloud_backup_period_entitlements',
'cloud_instance_backups', 'cloud_deployment_snapshots',
'cloud_backup_restores', 'cloud_backup_recoveries',
'cloud_instance_migrations', 'cloud_peer_migration_artifacts',
'cloud_backup_restores', 'cloud_backup_restore_attempts',
'cloud_backup_recoveries', 'cloud_instance_migrations',
'cloud_instance_migration_source_debts',
'cloud_peer_migration_artifacts',
'cloud_instance_runtime', 'cloud_orders', 'cloud_order_items',
'cloud_resource_reservations', 'cloud_resource_reservation_ips',
'cloud_public_network_transitions',
@ -286,6 +288,16 @@ final class CloudSetup
'new_uuid', 'new_name', 'state', 'error_code', 'ready_at',
'created_at', 'updated_at',
],
'cloud_backup_restore_attempts' => [
'id', 'attempt_key', 'backup_restore_id', 'generation',
'operation_id', 'job_id', 'reservation_id', 'target_host_id',
'target_uuid', 'target_name', 'target_network_attachment_id',
'target_identity_json', 'target_identity_sha256',
'target_claim_set_sha256', 'target_public_network_json',
'target_public_network_sha256', 'state', 'effect_resolution',
'active_attempt', 'last_error_code', 'effect_resolved_at',
'terminal_at', 'created_at', 'updated_at',
],
'cloud_backup_recoveries' => [
'id', 'recovery_key', 'backup_id', 'instance_id', 'job_id',
'operation_id', 'state', 'error_code', 'completed_at',
@ -312,6 +324,16 @@ final class CloudSetup
'source_service_status', 'source_network_status', 'error_code',
'cutover_at', 'completed_at', 'created_at', 'updated_at',
],
'cloud_instance_migration_source_debts' => [
'id', 'debt_key', 'migration_id', 'source_reservation_id',
'source_host_id', 'source_uuid',
'source_network_attachment_id', 'source_identity_json',
'source_identity_sha256', 'source_claim_set_sha256',
'source_public_network_json', 'source_public_network_sha256',
'cleanup_operation_id', 'cleanup_job_id', 'state',
'active_debt', 'last_error_code', 'resolved_at',
'created_at', 'updated_at',
],
'cloud_peer_migration_artifacts' => [
'id', 'migration_id', 'artifact_id', 'role',
'source_snapshot_id', 'snapshot_key', 'name', 'consistency',
@ -321,7 +343,9 @@ final class CloudSetup
],
'cloud_resource_reservations' => [
'id', 'reservation_key', 'operation_id', 'order_id',
'backup_restore_id', 'offer_id', 'resource_pool_id', 'host_id',
'backup_restore_id', 'backup_restore_attempt_key',
'migration_source_debt_id', 'offer_id', 'resource_pool_id',
'host_id',
'user_id', 'instance_id', 'network_attachment_id',
'public_ip_pool_id', 'public_ip_id', 'cpu_cores', 'memory_mib',
'disk_gib', 'state', 'expires_at', 'released_at',
@ -536,6 +560,18 @@ final class CloudSetup
'cloud_deployment_snapshots' => [
'chk_cloud_deployment_snapshot_state',
],
'cloud_backup_restore_attempts' => [
'chk_cloud_backup_restore_attempt_generation',
'chk_cloud_backup_restore_attempt_active',
'chk_cloud_backup_restore_attempt_state',
'chk_cloud_backup_restore_attempt_shape',
],
'cloud_instance_migration_source_debts' => [
'chk_cloud_migration_source_debt_active',
'chk_cloud_migration_source_debt_state',
'chk_cloud_migration_source_debt_cleanup_pair',
'chk_cloud_migration_source_debt_shape',
],
'cloud_invoice_payments' => [
'chk_cloud_invoice_payment_status',
],
@ -792,6 +828,15 @@ final class CloudSetup
'cloud_backup_restore_instance', 'cloud_backup_restore_backup',
'cloud_backup_restore_host',
],
'cloud_backup_restore_attempts' => [
'PRIMARY', 'cloud_backup_restore_attempt_key',
'cloud_backup_restore_attempt_operation',
'cloud_backup_restore_attempt_generation',
'cloud_backup_restore_attempt_active',
'cloud_backup_restore_attempt_job',
'cloud_backup_restore_attempt_reservation',
'cloud_backup_restore_attempt_host',
],
'cloud_backup_recoveries' => [
'PRIMARY', 'cloud_backup_recovery_key',
'cloud_backup_recovery_operation', 'cloud_backup_recovery_job',
@ -818,6 +863,14 @@ final class CloudSetup
'cloud_instance_migration_source',
'cloud_instance_migration_target',
],
'cloud_instance_migration_source_debts' => [
'PRIMARY', 'cloud_migration_source_debt_key',
'cloud_migration_source_debt_migration',
'cloud_migration_source_debt_active_reservation',
'cloud_migration_source_debt_cleanup_operation',
'cloud_migration_source_debt_cleanup_job',
'cloud_migration_source_debt_host',
],
'cloud_peer_migration_artifacts' => [
'PRIMARY', 'cloud_peer_migration_artifact',
'cloud_peer_migration_snapshot',
@ -829,6 +882,8 @@ final class CloudSetup
'cloud_resource_reservation_operation',
'cloud_resource_reservation_order',
'cloud_resource_reservation_backup_restore',
'cloud_resource_reservation_backup_attempt',
'cloud_resource_reservation_migration_debt',
'cloud_resource_reservation_host',
'cloud_resource_reservation_pool',
'cloud_resource_reservation_instance',
@ -842,6 +897,48 @@ final class CloudSetup
* non-unique. Column order is part of the ownership/fencing semantics.
*/
private const REQUIRED_INDEX_SHAPES = [
'cloud_backup_restore_attempts' => [
'cloud_backup_restore_attempt_generation' => [
'non_unique' => 0,
'columns' => ['backup_restore_id', 'generation'],
],
'cloud_backup_restore_attempt_active' => [
'non_unique' => 0,
'columns' => ['backup_restore_id', 'active_attempt'],
],
'cloud_backup_restore_attempt_operation' => [
'non_unique' => 0,
'columns' => ['operation_id'],
],
'cloud_backup_restore_attempt_reservation' => [
'non_unique' => 0,
'columns' => ['reservation_id'],
],
],
'cloud_instance_migration_source_debts' => [
'cloud_migration_source_debt_migration' => [
'non_unique' => 0,
'columns' => ['migration_id'],
],
'cloud_migration_source_debt_active_reservation' => [
'non_unique' => 0,
'columns' => ['source_reservation_id', 'active_debt'],
],
'cloud_migration_source_debt_cleanup_operation' => [
'non_unique' => 0,
'columns' => ['cleanup_operation_id'],
],
],
'cloud_resource_reservations' => [
'cloud_resource_reservation_backup_attempt' => [
'non_unique' => 0,
'columns' => ['backup_restore_attempt_key'],
],
'cloud_resource_reservation_migration_debt' => [
'non_unique' => 0,
'columns' => ['migration_source_debt_id'],
],
],
'cloud_public_ips' => [
'cloud_public_ip_reservation' => [
'non_unique' => 1,

@ -18,4 +18,12 @@ final class CloudBackupRestore extends Model
'created_at' => 'int',
'updated_at' => 'int',
];
public function attempts()
{
return $this->hasMany(
CloudBackupRestoreAttempt::class,
'backup_restore_id'
);
}
}

@ -0,0 +1,63 @@
<?php
namespace App\Models;
/** One immutable dispatch generation for an independent backup restore. */
final class CloudBackupRestoreAttempt extends Model
{
protected $connection = 'default';
protected $table = 'cloud_backup_restore_attempts';
protected $casts = [
'id' => 'int',
'backup_restore_id' => 'int',
'generation' => 'int',
'job_id' => 'int',
'reservation_id' => 'int',
'target_host_id' => 'int',
'target_network_attachment_id' => 'int',
'active_attempt' => 'int',
'effect_resolved_at' => 'int',
'terminal_at' => 'int',
'created_at' => 'int',
'updated_at' => 'int',
];
public function restore()
{
return $this->belongsTo(CloudBackupRestore::class, 'backup_restore_id');
}
public function boundReservationQuery()
{
$reservationId = (int) ($this->reservation_id ?? 0);
$attemptKey = (string) ($this->attempt_key ?? '');
if ($reservationId < 1
|| preg_match('/^[a-f0-9]{32}$/D', $attemptKey) !== 1) {
throw new \LogicException(
'Restore attempt reservation identity is incomplete.'
);
}
return CloudResourceReservation::query()
->where('id', $reservationId)
->where('backup_restore_attempt_key', $attemptKey);
}
public function job()
{
return $this->belongsTo(CloudJob::class, 'job_id');
}
public function matchesReservation(
CloudResourceReservation $reservation
): bool {
$attemptKey = (string) ($this->attempt_key ?? '');
return (int) ($this->reservation_id ?? 0) > 0
&& (int) $this->reservation_id === (int) ($reservation->id ?? 0)
&& preg_match('/^[a-f0-9]{32}$/D', $attemptKey) === 1
&& hash_equals(
$attemptKey,
(string) ($reservation->backup_restore_attempt_key ?? '')
);
}
}

@ -30,4 +30,12 @@ final class CloudInstanceMigration extends Model
'created_at' => 'int',
'updated_at' => 'int',
];
public function sourceDebt()
{
return $this->hasOne(
CloudInstanceMigrationSourceDebt::class,
'migration_id'
);
}
}

@ -0,0 +1,58 @@
<?php
namespace App\Models;
/** Durable ownership of a retained maintenance-migration source duplicate. */
final class CloudInstanceMigrationSourceDebt extends Model
{
protected $connection = 'default';
protected $table = 'cloud_instance_migration_source_debts';
protected $casts = [
'id' => 'int',
'migration_id' => 'int',
'source_reservation_id' => 'int',
'source_host_id' => 'int',
'source_network_attachment_id' => 'int',
'cleanup_job_id' => 'int',
'active_debt' => 'int',
'resolved_at' => 'int',
'created_at' => 'int',
'updated_at' => 'int',
];
public function migration()
{
return $this->belongsTo(CloudInstanceMigration::class, 'migration_id');
}
public function boundReservationQuery()
{
$debtId = (int) ($this->id ?? 0);
$reservationId = (int) ($this->source_reservation_id ?? 0);
if ($debtId < 1 || $reservationId < 1) {
throw new \LogicException(
'Migration source-debt reservation identity is incomplete.'
);
}
return CloudResourceReservation::query()
->where('id', $reservationId)
->where('migration_source_debt_id', $debtId);
}
public function cleanupJob()
{
return $this->belongsTo(CloudJob::class, 'cleanup_job_id');
}
public function matchesReservation(
CloudResourceReservation $reservation
): bool {
return (int) ($this->id ?? 0) > 0
&& (int) ($this->source_reservation_id ?? 0) > 0
&& (int) $this->source_reservation_id
=== (int) ($reservation->id ?? 0)
&& (int) ($reservation->migration_source_debt_id ?? 0)
=== (int) $this->id;
}
}

@ -11,6 +11,7 @@ final class CloudResourceReservation extends Model
'id' => 'int',
'order_id' => 'int',
'backup_restore_id' => 'int',
'migration_source_debt_id' => 'int',
'offer_id' => 'int',
'resource_pool_id' => 'int',
'host_id' => 'int',
@ -37,11 +38,20 @@ final class CloudResourceReservation extends Model
if (!$this->exists) {
$order = (int) ($this->order_id ?? 0);
$restore = (int) ($this->backup_restore_id ?? 0);
$attemptKey = (string) ($this->backup_restore_attempt_key ?? '');
$debt = (int) ($this->migration_source_debt_id ?? 0);
$offer = (int) ($this->offer_id ?? 0);
if (!(($order > 0 && $restore === 0 && $offer > 0)
|| ($order === 0 && $restore > 0 && $offer === 0))) {
if (!(($order > 0 && $offer > 0 && $restore === 0
&& $attemptKey === '' && $debt === 0)
|| ($order === 0 && $offer === 0 && $restore > 0
&& $attemptKey === '' && $debt === 0)
|| ($order === 0 && $offer === 0 && $restore === 0
&& preg_match('/^[a-f0-9]{32}$/D', $attemptKey) === 1
&& $debt === 0)
|| ($order === 0 && $offer === 0 && $restore === 0
&& $attemptKey === '' && $debt > 0))) {
throw new \LogicException(
'New reservations require exactly one order or backup restore source.'
'New reservations require exactly one immutable source.'
);
}
}
@ -63,4 +73,33 @@ final class CloudResourceReservation extends Model
'reservation_id'
)->where('active_claim', 1);
}
public function backupRestoreAttemptQuery()
{
$reservationId = (int) ($this->id ?? 0);
$attemptKey = (string) ($this->backup_restore_attempt_key ?? '');
if ($reservationId < 1
|| preg_match('/^[a-f0-9]{32}$/D', $attemptKey) !== 1) {
throw new \LogicException(
'Restore attempt reservation identity is incomplete.'
);
}
return CloudBackupRestoreAttempt::query()
->where('reservation_id', $reservationId)
->where('attempt_key', $attemptKey);
}
public function migrationSourceDebtQuery()
{
$reservationId = (int) ($this->id ?? 0);
$debtId = (int) ($this->migration_source_debt_id ?? 0);
if ($reservationId < 1 || $debtId < 1) {
throw new \LogicException(
'Migration source-debt reservation identity is incomplete.'
);
}
return CloudInstanceMigrationSourceDebt::query()
->where('id', $debtId)
->where('source_reservation_id', $reservationId);
}
}

@ -20,6 +20,10 @@ final class CloudActivePublicNetworkClaimSet
}
/**
* @internal Topology constructors only. Application business paths must
* obtain this value through
* CloudPublicNetworkAllocationService::currentClaimSet().
*
* @param array<int, object> $claims
* @param array<int, object> $addresses keyed by public IP id
*/

@ -0,0 +1,250 @@
<?php
namespace App\Services\Cloud;
/**
* Immutable stored identity for one exact public dual-stack claim set.
*
* Canonical network and claim digests come only from the authoritative active
* claim-set projection. Callers must obtain that projection through
* CloudPublicNetworkAllocationService::currentClaimSet(); this module never
* accepts raw claim/address rows and therefore cannot bypass its topology
* validation.
*/
final class CloudFrozenPublicNetworkIdentity
{
private function __construct(
private readonly array $identity,
private readonly CloudPublicNetworkSnapshot $network,
private readonly string $claimSetSha256
) {
}
public static function fromClaimSet(int $hostId, string $uuid,
CloudActivePublicNetworkClaimSet $claimSet): self
{
$reservationId = $claimSet->reservationId();
$networkAttachmentId = $claimSet->networkAttachmentId();
self::assertResourceIdentity(
$reservationId,
$hostId,
$uuid,
$networkAttachmentId
);
$network = $claimSet->publicNetwork();
$claimSetSha256 = $claimSet->digest();
if (preg_match('/^[a-f0-9]{64}$/D', $claimSetSha256) !== 1) {
throw new \InvalidArgumentException(
'Frozen public network claim-set digest is invalid.'
);
}
return new self(self::identity(
$reservationId,
$hostId,
$uuid,
$networkAttachmentId,
$claimSetSha256,
$network->fingerprint()
), $network, $claimSetSha256);
}
/**
* Rebuild a frozen identity from its row and the current authoritative
* claim-set projection. The host id must come from the same locked
* reservation used to obtain the claim set. Top-level row columns remain
* separate so a self-consistent cross-target JSON replacement is rejected.
*/
public static function fromStored(int $reservationId, int $hostId,
string $uuid, int $networkAttachmentId, string $identityJson,
string $identitySha256, string $publicNetworkJson,
string $publicNetworkSha256, string $claimSetSha256,
CloudActivePublicNetworkClaimSet $claimSet): self
{
self::assertResourceIdentity(
$reservationId,
$hostId,
$uuid,
$networkAttachmentId
);
if (preg_match('/^[a-f0-9]{64}$/D', $identitySha256) !== 1
|| preg_match('/^[a-f0-9]{64}$/D', $publicNetworkSha256) !== 1
|| preg_match('/^[a-f0-9]{64}$/D', $claimSetSha256) !== 1) {
throw new \InvalidArgumentException(
'Frozen public network digest is invalid.'
);
}
try {
$identity = json_decode(
$identityJson,
true,
16,
JSON_THROW_ON_ERROR
);
$decoded = json_decode(
$publicNetworkJson,
true,
64,
JSON_THROW_ON_ERROR
);
} catch (\JsonException $exception) {
throw new \InvalidArgumentException(
'Frozen public network JSON is invalid.',
0,
$exception
);
}
if (!is_array($identity) || array_is_list($identity)) {
throw new \InvalidArgumentException(
'Frozen public network identity is invalid.'
);
}
self::exactKeys($identity, [
'claim_set_sha256', 'contract', 'host_id',
'network_attachment_id', 'public_network_sha256',
'reservation_id', 'uuid',
]);
if (($identity['contract'] ?? null) !== 1
|| !is_int($identity['reservation_id'] ?? null)
|| !is_int($identity['host_id'] ?? null)
|| !is_int($identity['network_attachment_id'] ?? null)
|| !is_string($identity['uuid'] ?? null)
|| !is_string($identity['claim_set_sha256'] ?? null)
|| !is_string($identity['public_network_sha256'] ?? null)) {
throw new \InvalidArgumentException(
'Frozen public network identity is invalid.'
);
}
$network = CloudPublicNetworkSnapshot::fromArray($decoded);
if (!hash_equals($network->fingerprint(), $publicNetworkSha256)) {
throw new \InvalidArgumentException(
'Frozen public network digest does not match its payload.'
);
}
$canonical = self::identity(
$reservationId,
$hostId,
$uuid,
$networkAttachmentId,
$claimSetSha256,
$publicNetworkSha256
);
if ($identity !== $canonical
|| !hash_equals($identity['claim_set_sha256'], $claimSetSha256)
|| !hash_equals(
$identity['public_network_sha256'],
$publicNetworkSha256
)
|| !hash_equals(self::digest($canonical), $identitySha256)) {
throw new \InvalidArgumentException(
'Frozen public network identity digest does not match.'
);
}
$authoritative = self::fromClaimSet($hostId, $uuid, $claimSet);
if ($claimSet->reservationId() !== $reservationId
|| $claimSet->networkAttachmentId() !== $networkAttachmentId
|| !hash_equals(
$authoritative->claimSetSha256(),
$claimSetSha256
)
|| !hash_equals(
$authoritative->publicNetworkSha256(),
$publicNetworkSha256
)
|| !hash_equals(
$authoritative->publicNetwork()->fingerprint(),
$network->fingerprint()
)) {
throw new \InvalidArgumentException(
'Frozen public network identity does not match its claim set.'
);
}
return new self($canonical, $network, $claimSetSha256);
}
public function identityJson(): string
{
return self::encode($this->identity);
}
public function identitySha256(): string
{
return self::digest($this->identity);
}
public function publicNetwork(): CloudPublicNetworkSnapshot
{
return $this->network;
}
public function publicNetworkJson(): string
{
return json_encode(
$this->network->toArray(),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
}
public function publicNetworkSha256(): string
{
return $this->network->fingerprint();
}
public function claimSetSha256(): string
{
return $this->claimSetSha256;
}
private static function identity(int $reservationId, int $hostId,
string $uuid, int $networkAttachmentId, string $claimSetSha256,
string $publicNetworkSha256): array
{
return [
'contract' => 1,
'reservation_id' => $reservationId,
'host_id' => $hostId,
'uuid' => strtolower($uuid),
'network_attachment_id' => $networkAttachmentId,
'claim_set_sha256' => $claimSetSha256,
'public_network_sha256' => $publicNetworkSha256,
];
}
private static function assertResourceIdentity(int $reservationId,
int $hostId, string $uuid, int $networkAttachmentId): void
{
if ($reservationId < 1 || $hostId < 1 || $networkAttachmentId < 1
|| preg_match(
'/^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/D',
strtolower($uuid)
) !== 1) {
throw new \InvalidArgumentException(
'Frozen public network resource identity is invalid.'
);
}
}
private static function exactKeys(array $value, array $expected): void
{
$actual = array_keys($value);
sort($actual, SORT_STRING);
sort($expected, SORT_STRING);
if ($actual !== $expected) {
throw new \InvalidArgumentException(
'Frozen public network identity fields are invalid.'
);
}
}
private static function encode(array $value): string
{
return json_encode(
$value,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
}
private static function digest(array $value): string
{
return hash('sha256', self::encode($value));
}
}

@ -90,10 +90,43 @@ final class CloudPublicNetworkAllocationService
if ($set->reservationId() !== $reservationId) {
throw new CloudError('公网网络活动声明归属不一致', 409);
}
if ($expectedState === 'committed') {
self::assertInstancePublicNetworkSnapshot($instance, $set);
}
return $set;
});
}
private static function assertInstancePublicNetworkSnapshot(
?object $instance,
CloudActivePublicNetworkClaimSet $claimSet
): void {
try {
$spec = json_decode(
(string) ($instance->spec_json ?? ''),
true,
64,
JSON_THROW_ON_ERROR
);
if (!is_array($spec) || array_is_list($spec)) {
throw new \InvalidArgumentException(
'Instance specification is invalid.'
);
}
$frozen = CloudPublicNetworkSnapshot::fromArray(
$spec['public_network'] ?? null
);
} catch (\Throwable) {
throw new CloudError('实例缺少有效的冻结公网网络快照', 409);
}
if (!hash_equals(
$frozen->fingerprint(),
$claimSet->publicNetwork()->fingerprint()
)) {
throw new CloudError('实例冻结公网网络快照与活动声明不一致', 409);
}
}
public static function reserveBundle(int $hostId, int $lineId,
int $reservationId, string $operationId): CloudPublicNetworkSnapshot
{

@ -1267,6 +1267,86 @@ CREATE TABLE cloud_backup_restores (
KEY cloud_backup_restore_backup (backup_id, state, id),
KEY cloud_backup_restore_host (target_host_id, state, id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- Every independent restore dispatch owns one immutable attempt. A confirmed
-- not-applied retry creates a new generation and operation instead of
-- rewriting the historical reservation or claim identity. Unknown effects
-- remain active and therefore keep the complete dual-stack bundle fenced.
CREATE TABLE cloud_backup_restore_attempts (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
backup_restore_id BIGINT UNSIGNED NOT NULL,
generation INT UNSIGNED NOT NULL,
operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
job_id BIGINT UNSIGNED DEFAULT NULL,
reservation_id BIGINT UNSIGNED NOT NULL,
target_host_id BIGINT UNSIGNED NOT NULL,
target_uuid CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
target_name VARCHAR(63) NOT NULL,
target_network_attachment_id BIGINT UNSIGNED NOT NULL,
target_identity_json LONGTEXT NOT NULL,
target_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
target_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
target_public_network_json LONGTEXT NOT NULL,
target_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
state VARCHAR(24) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'reserved',
effect_resolution VARCHAR(16) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'not_applicable',
active_attempt TINYINT UNSIGNED DEFAULT 1,
last_error_code VARCHAR(128) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '',
effect_resolved_at BIGINT UNSIGNED DEFAULT NULL,
terminal_at BIGINT UNSIGNED DEFAULT NULL,
created_at BIGINT UNSIGNED NOT NULL,
updated_at BIGINT UNSIGNED NOT NULL,
UNIQUE KEY cloud_backup_restore_attempt_key (attempt_key),
UNIQUE KEY cloud_backup_restore_attempt_operation (operation_id),
UNIQUE KEY cloud_backup_restore_attempt_generation (
backup_restore_id, generation
),
UNIQUE KEY cloud_backup_restore_attempt_active (
backup_restore_id, active_attempt
),
UNIQUE KEY cloud_backup_restore_attempt_job (job_id),
UNIQUE KEY cloud_backup_restore_attempt_reservation (reservation_id),
KEY cloud_backup_restore_attempt_host (target_host_id, state, id),
CONSTRAINT chk_cloud_backup_restore_attempt_generation CHECK (
generation >= 1
),
CONSTRAINT chk_cloud_backup_restore_attempt_active CHECK (
active_attempt IS NULL OR active_attempt = 1
),
CONSTRAINT chk_cloud_backup_restore_attempt_state CHECK (
state IN ('reserved','queued','awaiting_receipt','effect_unknown',
'finalization_pending','succeeded','failed')
),
CONSTRAINT chk_cloud_backup_restore_attempt_shape CHECK (
(state = 'reserved'
AND job_id IS NULL
AND effect_resolution = 'not_applicable'
AND active_attempt IS NOT NULL AND active_attempt = 1
AND effect_resolved_at IS NULL AND terminal_at IS NULL)
OR (state IN ('queued','awaiting_receipt')
AND job_id IS NOT NULL
AND effect_resolution = 'not_applicable'
AND active_attempt IS NOT NULL AND active_attempt = 1
AND effect_resolved_at IS NULL AND terminal_at IS NULL)
OR (state = 'effect_unknown' AND effect_resolution = 'unknown'
AND job_id IS NOT NULL
AND active_attempt IS NOT NULL AND active_attempt = 1
AND effect_resolved_at IS NULL AND terminal_at IS NULL)
OR (state = 'finalization_pending'
AND job_id IS NOT NULL
AND effect_resolution IN ('applied','not_applied')
AND active_attempt IS NOT NULL AND active_attempt = 1
AND effect_resolved_at IS NOT NULL AND terminal_at IS NULL)
OR (state = 'succeeded' AND effect_resolution = 'applied'
AND job_id IS NOT NULL
AND active_attempt IS NULL
AND effect_resolved_at IS NOT NULL AND terminal_at IS NOT NULL)
OR (state = 'failed' AND effect_resolution = 'not_applied'
AND job_id IS NOT NULL
AND active_attempt IS NULL
AND effect_resolved_at IS NOT NULL AND terminal_at IS NOT NULL)
)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- Restoring a backup onto its source instance is a destructive disk switch,
-- distinct from creating an independent restored VM. This ledger fences the
-- original operation until its exact Agent receipt is reconciled.
@ -1339,6 +1419,71 @@ CREATE TABLE cloud_instance_migrations (
KEY cloud_instance_migration_source (source_host_id, source_uuid),
KEY cloud_instance_migration_target (target_host_id, target_uuid)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- After cutover the stopped source duplicate is not an ordinary restore. Its
-- exact reservation and dual-stack identity remain a durable cleanup debt
-- until source deletion is confirmed or rollback restores source authority.
CREATE TABLE cloud_instance_migration_source_debts (
id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
debt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
migration_id BIGINT UNSIGNED NOT NULL,
source_reservation_id BIGINT UNSIGNED NOT NULL,
source_host_id BIGINT UNSIGNED NOT NULL,
source_uuid CHAR(36) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
source_network_attachment_id BIGINT UNSIGNED NOT NULL,
source_identity_json LONGTEXT NOT NULL,
source_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
source_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
source_public_network_json LONGTEXT NOT NULL,
source_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
cleanup_operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL,
cleanup_job_id BIGINT UNSIGNED DEFAULT NULL,
state VARCHAR(24) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT 'prepared',
active_debt TINYINT UNSIGNED DEFAULT 1,
last_error_code VARCHAR(128) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '',
resolved_at BIGINT UNSIGNED DEFAULT NULL,
created_at BIGINT UNSIGNED NOT NULL,
updated_at BIGINT UNSIGNED NOT NULL,
UNIQUE KEY cloud_migration_source_debt_key (debt_key),
UNIQUE KEY cloud_migration_source_debt_migration (migration_id),
UNIQUE KEY cloud_migration_source_debt_active_reservation (
source_reservation_id, active_debt
),
UNIQUE KEY cloud_migration_source_debt_cleanup_operation (
cleanup_operation_id
),
UNIQUE KEY cloud_migration_source_debt_cleanup_job (cleanup_job_id),
KEY cloud_migration_source_debt_host (source_host_id, state, id),
CONSTRAINT chk_cloud_migration_source_debt_active CHECK (
active_debt IS NULL OR active_debt = 1
),
CONSTRAINT chk_cloud_migration_source_debt_state CHECK (
state IN ('prepared','retained','cleanup_running','released',
'rollback_restored','attention')
),
CONSTRAINT chk_cloud_migration_source_debt_cleanup_pair CHECK (
(cleanup_operation_id IS NULL AND cleanup_job_id IS NULL)
OR (cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL)
),
CONSTRAINT chk_cloud_migration_source_debt_shape CHECK (
(state IN ('prepared','retained')
AND active_debt IS NOT NULL AND active_debt = 1
AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL
AND resolved_at IS NULL)
OR (state = 'cleanup_running'
AND active_debt IS NOT NULL AND active_debt = 1
AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL
AND resolved_at IS NULL)
OR (state = 'attention'
AND active_debt IS NOT NULL AND active_debt = 1
AND resolved_at IS NULL)
OR (state = 'released' AND active_debt IS NULL
AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL
AND resolved_at IS NOT NULL)
OR (state = 'rollback_restored' AND active_debt IS NULL
AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL
AND resolved_at IS NOT NULL)
)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
-- Immutable direct-transfer artifacts that exist only for one PeerMigration V3
-- session. Host paths and tickets are never stored in this catalog.
CREATE TABLE cloud_peer_migration_artifacts (
@ -1439,6 +1584,8 @@ CREATE TABLE cloud_resource_reservations (
operation_id CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
order_id BIGINT UNSIGNED DEFAULT NULL,
backup_restore_id BIGINT UNSIGNED DEFAULT NULL,
backup_restore_attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL,
migration_source_debt_id BIGINT UNSIGNED DEFAULT NULL,
offer_id BIGINT UNSIGNED DEFAULT NULL,
resource_pool_id BIGINT UNSIGNED NOT NULL,
host_id BIGINT UNSIGNED NOT NULL,
@ -1460,14 +1607,34 @@ CREATE TABLE cloud_resource_reservations (
UNIQUE KEY cloud_resource_reservation_operation (operation_id),
UNIQUE KEY cloud_resource_reservation_order (order_id),
UNIQUE KEY cloud_resource_reservation_backup_restore (backup_restore_id),
UNIQUE KEY cloud_resource_reservation_backup_attempt (
backup_restore_attempt_key
),
UNIQUE KEY cloud_resource_reservation_migration_debt (
migration_source_debt_id
),
KEY cloud_resource_reservation_host (host_id, state, expires_at, id),
KEY cloud_resource_reservation_pool (resource_pool_id, state, id),
KEY cloud_resource_reservation_instance (instance_id),
KEY cloud_resource_reservation_network (network_attachment_id, public_ip_pool_id),
KEY cloud_resource_reservation_ip (public_ip_id),
CONSTRAINT chk_cloud_resource_reservation_source CHECK (
(order_id IS NOT NULL AND backup_restore_id IS NULL AND offer_id IS NOT NULL)
OR (order_id IS NULL AND backup_restore_id IS NOT NULL AND offer_id IS NULL)
(order_id IS NOT NULL AND offer_id IS NOT NULL
AND backup_restore_id IS NULL
AND backup_restore_attempt_key IS NULL
AND migration_source_debt_id IS NULL)
OR (order_id IS NULL AND offer_id IS NULL
AND backup_restore_id IS NOT NULL
AND backup_restore_attempt_key IS NULL
AND migration_source_debt_id IS NULL)
OR (order_id IS NULL AND offer_id IS NULL
AND backup_restore_id IS NULL
AND backup_restore_attempt_key IS NOT NULL
AND migration_source_debt_id IS NULL)
OR (order_id IS NULL AND offer_id IS NULL
AND backup_restore_id IS NULL
AND backup_restore_attempt_key IS NULL
AND migration_source_debt_id IS NOT NULL)
)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

@ -22,7 +22,7 @@ $assert(stripos($schema, 'compatibility import') === false
$assert(!preg_match('/\bengine_[A-Za-z0-9_]*\b/', $schema),
'cloud.sql retained an engine-prefixed identifier.');
$assert(str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& !str_contains($setup, "SCHEMA_VERSION = 'go-v1'"),
'Outbound Agent schema must reject the incompatible earlier Go database.');
$assert(str_contains($schema,
@ -44,9 +44,11 @@ foreach (['cloud_host_agents', 'cloud_templates',
'cloud_instance_backups',
'cloud_deployment_snapshots',
'cloud_backup_subscriptions', 'cloud_backup_period_entitlements',
'cloud_backup_restores',
'cloud_backup_restores', 'cloud_backup_restore_attempts',
'cloud_backup_recoveries', 'cloud_order_items', 'cloud_invoice_items',
'cloud_instance_migrations', 'cloud_peer_migration_artifacts',
'cloud_instance_migrations',
'cloud_instance_migration_source_debts',
'cloud_peer_migration_artifacts',
'cloud_resource_reservation_ips',
'cloud_public_network_transitions',
'cloud_public_network_transition_ips',
@ -122,8 +124,9 @@ $assert(str_contains($schema,
'KEY cloud_job_backup_recovery (backup_recovery_id, id)')
&& str_contains($setup,
"'cloud_backup_subscriptions', 'cloud_backup_period_entitlements'")
&& str_contains($setup,
"'cloud_backup_restores', 'cloud_backup_recoveries'")
&& str_contains($setup, "'cloud_backup_restores'")
&& str_contains($setup, "'cloud_backup_restore_attempts'")
&& str_contains($setup, "'cloud_backup_recoveries'")
&& str_contains($setup,
"'cloud_job_backup', 'cloud_job_backup_restore'")
&& str_contains($setup,

@ -65,7 +65,7 @@ $assert(is_string($schema)
'Public-pool replacement lacks durable batch, child, or active-claim schema.');
$assert(is_string($setup)
&& str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($setup,
"'cloud_public_ip_pool_replacement_batches'")
&& str_contains($setup,

@ -5,6 +5,7 @@ require dirname(__DIR__) . '/vendor/autoload.php';
use App\Services\Cloud\CloudPublicNetworkAllocationService;
use App\Services\Cloud\CloudPublicNetworkCapacityUnavailable;
use App\Services\Cloud\CloudActivePublicNetworkClaimSet;
use App\Services\Cloud\CloudFrozenPublicNetworkIdentity;
use App\Services\Cloud\CloudPublicNetworkSnapshot;
use App\Services\Cloud\CloudError;
use Illuminate\Database\Capsule\Manager as Capsule;
@ -127,6 +128,7 @@ $schema->create('cloud_instances', static function (Blueprint $table): void {
$table->integer('host_id');
$table->integer('resource_pool_id');
$table->integer('user_id');
$table->text('spec_json');
});
$schema->create('cloud_instance_migrations', static function (
Blueprint $table
@ -285,11 +287,11 @@ foreach ($operations as $id => $operationId) {
Capsule::table('cloud_instances')->insert([
[
'id' => 900, 'reservation_id' => 500, 'host_id' => 1,
'resource_pool_id' => 30, 'user_id' => 42,
'resource_pool_id' => 30, 'user_id' => 42, 'spec_json' => '{}',
],
[
'id' => 901, 'reservation_id' => 504, 'host_id' => 1,
'resource_pool_id' => 30, 'user_id' => 42,
'resource_pool_id' => 30, 'user_id' => 42, 'spec_json' => '{}',
],
]);
@ -332,6 +334,12 @@ Capsule::table('cloud_resource_reservations')->where('id', 500)->update([
'state' => 'committed',
'instance_id' => 900,
]);
Capsule::table('cloud_instances')->where('id', 900)->update([
'spec_json' => json_encode(
['public_network' => $committed->toArray()],
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
),
]);
$replacementAttempt = CloudPublicNetworkAllocationService::reserveBundle(
1,
7,
@ -426,6 +434,12 @@ Capsule::table('cloud_resource_reservations')->where('id', 504)->update([
'state' => 'committed',
'instance_id' => 901,
]);
Capsule::table('cloud_instances')->where('id', 901)->update([
'spec_json' => json_encode(
['public_network' => $recoveredSuccess->toArray()],
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
),
]);
$rejects(static fn () => CloudPublicNetworkAllocationService::commitBundle(
504,
902,
@ -470,6 +484,103 @@ $assert($mixedGeneration->generation(4) === 1
&& $mixedGeneration->generation(6) === 2
&& strlen($mixedGeneration->digest()) === 64,
'A legal active pair required both families to share generation or operation.');
$frozenUuid = '123e4567-e89b-42d3-a456-426614174000';
$frozen = CloudFrozenPublicNetworkIdentity::fromClaimSet(
1,
$frozenUuid,
$mixedGeneration
);
$restoredFrozen = CloudFrozenPublicNetworkIdentity::fromStored(
500,
1,
$frozenUuid,
10,
$frozen->identityJson(),
$frozen->identitySha256(),
$frozen->publicNetworkJson(),
$frozen->publicNetworkSha256(),
$frozen->claimSetSha256(),
$mixedGeneration
);
$assert(hash_equals(
$restoredFrozen->identitySha256(),
$frozen->identitySha256()
) && hash_equals(
$restoredFrozen->claimSetSha256(),
$mixedGeneration->digest()
),
'A frozen identity did not round-trip its authoritative claim set.');
$tamperedTopLevel = json_decode(
$frozen->identityJson(),
true,
16,
JSON_THROW_ON_ERROR
);
$tamperedTopLevel['network_attachment_id'] = 11;
$tamperedTopLevelJson = json_encode(
$tamperedTopLevel,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored(
500,
1,
$frozenUuid,
11,
$tamperedTopLevelJson,
hash('sha256', $tamperedTopLevelJson),
$frozen->publicNetworkJson(),
$frozen->publicNetworkSha256(),
$frozen->claimSetSha256(),
$mixedGeneration
), 'A self-consistent attachment rewrite bypassed the current claim set.');
$tamperedNetwork = $mixedGeneration->publicNetwork()->toArray();
$tamperedNetwork['network_selector'] = 'bridge:br1';
$tamperedNetwork = CloudPublicNetworkSnapshot::fromArray($tamperedNetwork);
$tamperedNetworkJson = json_encode(
$tamperedNetwork->toArray(),
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$tamperedNetworkIdentity = json_decode(
$frozen->identityJson(),
true,
16,
JSON_THROW_ON_ERROR
);
$tamperedNetworkIdentity['public_network_sha256'] =
$tamperedNetwork->fingerprint();
$tamperedNetworkIdentityJson = json_encode(
$tamperedNetworkIdentity,
JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES
);
$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored(
500,
1,
$frozenUuid,
10,
$tamperedNetworkIdentityJson,
hash('sha256', $tamperedNetworkIdentityJson),
$tamperedNetworkJson,
$tamperedNetwork->fingerprint(),
$frozen->claimSetSha256(),
$mixedGeneration
), 'A self-consistent network rewrite bypassed the current claim set.');
$otherGeneration = CloudPublicNetworkAllocationService::currentClaimSet(
504,
'committed',
901
);
$rejects(static fn () => CloudFrozenPublicNetworkIdentity::fromStored(
500,
1,
$frozenUuid,
10,
$frozen->identityJson(),
$frozen->identitySha256(),
$frozen->publicNetworkJson(),
$frozen->publicNetworkSha256(),
$frozen->claimSetSha256(),
$otherGeneration
), 'A frozen identity accepted another reservation claim set.');
$activeRows = Capsule::table('cloud_resource_reservation_ips')
->where('reservation_id', 500)->where('active_claim', 1)
->orderBy('address_family')->get()->all();
@ -562,6 +673,8 @@ $instance900 = [
'host_id' => 1,
'resource_pool_id' => 30,
'user_id' => 42,
'spec_json' => (string) Capsule::table('cloud_instances')
->where('id', 900)->value('spec_json'),
];
$assertCurrentAuthorityRejects(
static fn () => Capsule::table('cloud_instances')
@ -665,6 +778,13 @@ $assertCurrentAuthorityRejects(
->where('id', 10)->update(['line_id' => 7]),
'A claim set accepted an attachment outside the reservation line.'
);
$assertCurrentAuthorityRejects(
static fn () => Capsule::table('cloud_host_network_attachments')
->where('id', 10)->update(['network_selector' => 'bridge:br1']),
static fn () => Capsule::table('cloud_host_network_attachments')
->where('id', 10)->update(['network_selector' => 'bridge:br0']),
'A claim set accepted selector drift from the frozen instance snapshot.'
);
$assertCurrentAuthorityRejects(
static fn () => Capsule::table('cloud_resource_reservations')
->where('id', 500)->update(['resource_pool_id' => 31]),
@ -679,6 +799,13 @@ $assertCurrentAuthorityRejects(
->where('id', 100)->update(['host_id' => 1]),
'A claim set accepted a pool outside the reservation host.'
);
$assertCurrentAuthorityRejects(
static fn () => Capsule::table('cloud_public_ip_pools')
->where('id', 100)->update(['network_attachment_id' => 11]),
static fn () => Capsule::table('cloud_public_ip_pools')
->where('id', 100)->update(['network_attachment_id' => 10]),
'A claim set accepted a pool outside the active attachment.'
);
$assertCurrentAuthorityRejects(
static fn () => Capsule::table('cloud_public_ips')
->where('id', (int) $ipv4Claim->public_ip_id)

@ -170,7 +170,7 @@ $assert(str_contains($setup,
'CloudSetup does not verify index uniqueness and ordered columns.');
$assert(str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($setup, "'cloud_public_network_transitions'")
&& str_contains($setup, "'cloud_public_network_transition_ips'")
&& str_contains($setup, "'reservation_ip_claim_id'")

@ -56,7 +56,7 @@ $assert($replica !== ''
&& str_contains($replica, 'cleanup_resolved_at BIGINT UNSIGNED'),
'Rescue replica cannot prove exact identity or retain cleanup debt.');
$assert(str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($setup, "'cloud_rescue_artifact_delete_due'")
&& str_contains($setup, "'cloud_rescue_replica_cleanup'"),
'CloudSetup version or rescue catalog indexes are incomplete.');

@ -0,0 +1,278 @@
<?php
require dirname(__DIR__) . '/vendor/autoload.php';
use App\Models\CloudBackupRestoreAttempt;
use App\Models\CloudInstanceMigrationSourceDebt;
use App\Models\CloudResourceReservation;
use Illuminate\Database\Capsule\Manager as Capsule;
$root = dirname(__DIR__);
$schema = file_get_contents($root . '/sql/cloud.sql');
$setup = file_get_contents($root . '/app/Command/CloudSetup.php');
$reservationModel = file_get_contents(
$root . '/app/Models/CloudResourceReservation.php'
);
$attemptModel = file_get_contents(
$root . '/app/Models/CloudBackupRestoreAttempt.php'
);
$debtModel = file_get_contents(
$root . '/app/Models/CloudInstanceMigrationSourceDebt.php'
);
if (!is_string($schema) || !is_string($setup)
|| !is_string($reservationModel) || !is_string($attemptModel)
|| !is_string($debtModel)) {
throw new RuntimeException('Restore/migration ledger sources are unreadable.');
}
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$table = static function (string $name) use ($schema): string {
$start = strpos($schema, 'CREATE TABLE ' . $name . ' (');
if ($start === false) {
return '';
}
$end = strpos(
$schema,
') ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;',
$start
);
return $end === false ? '' : substr($schema, $start, $end - $start);
};
$normalized = static function (string $value): string {
return trim((string) preg_replace('/\s+/', ' ', $value));
};
$capsule = new Capsule();
$capsule->addConnection([
'driver' => 'sqlite',
'database' => ':memory:',
], 'default');
$capsule->setAsGlobal();
$capsule->bootEloquent();
$schemaBuilder = $capsule->schema('default');
$schemaBuilder->create('cloud_backup_restore_attempts', static function (
$table
): void {
$table->integer('id')->primary();
$table->string('attempt_key');
$table->integer('reservation_id');
});
$schemaBuilder->create('cloud_instance_migration_source_debts', static function (
$table
): void {
$table->integer('id')->primary();
$table->integer('source_reservation_id');
});
$schemaBuilder->create('cloud_resource_reservations', static function (
$table
): void {
$table->integer('id')->primary();
$table->string('backup_restore_attempt_key')->nullable();
$table->integer('migration_source_debt_id')->nullable();
});
$attempts = $table('cloud_backup_restore_attempts');
$debts = $table('cloud_instance_migration_source_debts');
$reservations = $table('cloud_resource_reservations');
$assert($attempts !== ''
&& str_contains($attempts,
'reservation_id BIGINT UNSIGNED NOT NULL')
&& str_contains($attempts,
'UNIQUE KEY cloud_backup_restore_attempt_generation')
&& str_contains($attempts,
'UNIQUE KEY cloud_backup_restore_attempt_active')
&& str_contains($attempts,
'UNIQUE KEY cloud_backup_restore_attempt_operation (operation_id)')
&& str_contains($attempts,
'target_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($attempts,
'target_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($attempts,
'target_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($attempts,
'CONSTRAINT chk_cloud_backup_restore_attempt_shape CHECK'),
'Backup restore attempts do not fence immutable generations and network identity.');
$attemptShape = $normalized($attempts);
$assert(str_contains($attemptShape,
"state = 'reserved' AND job_id IS NULL AND effect_resolution = 'not_applicable' AND active_attempt IS NOT NULL AND active_attempt = 1")
&& str_contains($attemptShape,
"state IN ('queued','awaiting_receipt') AND job_id IS NOT NULL AND effect_resolution = 'not_applicable' AND active_attempt IS NOT NULL AND active_attempt = 1")
&& str_contains($attemptShape,
"state = 'effect_unknown' AND effect_resolution = 'unknown' AND job_id IS NOT NULL AND active_attempt IS NOT NULL AND active_attempt = 1")
&& str_contains($attemptShape,
"state = 'finalization_pending' AND job_id IS NOT NULL AND effect_resolution IN ('applied','not_applied') AND active_attempt IS NOT NULL AND active_attempt = 1")
&& str_contains($attemptShape,
"state = 'succeeded' AND effect_resolution = 'applied' AND job_id IS NOT NULL AND active_attempt IS NULL")
&& str_contains($attemptShape,
"state = 'failed' AND effect_resolution = 'not_applied' AND job_id IS NOT NULL AND active_attempt IS NULL"),
'Restore-attempt terminal and unknown-effect fencing can diverge.');
$assert($debts !== ''
&& str_contains($debts,
'UNIQUE KEY cloud_migration_source_debt_migration (migration_id)')
&& str_contains($debts,
'UNIQUE KEY cloud_migration_source_debt_active_reservation')
&& str_contains($debts,
'source_identity_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($debts,
'source_claim_set_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($debts,
'source_public_network_sha256 CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL')
&& str_contains($debts,
"state IN ('prepared','retained','cleanup_running','released',")
&& str_contains($debts,
'CONSTRAINT chk_cloud_migration_source_debt_shape CHECK'),
'Maintenance migration source cleanup debt is not durable and exclusive.');
$debtShape = $normalized($debts);
$assert(str_contains($debtShape,
"(cleanup_operation_id IS NULL AND cleanup_job_id IS NULL) OR (cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL)")
&& str_contains($debtShape,
"state IN ('prepared','retained') AND active_debt IS NOT NULL AND active_debt = 1 AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL AND resolved_at IS NULL")
&& str_contains($debtShape,
"state = 'cleanup_running' AND active_debt IS NOT NULL AND active_debt = 1 AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL AND resolved_at IS NULL")
&& str_contains($debtShape,
"state = 'attention' AND active_debt IS NOT NULL AND active_debt = 1 AND resolved_at IS NULL")
&& str_contains($debtShape,
"state = 'released' AND active_debt IS NULL AND cleanup_operation_id IS NOT NULL AND cleanup_job_id IS NOT NULL AND resolved_at IS NOT NULL")
&& str_contains($debtShape,
"state = 'rollback_restored' AND active_debt IS NULL AND cleanup_operation_id IS NULL AND cleanup_job_id IS NULL AND resolved_at IS NOT NULL"),
'Source debt can become terminal without confirmed resolution.');
// MySQL accepts CHECK expressions that evaluate to UNKNOWN. Every live-state
// branch must therefore reject NULL explicitly before comparing the nullable
// unique-index fence with 1.
$assert(!str_contains($attemptShape,
"effect_resolution = 'unknown' AND active_attempt = 1")
&& !str_contains($debtShape,
"state = 'attention' AND active_debt = 1"),
'A nullable active fence can satisfy MySQL CHECK through UNKNOWN.');
$assert($reservations !== ''
&& str_contains($reservations,
'backup_restore_attempt_key CHAR(32) CHARACTER SET ascii COLLATE ascii_bin DEFAULT NULL')
&& str_contains($reservations,
'migration_source_debt_id BIGINT UNSIGNED DEFAULT NULL')
&& str_contains($reservations,
'UNIQUE KEY cloud_resource_reservation_backup_attempt')
&& str_contains($reservations,
'UNIQUE KEY cloud_resource_reservation_migration_debt')
&& !str_contains($reservations, 'backup_restore_attempt_id')
&& substr_count($reservations,
'backup_restore_attempt_key IS NOT NULL') === 1
&& substr_count($reservations, 'migration_source_debt_id IS NOT NULL') === 1,
'Reservation ownership does not enforce one source ledger.');
foreach ([
"'cloud_backup_restore_attempts'",
"'cloud_instance_migration_source_debts'",
"'backup_restore_attempt_key'",
"'migration_source_debt_id'",
"'chk_cloud_backup_restore_attempt_shape'",
"'chk_cloud_migration_source_debt_shape'",
"'chk_cloud_migration_source_debt_cleanup_pair'",
"'cloud_backup_restore_attempt_active'",
"'cloud_migration_source_debt_active_reservation'",
"'columns' => ['backup_restore_attempt_key']",
"'columns' => ['migration_source_debt_id']",
] as $required) {
$assert(str_contains($setup, $required),
'CloudSetup omits restore/migration ledger contract: ' . $required);
}
$assert(str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($attemptModel,
"protected \$table = 'cloud_backup_restore_attempts';")
&& str_contains($attemptModel, "'active_attempt' => 'int'")
&& str_contains($debtModel,
"protected \$table = 'cloud_instance_migration_source_debts';")
&& str_contains($debtModel, "'active_debt' => 'int'")
&& str_contains($reservationModel,
"function backupRestoreAttemptQuery()")
&& str_contains($attemptModel,
"function boundReservationQuery()")
&& str_contains($debtModel,
"function boundReservationQuery()")
&& str_contains($reservationModel,
"'migration_source_debt_id' => 'int'"),
'Models or setup version do not expose the new ownership boundary.');
$frozenIdentity = file_get_contents(
$root . '/app/Services/Cloud/CloudFrozenPublicNetworkIdentity.php'
);
$assert(is_string($frozenIdentity)
&& str_contains($frozenIdentity,
'public static function fromClaimSet(int $hostId, string $uuid,')
&& str_contains($frozenIdentity,
'CloudActivePublicNetworkClaimSet $claimSet')
&& str_contains($frozenIdentity,
'CloudPublicNetworkAllocationService::currentClaimSet()')
&& !str_contains($frozenIdentity,
'public static function fromLedger(')
&& !str_contains($frozenIdentity, 'array $claims')
&& !str_contains($frozenIdentity, 'array $addresses'),
'Frozen identity can bypass the authoritative claim-set module.');
$attemptRecord = new CloudBackupRestoreAttempt();
$attemptRecord->id = 91;
$attemptRecord->attempt_key = str_repeat('e', 32);
$attemptRecord->reservation_id = 92;
$reservationRecord = new CloudResourceReservation();
$reservationRecord->id = 92;
$reservationRecord->backup_restore_attempt_key = str_repeat('e', 32);
Capsule::table('cloud_backup_restore_attempts')->insert([
'id' => 91,
'attempt_key' => str_repeat('e', 32),
'reservation_id' => 92,
]);
Capsule::table('cloud_resource_reservations')->insert([
'id' => 92,
'backup_restore_attempt_key' => str_repeat('e', 32),
'migration_source_debt_id' => null,
]);
$assert($attemptRecord->matchesReservation($reservationRecord)
&& (int) $attemptRecord->boundReservationQuery()->first()?->id === 92
&& (int) $reservationRecord->backupRestoreAttemptQuery()->first()?->id
=== 91,
'Restore attempt and reservation are not joined by id and stable key.');
$reservationRecord->backup_restore_attempt_key = str_repeat('f', 32);
Capsule::table('cloud_resource_reservations')->where('id', 92)->update([
'backup_restore_attempt_key' => str_repeat('f', 32),
]);
$assert(!$attemptRecord->matchesReservation($reservationRecord)
&& $attemptRecord->boundReservationQuery()->first() === null
&& $reservationRecord->backupRestoreAttemptQuery()->first() === null,
'Restore attempt accepted a cross-bound reservation identity.');
$debtRecord = new CloudInstanceMigrationSourceDebt();
$debtRecord->id = 101;
$debtRecord->source_reservation_id = 102;
$debtReservation = new CloudResourceReservation();
$debtReservation->id = 102;
$debtReservation->migration_source_debt_id = 101;
Capsule::table('cloud_instance_migration_source_debts')->insert([
'id' => 101,
'source_reservation_id' => 102,
]);
Capsule::table('cloud_resource_reservations')->insert([
'id' => 102,
'backup_restore_attempt_key' => null,
'migration_source_debt_id' => 101,
]);
$assert($debtRecord->matchesReservation($debtReservation)
&& (int) $debtRecord->boundReservationQuery()->first()?->id === 102
&& (int) $debtReservation->migrationSourceDebtQuery()->first()?->id
=== 101,
'Migration source debt does not bind the exact source reservation both ways.');
$debtReservation->migration_source_debt_id = 103;
Capsule::table('cloud_resource_reservations')->where('id', 102)->update([
'migration_source_debt_id' => 103,
]);
$assert(!$debtRecord->matchesReservation($debtReservation)
&& $debtRecord->boundReservationQuery()->first() === null
&& $debtReservation->migrationSourceDebtQuery()->first() === null,
'Migration source debt accepted a cross-bound reservation identity.');
echo "Restore/migration durable-ledger contract tests passed.\n";

@ -63,7 +63,7 @@ $assert(str_contains($schema,
&& str_contains($schema,
'CONSTRAINT chk_cloud_template_import_completion CHECK (')
&& str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'"),
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'"),
'Template imports are missing durable identity or terminal-state constraints.');
$assert(str_contains($routes, "'/admin/cloud-template-imports'")
&& str_contains($routes, "'/admin/cloud-template-imports/{id}'")

@ -71,7 +71,7 @@ $assert(str_contains($schema,
'Service-period traffic-pool identity is not frozen or indexed.');
$assert(str_contains($setup,
"SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($setup, "'chk_cloud_traffic_entitlement_balance'")
&& str_contains($setup, "'cloud_traffic_ledger_sequence'"),
'CloudSetup schema version or named-object validation is incomplete.');

@ -101,7 +101,7 @@ $assert(str_contains($jobs, 'vpc_id BIGINT UNSIGNED DEFAULT NULL')
'Cloud jobs cannot be correlated to VPC or VPC-port work.');
$assert(str_contains($setup,
"private const SCHEMA_VERSION = 'go-agent-wss-v30-public-network-batch-identity'")
"private const SCHEMA_VERSION = 'go-agent-wss-v31-restore-migration-ledgers'")
&& str_contains($setup, "'name' => 'cloud_vpc_enabled'")
&& str_contains($setup, "'value' => 'false'")
&& str_contains($setup,

Loading…
Cancel
Save