The Immutable Plan

"A plan you can edit while it runs is not a plan. It's a rumor."

What the Plan Freezes

An OperationPlan is a frozen snapshot of intent. It captures the source and destination references, the expected resource identities and metadata, the collision decision, the package-and-symlink policy, and a deterministic hash computed over all of it. Once created, it never changes. The engine reads it, journals it, and executes it — but nothing, including the engine, edits it in place while it's running.

Change Means a New Plan

So what happens when reality shifts — a collision appears that the plan didn't anticipate, or the user revises a decision? You don't mutate the running plan; that would make its hash a lie and its journal record meaningless. You create a new plan (or a revision), with its own hash and its own journal identity. The old plan is superseded, not secretly rewritten. Immutability is what makes 'what exactly did the app intend?' a question with a permanent, checkable answer.

Why the Hash Matters

The deterministic hash turns the plan into something verifiable. The journal records the hash; recovery can confirm the plan it's resuming is byte-for-byte the plan that was committed. Two runs of the same intent produce the same hash, so the system can recognize identity without guessing. Frozen intent plus a hash is what makes both recovery and auditing deterministic rather than best-effort.

The plan is immutable and hashed; changing conditions produce a new plan, never an edit. Frozen intent — sources, destinations, expected identities, collision decisions, policy — is a contract the engine executes and the journal records. A running plan is never rewritten; a revision is a new plan with a new identity.

Track cleared — the engine is built. One boundary, journal-first, a state machine, UI-can't-mutate, and an immutable hashed plan. Together they are the answer to the thesis from Track 1: this is the machinery that makes 'trustworthy mutation' more than a wish. Everything ahead — copy/verify/delete, collisions, coordination, recovery — runs on top of this engine.

Code

An immutable, hashed plan·swift

struct OperationPlan: Hashable {
    let id: OperationID
    let kind: OperationKind                 // copy, move, rename, trash, tag...
    let sources: [LocationReference]
    let destination: LocationReference?
    let expectedIdentities: [ResourceID]    // what we revalidate against
    let expectedMetadata: [MetadataSnapshot]
    let collision: CollisionDecision        // frozen, not inferred at runtime
    let traversalPolicy: TraversalPolicy    // packages atomic, symlinks as links
    let planHash: String                    // deterministic over all the above
    // NOTE: every field is `let`. There is no mutating method. On purpose.
}

// Reality changed? Don't edit -- supersede with a NEW plan:
func revise(_ old: OperationPlan, newCollision: CollisionDecision) -> OperationPlan {
    OperationPlan(from: old, collision: newCollision)   // fresh id, fresh hash
}

Exercise

Take a mutable 'request' or 'job' object from code you've written — one that gets fields set on it over its lifetime. List the ways it could be in an inconsistent state because two parts of the code edited it at different times. Then redesign it as an immutable value where any change produces a new version. What bug class did you just delete?

Hint

Mutable request objects invite 'partially configured' and 'edited after it started' bugs — the classic is a field changing between validation and use. Making it immutable means a change is a new object with its own identity, so 'the thing I validated is the thing that ran' becomes true by construction. That's the exact guarantee the plan hash gives Waygate.

What the Plan Freezes

Change Means a New Plan

Why the Hash Matters

Code

External links

Exercise

Progress

Comments 0