Preflight Before the First Write

"Fail in the checklist, where nothing has happened yet — never in the middle of the chain, where half the world already moved."

Everything That Can Fail, Checked First

Birth performs irreversible external effects, so the cheapest place for it to fail is before the very first one. That's what preflight is: an exhaustive gate that must fully pass before any write. It validates a proper cwkPascalCase name and the fire-grammar naming policy; confirms the destination directory is absent; confirms the private GitHub name is available; confirms the template is readable and matches the v0 scaffold contract; confirms the roster and network ledgers are readable and writable; validates the requested port range and its HTTPS pairing; rejects any collision with every declared and observed family port; and acquires a birth lock for the member id. Only when all of that holds does the first byte get written.

Check the Whole World, Not Just the Ledger

One detail carries a lot of weight: the port-collision check rejects a clash with every declared and observed family port — not just what the ledger says is taken. A port can be free on paper but busy in reality, or reserved somewhere the ledger forgot. Preflight looks at both the declaration and the running world before blessing a new port, because a birth that grabs a port already in live use would create a conflict the moment the new service starts. Observed beats declared applies here too: the check isn't complete until it has looked.

Why Fail-Fast Is Kindness

Checking writability of the ledgers before creating the repo might feel paranoid — surely they're writable? But if the ledger turns out to be read-only after the remote already exists, you're stranded mid-chain with a repo on GitHub and no way to record it. Preflight's job is to move every knowable failure to the front, where the cost of failing is zero: nothing external has happened, nothing needs unwinding, the lock is released, and you try again. Fail-fast isn't pessimism; it's refusing to discover a fatal problem after it's expensive.

Front-load every knowable check before the first irreversible effect, and validate against the real world, not just the declaration. A failure in preflight costs nothing to recover from; the same failure discovered mid-chain leaves external side effects half-done. The most humane place to say no is before anything has happened.

Code

Preflight: an exhaustive gate before the first write·python

def preflight(request) -> None:
    # Every check here runs BEFORE any external effect. All must pass.
    validate_name(request.name)              # cwkPascalCase + fire-grammar policy
    assert_absent(request.destination)       # nothing already at the path
    assert_github_name_available(request.name)
    assert_template_ok()                     # readable + v0 scaffold contract:
                                             #   docs/APP-ARCHITECTURE.md, name tokens,
                                             #   schema-v1 cwk-product.json @ 0.0.0
    assert_ledgers_readable_and_writable()   # roster + network, BEFORE we need them
    validate_port_range(request.ports)       # range + HTTPS pairing
    reject_port_collision(request.ports,
                          declared_ports() | observed_ports())  # both worlds
    acquire_birth_lock(request.member_id)    # serialize this birth

    # Only after ALL of the above holds does Birth write its first byte.
    # A failure here costs nothing: no repo, no remote, no ledger change.

Exercise

Take a create-or-provision operation you know that does several irreversible things in sequence. List every precondition that, if false, would strand it halfway. Which of those are you currently checking upfront, and which do you only discover when a step fails mid-chain? Move at least one late-discovered failure into a preflight check, and note how it changes the cost of that failure from 'clean up a mess' to 'try again.'

Hint

The classic late failure is a permission or capacity check that only trips when you actually write — disk full, token expired, name taken. Any of those you can test read-only before the first write belongs in preflight, where failing is free.

Preflight Before the First Write

Everything That Can Fail, Checked First

Check the Whole World, Not Just the Ledger

Why Fail-Fast Is Kindness

Code

External links

Exercise

Progress

Comments 0