Documentation
¶
Overview ¶
Package upgrade runs the permanent final current-state upgrade: it verifies only the sealed facts of a bridge attestation and applies the cutover output plan through a recoverable journal. It ships no legacy inventory, approval parser, or cross-schema adapter; the sealed attestation is the sole trust anchor for the legacy adjudication the current-state binary can no longer recompute.
Index ¶
Constants ¶
const ( KindFile = "" KindResidentTree = "resident-tree" )
Operation kinds. An empty kind is a file replacement, so every journal written before resident quarantine existed keeps its exact meaning. A resident-tree operation moves a whole directory aside instead of imaging its bytes: a resident tree holds unbounded ephemeral descendants, so recording it as file images would be both enormous and lossy, and deleting it outright would leave nothing to roll back to.
const JournalVersion = 1
JournalVersion is the only accepted current-state upgrade journal schema.
Variables ¶
This section is empty.
Functions ¶
func JournalPath ¶
JournalPath returns the fixed journal path under root.
func JournalPresent ¶
JournalPresent reports whether a journal file exists under root. A fault is returned rather than folded into absence: answering "no journal" from a read that never completed would let the command-state guard permit the commands an unrecovered upgrade must block.
func QuarantineRel ¶ added in v0.30.0
func QuarantineRel() string
QuarantineRel is the repo-relative root every quarantined resident tree moves under. It sits inside the awf directory so one tracked-authority restore reaches it, and it is never a resident root itself.
func Verify ¶
Verify checks only the sealed facts of att: its version, that current HEAD equals the sealed PreparedHead, and that the recomputed tree digest equals the sealed TreeDigest. It reads the tree read-only. The sealed legacy adjudication is trusted through this unchanged seal alone, because the current-state binary ships no inventory, approval parser, or cross-schema adapter to recompute it.
Types ¶
type Evidence ¶ added in v0.30.0
Evidence is one ordered, terminally proven journal fact. It is collected by the transaction owner and rendered only at the command boundary.
type Image ¶
type Image struct {
Present bool `json:"present"`
Mode uint32 `json:"mode"`
Content []byte `json:"content"`
}
Image is one file's exact recorded state: present with an octal permission mode and content, or absent (present:false, mode 0, empty content).
type Journal ¶
type Journal struct {
Version int `json:"version"`
Phase string `json:"phase"`
FinalLockSHA256 string `json:"finalLockSHA256"`
Operations []Operation `json:"operations"`
}
Journal is the durable transaction record. Version is always 1; Operations are unique, sorted, and end with the lock operation; FinalLockSHA256 is the SHA-256 of the sealed lock content the transaction commits.
func LoadJournal ¶
LoadJournal reads and validates the journal under root. A malformed or contract-violating journal is a hard error naming the Git-restoration escape, so no caller mutates the tree on a journal it cannot trust.
func ParseJournal ¶
ParseJournal validates a journal captured from an immutable snapshot. It is the staged-check counterpart of LoadJournal, sharing the exact journal contract without materializing index bytes into the working tree.
type Operation ¶
type Operation struct {
Path string `json:"path"`
Kind string `json:"kind,omitempty"`
Prior Image `json:"prior"`
Replacement Image `json:"replacement"`
Quarantine string `json:"quarantine,omitempty"`
}
Operation records one path's prior and replacement images. The final journal operation is always the lock replacement. A resident-tree operation carries no images and instead names the quarantine path its tree is renamed to; the rename is the mutation, so it is reversible before the lock commits and only needs deleting after.
type Outcome ¶ added in v0.30.0
type Outcome struct {
// Evidence is the ordered history of proven transaction actions. It may
// include restored actions that are no longer true when the call returns.
Evidence []Evidence
// Changed names only axes still changed when the call returns. Failure
// diagnostics use this set, never historical Evidence.
Changed []Evidence
}
Outcome is the ordered terminal evidence from one journal operation.
func FinalUpgrade ¶
FinalUpgrade consumes a sealed bridge attestation. It verifies only the sealed facts, then journals the cutover output plan: the single deletion of the migration approval file and the lock replacement last, which drops the consumed attestation and discards its historical routing payload. The lock replacement is the transaction commit point; a pre-commit failure rolls back, a post-commit failure leaves a recoverable journal.
func Recover ¶
Recover applies the journal recovery decision table. It is the only project mode permitted while a journal exists.
func ResetLegacyResidents ¶ added in v0.30.0
ResetLegacyResidents commits a schema advance that discards resident state, as one journaled transaction: every already-proven legacy resident is quarantined, then the lock is replaced last. The lock replacement is the commit point in both directions - a failure before it restores every quarantined resident and leaves the old generation authoritative, and a failure after it discards them and leaves the new generation authoritative. No binary older than the new generation runs against this tree again from the moment that lock lands.
The residents must already have been proven obsolete by a read-only preflight; this function moves bytes and asks no questions about them. Only the schema generation is stamped, exactly as every other migration leaves the release version to the terminal sync; the generation alone is what makes an older binary refuse this tree.
func (Outcome) CompletedMutation ¶ added in v0.30.0
func (o Outcome) CompletedMutation() (presentation.Mutation, error)
CompletedMutation maps a successful final upgrade into its terminal presentation result.
func (Outcome) FailureDiagnostic ¶ added in v0.30.0
func (o Outcome) FailureDiagnostic(condition string, cause error) (presentation.Diagnostic, error)
FailureDiagnostic maps a failed journal operation into an actionable diagnostic using only axes still changed at return.
func (Outcome) RecoveredMutation ¶ added in v0.30.0
func (o Outcome) RecoveredMutation() (presentation.Mutation, error)
RecoveredMutation maps a successful journal recovery into its terminal presentation result.
Source Files