Step 13
Step 13 — Close partial failure and recovery as a cross-service contract
0 views
Table of contents
Step 13 — Close partial failure and recovery as a cross-service contract
When several services form one product, an HTTP 200 is not completion evidence. We must also close whether a batch processed every item, whether a migration really ran, whether a static client can reach a server-only capability, and whether the user knows what to do next.
The state table
| State | Data and operations meaning | User-facing behavior |
|---|---|---|
completed |
The expected set and all checks finished | Show the result normally |
skipped |
A complete result already exists | Show freshness and the check time |
partial |
Some dates, types, or upstream work failed | Separate successes from the retry scope |
failed |
A write, migration, or required capability failed | Show a safe code and offer retry |
unsupported |
The current platform has no server-owned capability | Explain the boundary and offer the web path |
Three boundaries
1. Validate completeness before writing generated data
If the LLM returns one item out of twelve, do not save one item and call it success. Compare the expected sign set, then upsert the exact batch in one transaction. Roll back on a database error so the next scheduler round can repair the incomplete state.
Read next: Complete horoscope batches and atomic upserts
2. Replay migrations fail closed
An integration test that only warns about a missing migration directory or failed SQL can make every entity test false-green. Stop immediately when the directory, SQL files, or any statement is missing or fails, and read SQL as explicit UTF-8.
Read next: Fail-closed migration replay
3. Static platforms do not call capabilities they do not have
The Tauri export has no Next.js BFF route. Instead of creating a mysterious 404 by calling /api/batch/init, return an explicit unsupported state and explain that the feature belongs to the server-owned web runtime.
Read next: The Tauri capability boundary
Acceptance evidence from five perspectives
- Product defines normal, partial, retry, and unsupported states with an owner.
- Design checks a table that does not hide the failed scope, plus focus and retry copy.
- Engineering leaves set validation, transactions, unique indexes, safe error codes, and contract tests.
- Users can tell whether the current result is complete and what retry will change.
- Operations can inspect scheduler outcomes, readiness, migration logs, release SHA, and rollback.
Completion checklist
- An incomplete batch is never skipped as complete.
- One database error rolls back the whole batch.
- Missing or failed migration SQL cannot produce a passing test run.
- Logical uniqueness for cache keys containing
NULLmatches the database upsert target. - Static clients return an explicit
unsupportedstate for server-only capabilities. - Public UI and operations logs use the same state names.
Mark the cross-service change complete only when this checklist and its execution evidence are attached to the release record.