Skip to content

Reconcile the cutover sequence with the answer that forbids a resolution gap #229

Description

@iderex

docs/domain-cutover.md carries two steps written against a different answer to
entry 3 of #7 than the one that was taken. The runbook says so about itself,
repairs neither, and nothing on this board holds either of them, so the
departures live in a document rather than anywhere somebody is watching. A
contradiction a runbook has written down about its own sequence is the one that
gets found while the move is being performed.

The answer the two steps depart from

gh issue view 7 --repo Flowfin/site --json comments --jq '.comments[].body' \
  | grep -o 'Answer to entry 3, decided 2026-08-24:[^.]*\.'
Answer to entry 3, decided 2026-08-24: the new site goes live on a subdomain first, is proven there, and the cutover happens against a standing target - the catalogue address answers throughout, with no resolution gap.

Run 2026-09-02.

The window, which the runbook calls a contradiction rather than a reading

git show origin/main:docs/domain-cutover.md \
  | sed -n '/^The second is the window/,/^with no resolution gap/p'
The second is the window, and it is a contradiction rather than a reading. Step
5 releases the name from the old origin before step 6 claims it at the new one,
and says in its own words that from there until step 6 completes no published
site claims the name. The answer says the catalogue address answers throughout,
with no resolution gap. Both cannot hold as this sequence is written.

And why it is structural rather than an ordering mistake, in the same document:

git show origin/main:docs/domain-cutover.md \
  | sed -n '/^What makes it structural/,/^neither is chosen here/p'
What makes it structural rather than an ordering mistake is stated above under
`## What moves, and what does not`: one custom domain is attached to one
published site at a time, so the old site releases the name before the new one
can take it, and that is where the window comes from. That sentence is a claim
about how the host behaves rather than a measurement, and measuring it costs
performing the move once. So closing the window means either a route this
document has not found, or the clause that forbids the gap giving way, and
neither is chosen here.

Both run 2026-09-02 against f51005f.

The second departure, from the same answer and in the same section

git show origin/main:docs/domain-cutover.md \
  | sed -n '/^The first is the address the new site/,/^certificate this document does not wait for/p'
The first is the address the new site is proven at. Step 2 publishes it at the
address the host gives a project site, `https://flowfin.github.io/site/`, and
the answer says a subdomain. Whether the host's project address satisfies that
word or whether it asks for a name under `flowfin.dev` is not decided here, and
the difference is not cosmetic: a name under `flowfin.dev` is a second custom
domain, which is a settings action this document does not describe and a
certificate this document does not wait for.

Run 2026-09-02 against f51005f.

Nothing on this board holds either of them

The runbook declines both in its own closing section, and the only open issue
that mentions the cutover at all is the publish workflow:

git show origin/main:docs/domain-cutover.md | grep -n 'reconciling the two is not covered here'
366:one; reconciling the two is not covered here.
gh issue list --repo Flowfin/site --state open --limit 300 --json number,title,body \
  --jq '[.[] | select((.body + .title) | test("domain-cutover|resolution gap|cutover")) | .number]'
[58]

Both run 2026-09-02. #58's done-when is about which branch may publish, where
write permission sits, that the custom domain file is in what was published, and
what a failed run leaves behind. It says nothing about the order in which the
name moves between two published sites, so it does not hold either departure and
would close with both standing.

Why this is a decision rather than work

Closing the window means either a route the runbook has not found or the clause
forbidding the gap giving way, and the sentence the choice rests on is a claim
about how the host behaves rather than a measurement. Measuring it costs
performing the move once, which is the move this document exists to sequence, so
there is no reading of this tree that settles it and no cheap experiment that
settles it either.

The address in step 2 is the same shape at a smaller size. Whether the address
the host gives a project site satisfies the word subdomain in the answer, or
whether the answer asks for a name under flowfin.dev, is a reading of the
answer rather than of the tree. The two readings cost differently: the second is
a second custom domain, which is a settings action and a certificate wait the
runbook does not describe.

What it costs to leave as it is

The runbook is followed once, under time pressure, with the catalogue address at
stake. A step that contradicts a decision made a month earlier is discovered at
step 5 by whoever is performing it, and the choice then gets made in the minute
it is noticed rather than before the move starts. That is the failure this issue
exists to move earlier, and it is the reason the departure being written down is
not the same as it being held.

Done when

The window has one of its two answers and the runbook carries it: either the
sequence is rewritten to a route that keeps the catalogue address answered
throughout, with the step that releases the name changed to it, or the clause
forbidding the gap is superseded on #7 with the length of the window stated
rather than left as an unbounded one. And step 2 names the address the new site
is proven at, with a reading of whether that address is a subdomain in the
answer's sense, and where it is not, the settings action and the certificate wait
it adds are written into the sequence rather than met during it.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

blocked-on-a-decisionWaits on a decision that is not taken yet. No change to this tree moves it.questionFurther information is requested

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions