One Motion Under One Lease

Four Steps That Must Not Be Interleaved

Landing a finished piece of work is four things: commit it, push it, stamp the record that lives with the material, and write the log entry that says this happened. Any one of them alone is unremarkable. What matters is that no other landing may happen between them.

If another session slips a landing in between your commit and your stamp, the repository and the record now describe different histories, and nothing in either one says so. That is the worst class of data problem: silent, plausible, and discovered months later by someone trying to answer an unrelated question.

Be exact about what the lease buys, because it is easy to over-claim. It excludes other landings. It does not make the four steps atomic, and the difference is not academic: if your own process dies after the push and before either record write, you get the identical split history with nobody else involved. Serialization is not transactionality. What closes that remaining gap is not a bigger lock but a reconciliation pass — a view that walks the repository against the record and reports where the two disagree.

The Lease, and Why It Is Not a Lock

The mechanism is a lease held on the target repository for the duration of those four steps. Calling it a lease rather than a lock is not vocabulary fussiness — it names the property that matters, which is that a holder who never comes back can be taken off it.

A lock is held until released. A session that dies holding one has created a permanent outage, and the recovery is a human finding the stale lock and deciding it is safe to break. A lease is held until released, or until someone breaks it deliberately and the break is itself recorded, which turns "the holder never came back" from an incident into a delay. Given that these holders are interactive sessions on laptops that get closed, that distinction is load-bearing rather than theoretical.

Verification Is Part of the Motion Too

One more coupling belongs here: the landing refuses to proceed without a recorded passing verification for this unit of work. Not a suggestion in a document — the command looks for the event and exits if it is absent.

There is an override, and using it writes that fact into the record. That combination is the shape to aim for everywhere: the escape hatch exists, because a guard with no override gets removed the first time it is wrong at an awkward hour, and taking it is never invisible.

You could ask why the verification check lives inside the landing command at all, rather than as a separate step people are asked to run first. That separate arrangement is exactly the one that rotted in the previous track: when verification is independent of the landing, a step that costs nothing to skip eventually gets skipped. Rather than asking for the order to be honored, make the wrong order unable to proceed.

Group the steps that must agree with each other under one held lease, and give the lease a recorded way to be broken. The grouping is what keeps two records from telling different stories; the recorded break is what keeps a closed laptop from stopping everyone else's work until somebody investigates.

Code

The landing, with its couplings visible·python

def land(unit_id: int, note: str, force_unverified: bool = False):
    # 1. TEETH: no green verification, no landing. The override is
    #    itself recorded - possible, never accidental.
    if not has_passing_verification(unit_id) and not force_unverified:
        raise SystemExit("no passing verification logged - run it first")

    # 2. THE LEASE. Held across everything below. The holder is an
    #    interactive session on a laptop that can be closed mid-run,
    #    so recovery is an explicit break that LEAVES A RECORD - not a
    #    timer, which would also release a holder that is merely slow.
    lease = acquire_lease(repo="content")
    try:
        base = choose_base(repo)          # lesson 4 of this track
        sha = scoped_commit(repo, base,   # lesson 3 of this track
                            paths=pipeline["land_paths"], msg=note)
        push(repo)
        stamp_record(unit_id, sha, note)  # lives WITH the material
        write_log_entry(unit_id, "landed", commit=sha)
    finally:
        release_lease(lease)


# Why all four are inside: if another landing could interleave
# between `sha = ...` and `stamp_record(...)`, the repository and
# the record would describe different histories, and NEITHER of
# them would say so. Silent, plausible, found months later.

Exercise

Find a multi-step operation in your system where the steps write to different stores — a database and a search index, a repository and a ticket, a deployment and an announcement. Write down what a reader would conclude if the operation stopped between each pair of steps. Then decide which of those intermediate states you can tolerate and which need to be grouped under one held resource.

Hint

The dangerous intermediate states are the ones that look complete. A half-finished operation that leaves an obvious mess gets fixed; one that leaves two stores each internally consistent and mutually contradictory gets believed by both sides for months.

Four Steps That Must Not Be Interleaved

The Lease, and Why It Is Not a Lock

Verification Is Part of the Motion Too

Code

External links

Exercise

Progress

Comments 0