A handoff should also explain what is rejected, what can be repeated, which state owns the truth, how access changes take effect, and what an operator does when the result is uncertain.
01 / API CONTRACT
Name the caller, the state change, and the rejected paths.
Start with an observable business operation. A list of routes is not enough. Each write needs a caller, an authority boundary, a durable identity, a before-and-after state, and a response for invalid or unavailable conditions.
| Question | Review evidence | Stop if missing |
|---|---|---|
| Who may call? | Actor type, authentication method, tenant or organization, role, and required permission. | Possession of any valid token is treated as authority for every record. |
| What may change? | Allowed transition, required current state, validation rules, and durable record identity. | The endpoint can move an object into an undefined or irreversible state. |
| What may repeat? | Idempotency scope, request identity, replay result, conflict response, and retention period. | A network retry can create a second side effect. |
| What is accepted? | Named fixtures, expected status and body, stored state, audit evidence, and accountable reviewer. | Acceptance means only that a request returned 2xx. |
- Document public, authenticated, operator, and internal routes separately.
- Use explicit request and response schemas, bounds, and error objects.
- Distinguish validation failure, authentication failure, authorization failure, conflict, dependency failure, and unexpected failure.
- Expose health and readiness as different states when dependencies matter.
- Keep price, deadline, deployment access, and final acceptance outside the technical contract until the accountable owner approves them.
02 / DATA AND MIGRATIONS
Treat the database schema as a versioned operating dependency.
A service is not transferable when its database exists only as the current developer's local state. The candidate needs a known migration head, a clean install path, a rollback decision, and evidence that application expectations match the schema.
- Record the exact database engine and supported version range.
- Use one versioned migration path from an empty database to the current head.
- Check that model changes do not leave an ungenerated schema diff.
- Test the supported downgrade or document why rollback is a restore or forward-fix operation instead.
- Define ownership, nullability, uniqueness, foreign keys, indexes, timestamps, and deletion behavior for important records.
- Keep migration credentials and runtime credentials separate when their privileges differ.
- Document backup, restore, retention, and destructive-change approval as environment-specific release decisions.
A migration that succeeds on a populated developer database does not prove that a clean environment, an older supported state, or a restore path works. Test the exact path the next operator will use.
03 / IDENTITY AND ACCESS
Make current authorization state stronger than an old token.
Authentication establishes an identity. Authorization decides whether that identity may act on this tenant, record, and transition now. A handoff needs both, plus a way for revocation or role changes to take effect.
- Hash passwords with a current password-hashing scheme and never log plaintext credentials.
- Validate token algorithm, issuer, audience, subject, issued time, not-before time, expiry, and a unique token identifier as applicable.
- Keep token lifetime bounded and reject placeholder or weak signing secrets at startup.
- Recheck current user status or an equivalent revocation state for protected operations.
- Scope every read and write by the authorized tenant or organization, not only by a client-supplied record ID.
- Map roles to named operations and state transitions instead of scattering role-name comparisons through handlers.
- Test disabled users, changed roles, cross-tenant identifiers, missing ownership, and unauthorized transitions.
A valid identity is not permission to act on every object that can be named.
04 / SAFE WRITES
Define what happens when two attempts meet the same state.
Retries and concurrent requests are ordinary operating conditions. The backend should make an exact replay harmless, a changed replay visible, and an outdated update fail with enough information for a safe next decision.
- Bind each idempotency key to tenant, operation, actor, and a canonical request fingerprint.
- Serialize competing first writes where duplicate creation would be harmful.
- Return the original accepted result for an exact replay without repeating the side effect.
- Reject reuse of the same key for different content.
- Use an expected version, conditional update, or lock when a stale writer must not overwrite newer state.
- Keep the state transition and its idempotency or audit evidence in one transaction where practical.
- Test simultaneous exact requests, changed payloads, stale versions, dependency timeouts, and operator replay.
| Attempt | Expected behavior | Evidence |
|---|---|---|
| First valid write | Create or change one authorized object. | One committed state, one operation identity, one audit event. |
| Exact replay | Return the recorded result without repeating the write. | Same business result, replay marker, no second object. |
| Changed replay | Reject the key conflict. | No mutation and a specific conflict response. |
| Stale update | Reject or require an explicit merge decision. | Current version remains intact and the caller can recover safely. |
05 / EVIDENCE AND SECURITY
Leave enough evidence to investigate without copying the secret.
Useful operational evidence connects an actor, request, version, state transition, and outcome. It should not turn logs, fixtures, CI artifacts, or handoff notes into a second store of credentials or sensitive records.
- Record correlation, actor, tenant, operation, target, prior state, next state, outcome, and timestamp where justified.
- Protect audit records from ordinary update and deletion paths.
- Redact authorization headers, tokens, passwords, database URLs, cookies, personal data, and secret-bearing exception text.
- Use synthetic or sanitized fixtures for routine tests and public evidence.
- Fail closed when a required secret, database URL, issuer, audience, or environment boundary is absent or unsafe.
- Run tests with warnings promoted to failures when deprecated or ambiguous behavior would weaken the handoff.
- Separate a code review, dependency scan, penetration test, load test, and compliance assessment. None is implied by ordinary application tests.
Do not call a backend secure because authentication exists or because tests pass. State exactly which controls were exercised, in which environment, and which security, load, availability, and regulatory questions remain unanswered.
06 / RELEASE AND HANDOFF
Transfer a reproducible candidate and a clear operating decision.
The handoff candidate should be identifiable by version or hash, start without hidden developer state, and explain configuration, migrations, health, recovery, unsupported cases, and who makes the production decision.
- 01Freeze the candidate
Record the exact source revision, dependency lock, migration head, configuration contract, and artifact identity.
- 02Build a clean environment
Install declared dependencies and verify that secrets, caches, local databases, and developer files are not required implicitly.
- 03Run the acceptance set
Exercise ordinary, invalid, unauthorized, cross-tenant, duplicate, conflicting, unavailable, and recovery paths.
- 04Review the environment gap
List what was not exercised: container runtime, remote CI, cloud, load, backup restore, monitoring, incident response, security assessment, or live integrations.
- 05Assign the production decision
An accountable owner accepts the environment, remaining risks, access, release window, rollback, support, price, and schedule.
Do not hand over an unexplained database, a shared secret, an unbounded token, an unscoped query, an unsafe replay path, a mutable audit trail, or a deployment process that only works on one developer machine.
- API contract, migration path, configuration inventory, and supported environment are current.
- Test evidence is tied to the exact candidate and contains no secret material.
- Known limitations and unsupported paths are explicit.
- Health, readiness, logs, alerts, backup, restore, rollback, and escalation ownership are documented for the target environment.
- Production credentials are provisioned and controlled by the authorized owner.
- Commercial terms, deadline, support, contract, payment, and final acceptance remain separate owner decisions.
PRIVATE SELF-DIRECTED REFERENCE
FastAPI Backend Handoff Lab
This private reference is not client work. One loopback-only PostgreSQL 17.10 verification exercised an Alembic head-to-base-to-head round trip, two no-drift checks, JWT and Argon2 identity controls, database-backed revocation, tenant and role boundaries, optimistic versions, concurrent idempotency, append-only audit enforcement, 17 warning-free tests, and HTTP 200 health and OpenAPI probes. It does not prove production readiness, container or remote-CI execution, cloud delivery, load or uptime, a security audit, regulatory compliance, or business results. The source is not publicly released.