diff --git a/docs/architecture/ds01-activation-evidence.md b/docs/architecture/ds01-activation-evidence.md index 184e864..370e58b 100644 --- a/docs/architecture/ds01-activation-evidence.md +++ b/docs/architecture/ds01-activation-evidence.md @@ -30,7 +30,9 @@ v2 证据文档(`protocol_version=2`)字段。注意:台账行 `library_in | 字段 | 含义 | |---|---| -| `target_identity` / `target_fingerprint` | 目标身份与现场指纹(64 位 sha256 hex) | +| `target_identity` | 目标身份 | +| `target_fingerprint` | 维护窗口/部署目标指纹(64 位 sha256 hex),必须等于 journal 与维护行 | +| `restore_target_fingerprint` | 激活时对恢复目标(库/索引/桶)的实时观察指纹 | | `target_instance` | 治理库维护窗口的实例名,必须等于 journal 的 `source` | | `governance_database` | 当前治理库名,与 `current_database()` 比对 | | `protocol_build` | 必须是**运行中二进制**的 `version.DisplayVersion()` | @@ -51,7 +53,9 @@ v2 证据文档(`protocol_version=2`)字段。注意:台账行 `library_in - **A4 实例绑定**:journal `source` == 证据 `target_instance`,且 == 治理库 `library_instance_maintenance.instance`。 - **A5 作业绑定**:journal `job` == 证据 `maintenance_job` == 维护行 `owner_job_id`。 -- **A6 目标绑定**:journal `target_fingerprint` == 证据指纹 == 维护行指纹 == 调用方现场观察值。 +- **A6 目标绑定**:journal `target_fingerprint` == 证据 `target_fingerprint` == 维护行指纹; + 证据 `restore_target_fingerprint` == 调用方激活时对恢复目标的只读观察值。两者是 + 不同层(实例/部署 vs 内容/索引/桶身份),不能用一个值互相顶替。 - **A7 入口排空**:`ingress_closed=true`、`drain_verified=true`、gate `closed && drained && active_at_close==0`。 - **A8 后台静默**:`quiesce` 存在且 depth/pending_ops/unsettled 全 0、有合法 digest、 diff --git a/internal/libraryrelease/restore_dispatch_activation.go b/internal/libraryrelease/restore_dispatch_activation.go index 8b37f5d..36b01fd 100644 --- a/internal/libraryrelease/restore_dispatch_activation.go +++ b/internal/libraryrelease/restore_dispatch_activation.go @@ -40,9 +40,13 @@ type RestoreDispatchWriterDrain struct { } type RestoreDispatchActivationEvidence struct { - ProtocolVersion int `json:"protocol_version"` - TargetIdentity string `json:"target_identity"` + ProtocolVersion int `json:"protocol_version"` + TargetIdentity string `json:"target_identity"` + // TargetFingerprint 是维护窗口/部署目标指纹(journal 与治理库维护行记录的那一个); + // RestoreTargetFingerprint 是激活时对恢复目标内容/索引/桶的实时观察值。两者是不同层, + // 不能相互替代:前者绑定"动的是哪个实例",后者绑定"恢复要写的那个目标身份"。 TargetFingerprint string `json:"target_fingerprint"` + RestoreTargetFingerprint string `json:"restore_target_fingerprint"` TargetInstance string `json:"target_instance"` GovernanceDatabase string `json:"governance_database"` ProtocolBuild string `json:"protocol_build"` @@ -60,7 +64,8 @@ func (e RestoreDispatchActivationEvidence) Validate(now time.Time, maxAge time.D } for name, value := range map[string]string{ "target identity": e.TargetIdentity, "target fingerprint": e.TargetFingerprint, - "target instance": e.TargetInstance, "governance database": e.GovernanceDatabase, + "restore target fingerprint": e.RestoreTargetFingerprint, + "target instance": e.TargetInstance, "governance database": e.GovernanceDatabase, "protocol build": e.ProtocolBuild, "attested by": e.AttestedBy, "maintenance job": e.MaintenanceJob, "maintenance journal": e.MaintenanceJournal, "maintenance journal digest": e.MaintenanceJournalSHA256, @@ -69,8 +74,8 @@ func (e RestoreDispatchActivationEvidence) Validate(now time.Time, maxAge time.D return fmt.Errorf("restore dispatch activation evidence lacks %s", name) } } - if !isHex64(e.TargetFingerprint) { - return errors.New("restore dispatch activation target fingerprint is not a sha256 hex string") + if !isHex64(e.TargetFingerprint) || !isHex64(e.RestoreTargetFingerprint) { + return errors.New("restore dispatch activation target fingerprints are not sha256 hex strings") } if !isHex64(e.MaintenanceJournalSHA256) { return errors.New("restore dispatch activation maintenance journal digest is not a sha256 hex string") diff --git a/internal/platform/postgres/library_restore_dispatch_activation.go b/internal/platform/postgres/library_restore_dispatch_activation.go index 031285c..f0af1cc 100644 --- a/internal/platform/postgres/library_restore_dispatch_activation.go +++ b/internal/platform/postgres/library_restore_dispatch_activation.go @@ -37,6 +37,7 @@ type restoreDispatchVerifiedView struct { MaintenanceState string `json:"maintenance_state"` MaintenanceJournalSHA256 string `json:"maintenance_journal_sha256"` TargetFingerprint string `json:"target_fingerprint"` + RestoreTargetFingerprint string `json:"restore_target_fingerprint"` IngressGate restoreDispatchGateView `json:"ingress_gate"` Quiesce restoreDispatchQuiesceView `json:"quiesce"` Writers []restoreDispatchWriterView `json:"writers"` @@ -143,8 +144,11 @@ func (s *Store) verifyRestoreDispatchEvidence(ctx context.Context, evidence libr return verified, fmt.Errorf("restore dispatch activation evidence was produced by build %q, running build is %q", evidence.ProtocolBuild, build) } - if targetFingerprint != evidence.TargetFingerprint { - return verified, errors.New("restore dispatch activation evidence does not match the live target fingerprint") + // 维护窗口指纹与恢复目标指纹是两层:前者已与 journal/维护行比对,后者必须等于 + // 激活方刚刚对恢复目标做的那次只读观察。用一个值同时顶替两者会掩盖"配置指向 + // 另一个目标实例"的漂移。 + if targetFingerprint != evidence.RestoreTargetFingerprint { + return verified, errors.New("restore dispatch activation evidence does not match the live restore target fingerprint") } // 治理库维护行由维护链在开窗口时写入,不是激活调用方写的:用它把作业/实例/ @@ -220,6 +224,7 @@ FROM library_instance_maintenance WHERE instance=$1`, evidence.TargetInstance).S verified = restoreDispatchVerifiedView{ MaintenanceJob: journal.Job, MaintenanceSource: journal.Source, MaintenanceState: journal.State, MaintenanceJournalSHA256: journal.Digest, TargetFingerprint: journal.TargetFingerprint, + RestoreTargetFingerprint: evidence.RestoreTargetFingerprint, IngressGate: restoreDispatchGateView{Closed: journal.Gate.Closed, Drained: journal.Gate.Drained, ActiveAtClose: journal.Gate.ActiveAtClose, Served: journal.Gate.Served, Detail: journal.Gate.Detail}, Quiesce: restoreDispatchQuiesceView{Depth: journal.Quiesce.Depth, PendingOps: journal.Quiesce.PendingOps, diff --git a/internal/platform/postgres/library_restore_dispatch_test.go b/internal/platform/postgres/library_restore_dispatch_test.go index fe1ebce..c488d8b 100644 --- a/internal/platform/postgres/library_restore_dispatch_test.go +++ b/internal/platform/postgres/library_restore_dispatch_test.go @@ -442,7 +442,7 @@ func ds01ActivationEvidence(t *testing.T, store *Store, targetIdentity, fingerpr } return libraryrelease.RestoreDispatchActivationEvidence{ ProtocolVersion: 2, TargetIdentity: targetIdentity, TargetFingerprint: fingerprint, - TargetInstance: ds01TestInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(), + RestoreTargetFingerprint: fingerprint, TargetInstance: ds01TestInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(), AttestedBy: "ds01-test", AttestedAt: time.Now().UTC(), MaintenanceJob: job, MaintenanceJournal: job + ".json", MaintenanceJournalSHA256: journalDigest, Writers: []libraryrelease.RestoreDispatchWriterDrain{{Name: ds01TestWriter, Kind: "worker", InstanceID: ds01TestWriter}}, diff --git a/internal/releaseadapter/v071/formal_maintenance_recovery_r38_test.go b/internal/releaseadapter/v071/formal_maintenance_recovery_r38_test.go index bf47432..8046c88 100644 --- a/internal/releaseadapter/v071/formal_maintenance_recovery_r38_test.go +++ b/internal/releaseadapter/v071/formal_maintenance_recovery_r38_test.go @@ -426,8 +426,9 @@ FROM library_instance_maintenance WHERE instance=$1`, cfg.LibraryTargetInstance) if observeErr != nil { return "", nil, fmt.Errorf("observe live target: %w", observeErr) } - if recorded, _ := journal["target_fingerprint"].(string); fingerprint != recorded { - return "", nil, fmt.Errorf("live target fingerprint %s != maintenance window %s", fingerprint, recorded) + windowFingerprint, _ := journal["target_fingerprint"].(string) + if windowFingerprint == "" { + return "", nil, errors.New("maintenance journal has no target fingerprint") } build := version.DisplayVersion() if expected := os.Getenv("KG_R38_VERSION"); expected != "" && build != expected { @@ -440,8 +441,8 @@ FROM library_instance_maintenance WHERE instance=$1`, cfg.LibraryTargetInstance) journalSum := sha256.Sum256(rawJournal) now := time.Now().UTC() evidence := libraryrelease.RestoreDispatchActivationEvidence{ - ProtocolVersion: 2, TargetIdentity: cfg.LibraryTargetIdentity(), TargetFingerprint: fingerprint, - TargetInstance: cfg.LibraryTargetInstance, GovernanceDatabase: database, ProtocolBuild: build, + ProtocolVersion: 2, TargetIdentity: cfg.LibraryTargetIdentity(), TargetFingerprint: windowFingerprint, + RestoreTargetFingerprint: fingerprint, TargetInstance: cfg.LibraryTargetInstance, GovernanceDatabase: database, ProtocolBuild: build, AttestedBy: "r38-runner", AttestedAt: now, MaintenanceJob: job.ID, MaintenanceJournal: job.ID + ".json", MaintenanceJournalSHA256: hex.EncodeToString(journalSum[:]), Writers: writers, @@ -471,8 +472,9 @@ FROM library_index_restore_dispatch_activation WHERE target_identity=$1`, cfg.Li gate, _ := journal["gate"].(map[string]any) quiesce, _ := journal["quiesce"].(map[string]any) facts := map[string]any{ - "target": target, "fingerprint": fingerprint, "governance_database": database, - "maintenance_job": job.ID, "protocol_build": build, + "target": target, "fingerprint": fingerprint, "window_fingerprint": windowFingerprint, + "governance_database": database, + "maintenance_job": job.ID, "protocol_build": build, "journal_sha256": drainDigest, "activation_evidence_sha256": hex.EncodeToString(evidenceSum[:]), "journal_state": journal["state"], "gate": gate, "quiesce": quiesce, "writers": writers, "activated_at": activatedAt, "stored_evidence_bytes": len(stored), diff --git a/internal/releaseadapter/v071/library_index_ds01_test.go b/internal/releaseadapter/v071/library_index_ds01_test.go index 4f963fe..bb86c7d 100644 --- a/internal/releaseadapter/v071/library_index_ds01_test.go +++ b/internal/releaseadapter/v071/library_index_ds01_test.go @@ -600,7 +600,7 @@ WHERE instance=$1`, ds01TargetInstance, `["worker-ds01"]`, fingerprint); err != } evidence := libraryrelease.RestoreDispatchActivationEvidence{ ProtocolVersion: 2, TargetIdentity: targetIdentity, TargetFingerprint: fingerprint, - TargetInstance: ds01TargetInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(), + RestoreTargetFingerprint: fingerprint, TargetInstance: ds01TargetInstance, GovernanceDatabase: database, ProtocolBuild: version.DisplayVersion(), AttestedBy: "ds01-test", AttestedAt: now, MaintenanceJob: job, MaintenanceJournal: job + ".json", MaintenanceJournalSHA256: hex.EncodeToString(journalSum[:]),