Prefix Seals and Suffix Seals

One Flag Was Doing Two Jobs

The first version of the seal was keyed to the pipeline. A pipeline was either restricted or it was not, and a single flag both armed the guard and drove the after-the-fact gate that checks nothing was written.

Those are different questions. The gate asks did this run edit the source. The guard asks has this session read it. Once you see the difference, the flag is obviously overloaded — and the cost of the overload was that three pipelines ran their most sensitive stage with no guard at all across more than a hundred delegations, while everyone believed the flag covered them.

The reason is worth following, because it is not carelessness. One of those pipelines has a late stage whose whole job is to reconcile facts across both languages, and reconciling means editing both — it writes the source, not merely reads it. So the pipeline could not carry the restricted flag, because the flag would have failed the write gate on work the contract requires. And since the flag was the only switch, the pipeline's earlier stage — which genuinely does forbid the source — inherited no guard. The fix was never to flip the flag; it was to stop asking one flag two questions.

Two Real Shapes, and Why Both Fall Out of One Rule

Replace the flag with a list: which stages close which inputs. Then arm the guard from the first restricted stage through the last, inclusive, and two different pipeline shapes appear on their own.

A repair pipeline restricts its early stages and opens the source at the end, so its sealed window is a prefix. A creation pipeline authors the source in the middle and only forbids it during the final cold pass, so its window is a suffix. Same rule, opposite shapes, no special cases in the code.

Inclusive, Because Context Is Cumulative

The window has to span from the first restricted stage to the last, covering everything in between — including stages that do not themselves restrict anything. A seal that lifted for a middle stage and came back down afterward would protect nothing, because whatever entered the working context during the gap is still sitting there when the restricted stage resumes. Contexts do not empty between stages, and any design that assumes they do is a design that only works on a whiteboard.

When one flag answers two questions, the pipeline that answers them differently is the one that silently loses its guard. Look for that pipeline first — it is the one whose contract makes an exception, and the exception is what makes the overload invisible until something goes wrong somewhere else entirely.

Code

One rule, two shapes·python

REPAIR = {
    "required_stages": ["diag", "plan-gate", "fix", "reconcile"],
    # `reconcile` must open the source by contract, so the window
    # STOPS before it.
    "ko_only_stages": ["diag", "fix"],
}

CREATE = {
    "required_stages": ["sweep", "plan-gate", "compose",
                        "register", "ko-cold"],
    # `compose` AUTHORS the source, so the window starts after it.
    "ko_only_stages": ["ko-cold"],
}


def window(pipe):
    idx = [pipe["required_stages"].index(s)
           for s in pipe["ko_only_stages"]]
    return min(idx), max(idx)


# REPAIR  -> (0, 2)  a PREFIX: sealed from the start, opens at the end
# CREATE  -> (4, 4)  a SUFFIX: open until the end, then sealed
#
# Note REPAIR's window covers stage 1 (`plan-gate`), which restricts
# nothing itself. That is deliberate and it is the whole point:
# anything read during `plan-gate` is still in context at `fix`.


def armed(pipe, stages_logged):
    lo, hi = window(pipe)
    here = len(stages_logged)              # position, from the log
    return lo <= here <= hi


# Which makes stage logging LOAD-BEARING: the log is the only signal
# the guard gets about position. Skip an entry and the seal lags
# behind the run - and the direction of that failure DEPENDS ON THE
# SHAPE. For a PREFIX it over-seals: you are blocked from work you
# were entitled to do, which is loud and repairable. For a SUFFIX it
# UNDER-seals: `here` never reaches 4, the cold pass runs
# unguarded, and nothing says so. The suffix shape is the weaker seal
# for this reason too, not only because the author wrote the source.

Exercise

Find a boolean flag in your own system that is read by two or more consumers, and write out the question each consumer is actually asking. If the questions are not identical, find the case where the correct answers diverge — there is usually exactly one — and check what that case currently does. That case is either broken or carrying a comment explaining why it is fine, and both outcomes are worth knowing.

Hint

Overloaded flags are easiest to spot by their name: anything phrased as a mode or a category rather than as an answer to a specific question. A flag named for what something IS will drift; a flag named for what it ANSWERS cannot be borrowed by a second consumer without someone noticing.

One Flag Was Doing Two Jobs

Two Real Shapes, and Why Both Fall Out of One Rule

Inclusive, Because Context Is Cumulative

Code

External links

Exercise

Progress

Comments 0