Effect boundaries fail loudly
An effect boundary is the point where work leaves the process and becomes
something other people observe: a package published, a row written, a file
generated, content propagated to other repositories, a release cut.
The contract:
On an effect boundary, partial success is failure. No catch-and-continue,
no defaulting to success on an unknown outcome. A degraded operation must fail
the operation, surface the delta, or emit an explicit degraded-mode signal.
Silent failure is the dominant recurring bug archetype across Cratis. The
2026-08-24 organization-wide review found one disease with six manifestations,
in the release action, the Arc proxy generator, Stage, the Chronicle container
host, Chronicle constraint enforcement, and corpus propagation. They are written
out in failure-archetypes.md; read them
before deciding that your case is different.
When you need this
- You are writing or reviewing a
catch around an operation with an effect —
publish, write, generate, copy, notify, tag, release.
- An operation processes a set and some members can fail independently: a
fan-out, a batch, a matrix, a per-file generator.
- A call returns an outcome you did not model: an unexpected status code, a
null, an empty result, a timeout.
- Two implementations of one interface exist and only one of them really
enforces the behavior — an in-memory or SQL sibling of a real store.
- A host, container, or long-running process can reach a "started" state while
the thing it started has already thrown.
When you do not
- Pure computation with no effect. A parser that returns a partial tree for
a caller that inspects it is not an effect boundary.
- A retry that will still report the final outcome truthfully. Retrying is
not swallowing; reporting success after the retries also failed is.
- A genuinely optional enrichment whose absence is stated in the result. An
optional cache warm that records
cache: skipped is a degraded-mode signal,
which is exactly what this contract asks for.
- Style, naming, or structure questions. Those belong to the C# and
TypeScript conventions.
- Deciding whether an operation should exist at all. That is a product or
scope ruling, not an error-handling one.
Steps
- Name the boundary before you write the handler. Say out loud what leaves
the process: which package, which rows, which files, which repositories.
If nothing leaves, this contract does not apply and you can stop here.
- Enumerate the outcomes the call can produce, including the ones you did not
design for. An unexpected status code, an empty response, and a timeout are
outcomes. A handler that maps everything it did not enumerate onto success is
the defect.
- Choose one of the three permitted responses to a degraded outcome, and say
which one you chose. Fail the operation; or complete and surface the delta
in the result; or emit an explicit degraded-mode signal the caller must
handle. Anything else is catch-and-continue.
- Make partial fan-out visible in the aggregate, not just in the log. Count
attempted, succeeded, and failed, and put all three in the returned result
and the summary line. "29 of 36 succeeded" and "36 of 36 succeeded" must not
produce the same output.
- Refuse to convert an unknown into a pass. An outcome the code could not
classify is
indeterminate. Report it as its own state; never roll it up
into the success count.
- Check the sibling implementations of the same interface. When a real
store enforces a constraint, its in-memory and SQL siblings must enforce the
same one or throw
NotSupported. A sibling that silently accepts what the
real one rejects makes every specification that uses it pass vacuously.
- Make the process state follow the work. If startup threw, the host is not
Running. A liveness or readiness state that survives a failed start is a
lie the orchestrator will believe.
- Plant the failure and watch it surface. Force the degraded outcome —
inject the status code, delete an input, fail one fan-out member — and
confirm the operation fails, the delta appears, or the degraded signal fires.
A boundary whose failure path was never executed is not known to have one.
What breaks
Every item below is a real Cratis defect, not an illustration. Detail and issue
references are in failure-archetypes.md.
- A swallowed conflict reported as a successful release. The release action
caught a 422 from a concurrent publish and reported the release as done. The
version was never published, and the only artifact that said so was a caught
exception nobody saw.
- A generator that degrades silently. The Arc proxy generator emitted fewer
proxies than its inputs implied and exited zero. The failure shows up much
later as a missing TypeScript type, far from the generator that dropped it.
- A renderer that quietly renders less. Stage produced degraded output on a
path that reported success, so the difference between correct output and
partial output was invisible at the boundary that produced it.
- A container that stays
Running after startup threw. The Chronicle host
reported healthy while the thing it hosts had already failed to start, so the
orchestrator kept routing to it.
- A constraint that only one implementation enforces. Chronicle unique
constraints were not enforced on the SQL and in-memory storage providers.
Every specification exercising them passed while proving nothing.
- A fan-out that succeeded 29 times out of 36 and said "done". Corpus
propagation aggregated per-target results into a single success, so seven
repositories silently did not receive the change.
The shared symptom: the failure is discovered downstream, by someone who
cannot see the boundary that caused it. That is what makes this archetype
expensive rather than merely annoying.
How it is proven
- The failure path was executed. Name the planted defect and the observed
result: the injected status code, the removed input, the failed fan-out
member — and what the operation did in response.
- Counts appear on success. The clean run reports how many subjects it
attempted and how many succeeded. A bare "OK" cannot be distinguished from a
run over an empty set.
- Exit codes carry the verdict.
0 ran clean, 1 found defects, 2 could
not run. A wrapper that exits 0 because the wrapper finished has thrown the
child's verdict away; check the child's status and, in a pipeline, the status
of every stage.
- The degraded signal is asserted, not just emitted. A specification reads
the delta or the degraded-mode field and fails when it is absent.
- Sibling implementations are covered by the same specification. The test
that proves the constraint runs against every implementation of the interface,
not only the one that enforces it.
1---2name: cratis-engineering-effect-boundaries-23description: Use when publication, persistence, generation or propagation could partially fail while reporting success. Not for ordinary style questions or specification authoring.4license: LICENSE5metadata:6 source: https://skillmd.com/skills/cratis/cratis-engineering-effect-boundaries-27---89# Effect boundaries fail loudly1011An **effect boundary** is the point where work leaves the process and becomes12something other people observe: a package published, a row written, a file13generated, content propagated to other repositories, a release cut.1415The contract:1617> On an effect boundary, **partial success is failure.** No catch-and-continue,18> no defaulting to success on an unknown outcome. A degraded operation must fail19> the operation, surface the delta, or emit an explicit degraded-mode signal.2021Silent failure is the dominant recurring bug archetype across Cratis. The222026-08-24 organization-wide review found one disease with six manifestations,23in the release action, the Arc proxy generator, Stage, the Chronicle container24host, Chronicle constraint enforcement, and corpus propagation. They are written25out in [failure-archetypes.md](references/failure-archetypes.md); read them26before deciding that your case is different.2728## When you need this2930- You are writing or reviewing a `catch` around an operation with an effect —31 publish, write, generate, copy, notify, tag, release.32- An operation processes a set and some members can fail independently: a33 fan-out, a batch, a matrix, a per-file generator.34- A call returns an outcome you did not model: an unexpected status code, a35 null, an empty result, a timeout.36- Two implementations of one interface exist and only one of them really37 enforces the behavior — an in-memory or SQL sibling of a real store.38- A host, container, or long-running process can reach a "started" state while39 the thing it started has already thrown.4041## When you do not4243- **Pure computation with no effect.** A parser that returns a partial tree for44 a caller that inspects it is not an effect boundary.45- **A retry that will still report the final outcome truthfully.** Retrying is46 not swallowing; reporting success after the retries also failed is.47- **A genuinely optional enrichment whose absence is stated in the result.** An48 optional cache warm that records `cache: skipped` is a degraded-mode signal,49 which is exactly what this contract asks for.50- **Style, naming, or structure questions.** Those belong to the C# and51 TypeScript conventions.52- **Deciding whether an operation should exist at all.** That is a product or53 scope ruling, not an error-handling one.5455## Steps56571. **Name the boundary before you write the handler.** Say out loud what leaves58 the process: which package, which rows, which files, which repositories.59 If nothing leaves, this contract does not apply and you can stop here.602. **Enumerate the outcomes the call can produce, including the ones you did not61 design for.** An unexpected status code, an empty response, and a timeout are62 outcomes. A handler that maps everything it did not enumerate onto success is63 the defect.643. **Choose one of the three permitted responses to a degraded outcome, and say65 which one you chose.** Fail the operation; or complete and surface the delta66 in the result; or emit an explicit degraded-mode signal the caller must67 handle. Anything else is catch-and-continue.684. **Make partial fan-out visible in the aggregate, not just in the log.** Count69 attempted, succeeded, and failed, and put all three in the returned result70 and the summary line. "29 of 36 succeeded" and "36 of 36 succeeded" must not71 produce the same output.725. **Refuse to convert an unknown into a pass.** An outcome the code could not73 classify is `indeterminate`. Report it as its own state; never roll it up74 into the success count.756. **Check the sibling implementations of the same interface.** When a real76 store enforces a constraint, its in-memory and SQL siblings must enforce the77 same one or throw `NotSupported`. A sibling that silently accepts what the78 real one rejects makes every specification that uses it pass vacuously.797. **Make the process state follow the work.** If startup threw, the host is not80 `Running`. A liveness or readiness state that survives a failed start is a81 lie the orchestrator will believe.828. **Plant the failure and watch it surface.** Force the degraded outcome —83 inject the status code, delete an input, fail one fan-out member — and84 confirm the operation fails, the delta appears, or the degraded signal fires.85 A boundary whose failure path was never executed is not known to have one.8687## What breaks8889Every item below is a real Cratis defect, not an illustration. Detail and issue90references are in [failure-archetypes.md](references/failure-archetypes.md).9192- **A swallowed conflict reported as a successful release.** The release action93 caught a 422 from a concurrent publish and reported the release as done. The94 version was never published, and the only artifact that said so was a caught95 exception nobody saw.96- **A generator that degrades silently.** The Arc proxy generator emitted fewer97 proxies than its inputs implied and exited zero. The failure shows up much98 later as a missing TypeScript type, far from the generator that dropped it.99- **A renderer that quietly renders less.** Stage produced degraded output on a100 path that reported success, so the difference between correct output and101 partial output was invisible at the boundary that produced it.102- **A container that stays `Running` after startup threw.** The Chronicle host103 reported healthy while the thing it hosts had already failed to start, so the104 orchestrator kept routing to it.105- **A constraint that only one implementation enforces.** Chronicle unique106 constraints were not enforced on the SQL and in-memory storage providers.107 Every specification exercising them passed while proving nothing.108- **A fan-out that succeeded 29 times out of 36 and said "done".** Corpus109 propagation aggregated per-target results into a single success, so seven110 repositories silently did not receive the change.111112The shared symptom: **the failure is discovered downstream, by someone who113cannot see the boundary that caused it.** That is what makes this archetype114expensive rather than merely annoying.115116## How it is proven117118- **The failure path was executed.** Name the planted defect and the observed119 result: the injected status code, the removed input, the failed fan-out120 member — and what the operation did in response.121- **Counts appear on success.** The clean run reports how many subjects it122 attempted and how many succeeded. A bare "OK" cannot be distinguished from a123 run over an empty set.124- **Exit codes carry the verdict.** `0` ran clean, `1` found defects, `2` could125 not run. A wrapper that exits `0` because the wrapper finished has thrown the126 child's verdict away; check the child's status and, in a pipeline, the status127 of every stage.128- **The degraded signal is asserted, not just emitted.** A specification reads129 the delta or the degraded-mode field and fails when it is absent.130- **Sibling implementations are covered by the same specification.** The test131 that proves the constraint runs against every implementation of the interface,132 not only the one that enforces it.