Documentation
¶
Overview ¶
Package upgrade plans supported live-schema migrations and applies their output through a root-confined recoverable journal. The journal publishes the replacement lock last and preserves rollback, quarantine, postcommit cleanup, and recovery without interpreting historical authority.
Index ¶
- Constants
- func JournalPresent(root string) (bool, error)
- func LockRel() string
- func QuarantineRel() string
- type CurrentSchemaChange
- type Evidence
- type FileMutation
- type Gate
- type Image
- type Journal
- type LiveSchemaRange
- type Migration
- type MigrationResult
- type Operation
- type OperationOutcome
- type Outcome
- type ProjectPresent
- type SchemaGate
- type Sync
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 JournalRel = config.DirName + "/current-state-upgrade.journal"
JournalRel is the fixed repo-relative current-state upgrade journal path.
const JournalVersion = 1
JournalVersion is the only accepted current-state upgrade journal schema.
Variables ¶
This section is empty.
Functions ¶
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.
Types ¶
type CurrentSchemaChange ¶ added in v0.40.0
type CurrentSchemaChange func() string
CurrentSchemaChange describes stamping the current schema generation.
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 FileMutation ¶ added in v0.40.0
FileMutation is one journal-owned replacement or removal.
type Gate ¶ added in v0.40.0
Gate verifies that the selected binary may operate on the project. It is composed by the command because command execution owns the concrete gate.
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 LiveSchemaRange ¶ added in v0.40.0
type LiveSchemaRange func() (floor, current int)
LiveSchemaRange supplies the migrate-owned live compatibility bounds.
type Migration ¶ added in v0.40.0
type Migration func(context.Context, string) (MigrationResult, error)
Migration applies the migration sequence and returns its semantic results.
type MigrationResult ¶ added in v0.40.0
type MigrationResult struct {
Applied []string
Changes []string
Mutations []FileMutation
}
MigrationResult records applied migration steps and user-facing changes.
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 OperationOutcome ¶ added in v0.40.0
type OperationOutcome struct {
Document presentation.Document
}
OperationOutcome is the semantic presentation result of an upgrade operation.
func RecoverOperation ¶ added in v0.40.0
func RecoverOperation(root string, present ProjectPresent) (OperationOutcome, error)
RecoverOperation replays an interrupted upgrade transaction and maps its terminal evidence into the operation's presentation result.
func Run ¶ added in v0.40.0
func Run(ctx context.Context, root string, sync Sync, gate Gate, present ProjectPresent, liveSchemaRange LiveSchemaRange, schemaGate SchemaGate, migrate Migration, currentSchemaChange CurrentSchemaChange) (OperationOutcome, error)
Run executes the normal upgrade use case. Migration, authority and journal coordination live here; cmd/awf supplies only its concrete terminal sync and gate dependencies.
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 Recover ¶
Recover applies the journal recovery decision table. It is the only project mode permitted while a journal exists.
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.
type ProjectPresent ¶ added in v0.40.0
ProjectPresent reports whether root contains an awf project and preserves inspection failures rather than treating an unreadable authority path as absent.
type SchemaGate ¶ added in v0.40.0
SchemaGate reports root's migration relation and schema generation.
Source Files