Struct Plan 

#[non_exhaustive]
pub struct Plan {
    pub schema_version: SchemaVersion,
    pub platform: Platform,
    pub patches: Vec<PatchRef>,
    pub targets: Vec<Target>,
    pub fs_ops: Vec<FilesystemOp>,
}

Complete write plan for a chain of one or more source patches.

Schema versioning

Under the serde feature, every Plan carries a schema_version: u32 that records the in-memory layout this build emits. The current value is exposed as Plan::CURRENT_SCHEMA_VERSION and is currently 1.

Compatibility policy: the schema version is bumped any time a new required field is added to Plan or any of the types it transitively contains. Additive optional fields (defaulted via #[serde(default)]) do not bump the version. On deserialize, a Plan whose persisted schema_version does not equal Plan::CURRENT_SCHEMA_VERSION is rejected with crate::IndexError::SchemaVersionMismatch — older readers refuse to silently drop fields they cannot represent, rather than risk an apply against a partial plan. Callers persisting plans across crate-version boundaries should be prepared to rebuild the plan from the patch chain on mismatch.

#[non_exhaustive]: the top-level plan owns the schema-version contract; new persisted fields land here under that contract.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

schema_version: SchemaVersion

Schema-format version of this persisted plan. See the type-level docs for the compatibility policy. New plans constructed via Plan::new / PlanBuilder always carry Plan::CURRENT_SCHEMA_VERSION.

platform: Platform

Target platform pinned by the chain’s most recent SqpkTargetInfo chunk. Defaults to Platform::Win32 when no TargetInfo is seen.

patches: Vec<PatchRef>

Source patches in chain order. PartSource::Patch::patch_idx indexes into this vector; the applier asks the caller’s crate::index::PatchSource for bytes by (patch_idx, offset).

targets: Vec<Target>

Per-target write timelines, reflecting the chain’s end state — regions killed by a mid-chain RemoveAll, DeleteFile, or AddFile@0 are dropped at build time, not at apply time.

fs_ops: Vec<FilesystemOp>

Filesystem operations to run before any region writes, in chain order. Destructive ops (DeleteFile, DeleteDir, RemoveAllInExpansion) are preserved so that the applier still removes any pre-chain artefacts that the plan’s region set does not re-create.

Implementations

impl Plan

pub const CURRENT_SCHEMA_VERSION: SchemaVersion

Current on-disk schema version for Plan under the serde feature. See the type-level docs for the compatibility policy.

pub fn check_schema_version(&self) -> Result<()>

Validate that self.schema_version matches Self::CURRENT_SCHEMA_VERSION. Intended to be called by consumers immediately after deserializing a Plan from persistent storage, before handing it to the applier or verifier.

Errors

Returns crate::IndexError::SchemaVersionMismatch when the persisted version does not equal Self::CURRENT_SCHEMA_VERSION.

pub fn new( platform: Platform, patches: Vec<PatchRef>, targets: Vec<Target>, fs_ops: Vec<FilesystemOp>, ) -> Self

Construct a Plan from its component parts.

Exists so callers outside this crate can still build synthetic plans after the struct picked up #[non_exhaustive] for SemVer hygiene — in-crate code may continue to use the struct literal form directly. The constructed plan always carries Plan::CURRENT_SCHEMA_VERSION.

pub fn with_crc32<S: PatchSource>(self, source: &mut S) -> Result<Self>

Consume this plan, walk every region, and return a new plan in which every applicable region’s PartExpected has been replaced with PartExpected::Crc32 of the region’s effective output bytes.

Consumes self and returns the populated plan so the mutation is honest at the type level — there’s no in-place “compute” call that silently rewrites an outwardly-immutable-looking data type. Pairs with the PlanBuilder::finish() -> Plan owned-builder style.

• PartSource::Patch regions read the source bytes via source and, for PatchSourceKind::Deflated sources, decompress them in full before slicing the [decoded_skip..decoded_skip + region.length] window and CRC32-ing the slice. A single shared flate2::Decompress is reused across every Deflated region.
• PartSource::Zeros regions use the canonical all-zero payload, cached per-length so plans with many same-sized Zeros regions hit crc32fast::hash once per unique length.
• PartSource::EmptyBlock regions use the canonical empty-block payload the apply layer’s internal write_empty_block helper produces (a 20-byte SqPack empty-block header followed by units * 128 - 20 zero bytes), cached per-units.
• PartSource::Unavailable regions are left with their existing PartExpected (typically PartExpected::SizeOnly). A single tracing::warn! summary fires per call with the total count of skipped regions — per-region tracing happens at trace!.

Once populated, crate::index::PlanVerifier uses PartExpected::Crc32 to detect single-byte damage inside Patch regions, which the v1 size-only policy missed.

Errors

Surfaces any crate::IndexError produced by source.read or by DEFLATE decompression of a Patch region’s bytes. On error the original plan is dropped; callers that need to retry must hold an independent copy.

Atomicity

All-or-nothing: on Ok, every applicable region in the returned plan carries a fresh PartExpected::Crc32; on Err, no partially-mutated plan is observable — the input was consumed and the staging buffer is dropped without being flushed.

pub fn crc32(&self) -> u32

Stable CRC32 identity over this plan’s structural content.

Used by IndexedCheckpoint::plan_crc32 and crate::index::IndexApplier::resume_execute to detect a checkpoint that was persisted against a different plan revision than the one a resume call is given. The CRC is computed from a fixed, deterministically-ordered byte feed of every field that affects which bytes the applier writes — schema version, platform, patch chain, every target’s path and region timeline (including PartSource / PartExpected discriminants and payload), and the fs_ops list. The encoding does not match any serde format on purpose: we hash directly so the result stays stable regardless of which serializer the consumer picks for on-disk persistence.

Not cryptographic — collision space is 32 bits and the function is trivial to forge. Stale-detection only; never use this as an authentication or integrity check.

0 is a legitimate output value. CRC32 is uniform over u32 and a real plan can hash to zero; consumers must represent the “no checkpoint yet” state via Option<IndexedCheckpoint> rather than a sentinel plan_crc32: 0. See IndexedCheckpoint::plan_crc32 for the matching field doc.

Trait Implementations

impl Clone for Plan

fn clone(&self) -> Plan

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Plan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Plan

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Plan

fn eq(&self, other: &Plan) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Plan

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Plan

impl StructuralPartialEq for Plan