Freeze SCUM guarded mutation run contract

2026-08-13 14:04:44 +08:00
parent ac6f5419fe
commit 41c109128d
17 changed files with 741 additions and 37 deletions
@@ -38,32 +38,40 @@ const (
 type SCUMSafeErrorCode string

 const (
-	SCUMSafeErrorNone                SCUMSafeErrorCode = "none"
-	SCUMSafeErrorProbeExecutorAbsent SCUMSafeErrorCode = "probe_executor_absent"
-	SCUMSafeErrorProbeMissing        SCUMSafeErrorCode = "probe_missing"
-	SCUMSafeErrorProbeFailed         SCUMSafeErrorCode = "probe_failed"
-	SCUMSafeErrorSchemaIncompatible  SCUMSafeErrorCode = "schema_incompatible"
-	SCUMSafeErrorBindingMismatch     SCUMSafeErrorCode = "binding_mismatch"
-	SCUMSafeErrorAdapterMismatch     SCUMSafeErrorCode = "adapter_mismatch"
-	SCUMSafeErrorFingerprintMismatch SCUMSafeErrorCode = "fingerprint_mismatch"
-	SCUMSafeErrorDigestMismatch      SCUMSafeErrorCode = "digest_mismatch"
-	SCUMSafeErrorEvidenceExpired     SCUMSafeErrorCode = "evidence_expired"
-	SCUMSafeErrorInvalidProbePayload SCUMSafeErrorCode = "invalid_probe_payload"
-	SCUMSafeErrorInvalidRequest      SCUMSafeErrorCode = "invalid_request"
-	SCUMSafeErrorTargetUnavailable   SCUMSafeErrorCode = "target_unavailable"
-	SCUMSafeErrorSourceUnavailable   SCUMSafeErrorCode = "source_unavailable"
-	SCUMSafeErrorSQLiteOpenFailed    SCUMSafeErrorCode = "sqlite_open_failed"
-	SCUMSafeErrorSQLiteReadFailed    SCUMSafeErrorCode = "sqlite_read_failed"
-	SCUMSafeErrorDatabaseBusy        SCUMSafeErrorCode = "database_busy"
-	SCUMSafeErrorTimeout             SCUMSafeErrorCode = "timeout"
-	SCUMSafeErrorCancelled           SCUMSafeErrorCode = "cancelled"
-	SCUMSafeErrorSourceChanged       SCUMSafeErrorCode = "source_changed"
-	SCUMSafeErrorResultLimitExceeded SCUMSafeErrorCode = "result_limit_exceeded"
-	SCUMSafeErrorTemplateMissing     SCUMSafeErrorCode = "template_missing"
-	SCUMSafeErrorTemplateMismatch    SCUMSafeErrorCode = "template_digest_mismatch"
-	SCUMSafeErrorParameterInvalid    SCUMSafeErrorCode = "parameter_schema_invalid"
-	SCUMSafeErrorRowLimitExceeded    SCUMSafeErrorCode = "row_limit_exceeded"
-	SCUMSafeErrorResultSchemaInvalid SCUMSafeErrorCode = "result_schema_invalid"
+	SCUMSafeErrorNone                        SCUMSafeErrorCode = "none"
+	SCUMSafeErrorProbeExecutorAbsent         SCUMSafeErrorCode = "probe_executor_absent"
+	SCUMSafeErrorProbeMissing                SCUMSafeErrorCode = "probe_missing"
+	SCUMSafeErrorProbeFailed                 SCUMSafeErrorCode = "probe_failed"
+	SCUMSafeErrorSchemaIncompatible          SCUMSafeErrorCode = "schema_incompatible"
+	SCUMSafeErrorBindingMismatch             SCUMSafeErrorCode = "binding_mismatch"
+	SCUMSafeErrorAdapterMismatch             SCUMSafeErrorCode = "adapter_mismatch"
+	SCUMSafeErrorFingerprintMismatch         SCUMSafeErrorCode = "fingerprint_mismatch"
+	SCUMSafeErrorDigestMismatch              SCUMSafeErrorCode = "digest_mismatch"
+	SCUMSafeErrorEvidenceExpired             SCUMSafeErrorCode = "evidence_expired"
+	SCUMSafeErrorInvalidProbePayload         SCUMSafeErrorCode = "invalid_probe_payload"
+	SCUMSafeErrorInvalidRequest              SCUMSafeErrorCode = "invalid_request"
+	SCUMSafeErrorTargetUnavailable           SCUMSafeErrorCode = "target_unavailable"
+	SCUMSafeErrorSourceUnavailable           SCUMSafeErrorCode = "source_unavailable"
+	SCUMSafeErrorSQLiteOpenFailed            SCUMSafeErrorCode = "sqlite_open_failed"
+	SCUMSafeErrorSQLiteReadFailed            SCUMSafeErrorCode = "sqlite_read_failed"
+	SCUMSafeErrorDatabaseBusy                SCUMSafeErrorCode = "database_busy"
+	SCUMSafeErrorTimeout                     SCUMSafeErrorCode = "timeout"
+	SCUMSafeErrorCancelled                   SCUMSafeErrorCode = "cancelled"
+	SCUMSafeErrorSourceChanged               SCUMSafeErrorCode = "source_changed"
+	SCUMSafeErrorResultLimitExceeded         SCUMSafeErrorCode = "result_limit_exceeded"
+	SCUMSafeErrorTemplateMissing             SCUMSafeErrorCode = "template_missing"
+	SCUMSafeErrorTemplateMismatch            SCUMSafeErrorCode = "template_digest_mismatch"
+	SCUMSafeErrorParameterInvalid            SCUMSafeErrorCode = "parameter_schema_invalid"
+	SCUMSafeErrorRowLimitExceeded            SCUMSafeErrorCode = "row_limit_exceeded"
+	SCUMSafeErrorResultSchemaInvalid         SCUMSafeErrorCode = "result_schema_invalid"
+	SCUMSafeErrorMutationGuardMismatch       SCUMSafeErrorCode = "mutation_guard_mismatch"
+	SCUMSafeErrorMutationBackupUnavailable   SCUMSafeErrorCode = "mutation_backup_unavailable"
+	SCUMSafeErrorMutationOfflineRequired     SCUMSafeErrorCode = "mutation_offline_required"
+	SCUMSafeErrorMutationConfirmationMissing SCUMSafeErrorCode = "mutation_confirmation_missing"
+	SCUMSafeErrorMutationPatchInvalid        SCUMSafeErrorCode = "mutation_patch_invalid"
+	SCUMSafeErrorAffectedRowsMismatch        SCUMSafeErrorCode = "affected_rows_mismatch"
+	SCUMSafeErrorReadbackMismatch            SCUMSafeErrorCode = "readback_mismatch"
+	SCUMSafeErrorRollbackFailed              SCUMSafeErrorCode = "rollback_failed"
 )

 type SCUMTerminalResultStatus string
@@ -82,6 +90,15 @@ const (
 	SCUMRCONConfirmationUnknown   SCUMRCONConfirmationStatus = "unknown"
 )

+type SCUMMutationReadbackStatus string
+
+const (
+	SCUMMutationReadbackConfirmed SCUMMutationReadbackStatus = "confirmed"
+	SCUMMutationReadbackFailed    SCUMMutationReadbackStatus = "failed"
+	SCUMMutationReadbackConflict  SCUMMutationReadbackStatus = "conflict"
+	SCUMMutationReadbackUnknown   SCUMMutationReadbackStatus = "unknown"
+)
+
 type SCUMSafeError struct {
 	Code      SCUMSafeErrorCode
 	Message   string
@@ -137,6 +154,18 @@ func DefaultSCUMTypedRCONTemplateBounds() SCUMTypedRCONTemplateBounds {
 	return SCUMTypedRCONTemplateBounds{MaxPayloadBytes: 2048, TimeoutMS: 5000, MaxResponseBytes: 16 * 1024, MaxConfirmRecords: 16}
 }

+type SCUMGuardedMutationBounds struct {
+	MaxPayloadBytes  int
+	TimeoutMS        int
+	BusyTimeoutMS    int
+	MaxReadbackBytes int
+	MaxAffectedRows  int
+}
+
+func DefaultSCUMGuardedMutationBounds() SCUMGuardedMutationBounds {
+	return SCUMGuardedMutationBounds{MaxPayloadBytes: 4096, TimeoutMS: 5000, BusyTimeoutMS: 250, MaxReadbackBytes: 16 * 1024, MaxAffectedRows: 1}
+}
+
 type SCUMSchemaProbeRequest struct {
 	RequestID   string
 	JobID       string
@@ -182,6 +211,32 @@ type SCUMTypedRCONTemplateRequest struct {
 	RequestedAt               time.Time
 }

+type SCUMGuardedMutationRequest struct {
+	RequestID                 string
+	JobID                     string
+	Binding                   SCUMBindingIdentity
+	Capability                SCUMDataCapability
+	TargetKey                 string
+	TemplateKey               string
+	AdapterVersion            string
+	RequiredSchemaFingerprint string
+	AssetDigest               string
+	TargetIdentityDigest      string
+	ExpectedRowDigest         string
+	ExpectedValueDigest       string
+	ExpectedXMLDigest         string
+	PatchDigest               string
+	BackupEvidenceDigest      string
+	OfflineEvidenceDigest     string
+	DangerConfirmationDigest  string
+	ReadbackExpectationDigest string
+	IdempotencyKey            string
+	Payload                   map[string]any
+	ReviewReason              string
+	Bounds                    SCUMGuardedMutationBounds
+	RequestedAt               time.Time
+}
+
 type SCUMSchemaProbeDeclaration struct {
 	Capability string
 	TargetKey  string
@@ -296,6 +351,39 @@ type SCUMTypedRCONTemplateResult struct {
 	Limits               SCUMTypedRCONTemplateBounds
 }

+type SCUMGuardedMutationResult struct {
+	RequestID                 string
+	JobID                     string
+	Binding                   SCUMBindingIdentity
+	Status                    SCUMTerminalResultStatus
+	Capability                SCUMDataCapability
+	TargetKey                 string
+	TemplateKey               string
+	AdapterVersion            string
+	SchemaFingerprint         string
+	AssetDigest               string
+	SourceFingerprint         string
+	TargetIdentityDigest      string
+	ExpectedRowDigest         string
+	ExpectedValueDigest       string
+	ExpectedXMLDigest         string
+	PatchDigest               string
+	BackupEvidenceDigest      string
+	OfflineEvidenceDigest     string
+	DangerConfirmationDigest  string
+	ReadbackExpectationDigest string
+	ObservedAt                time.Time
+	ResultDigest              string
+	BeforeDigest              string
+	AfterDigest               string
+	ReadbackDigest            string
+	AffectedRows              int
+	ReadbackStatus            SCUMMutationReadbackStatus
+	SafeSummary               string
+	SafeError                 SCUMSafeError
+	Limits                    SCUMGuardedMutationBounds
+}
+
 type SCUMCapabilityRequirement struct {
 	Capability        SCUMDataCapability
 	AdapterVersion    string
@@ -406,6 +494,15 @@ func CopySCUMTypedRCONTemplateRequestPtr(value *SCUMTypedRCONTemplateRequest) *S
 	return &copy
 }

+func CopySCUMGuardedMutationRequestPtr(value *SCUMGuardedMutationRequest) *SCUMGuardedMutationRequest {
+	if value == nil {
+		return nil
+	}
+	copy := *value
+	copy.Payload = CopySCUMValueMap(value.Payload)
+	return &copy
+}
+
 func CopySCUMSQLiteTemplateResultPtr(value *SCUMSQLiteTemplateResult) *SCUMSQLiteTemplateResult {
 	if value == nil {
 		return nil
@@ -423,6 +520,14 @@ func CopySCUMTypedRCONTemplateResultPtr(value *SCUMTypedRCONTemplateResult) *SCU
 	return &copy
 }

+func CopySCUMGuardedMutationResultPtr(value *SCUMGuardedMutationResult) *SCUMGuardedMutationResult {
+	if value == nil {
+		return nil
+	}
+	copy := *value
+	return &copy
+}
+
 func CopySCUMValueMap(value map[string]any) map[string]any {
 	if value == nil {
 		return nil