git:20261028.6071f24 to git:20261101.8be107b

26 added, 68 removed. Audit A to A.

---

name: orbyn-backend-design

description: "Design and implement API/service behavior across validation, authorization, persistence, concurrency and client errors using the consuming project's stack. Use architect first for unsettled ownership; use orbyn-data-migration for stored-format changes."

---

# Backend contracts that reach the client

Start from the consuming project's instructions and actual API, transport and

domain owners. Use [how](../how/SKILL.md) to trace the existing request, and

[architect](../architect/SKILL.md) when ownership or lifecycle is undecided.

- Do not introduce Fastify, PostgreSQL, Zod or any other Orbyn stack component merely

- because it appears in an example.

- For service readiness or a material workload change, include the

- [operating contract](../architect/references/service-readiness.md): user completion

- indicator and observation window, demand/quota bounds, operator/recovery ownership,

- and data classification, retention/deletion and safe diagnostic fields. Put these

- in the returned criteria; unknown targets or policies remain unresolved gates.

- State the caller's input, allowed identity/scope, successful result and expected

- domain failures. Identify which reads establish authority/freshness and which

- write or external effect must preserve them. A parsed ID and a signed-in session

- do not prove access to the referenced tenant resource.

- Place parsing at the trust boundary and reuse the owning schema inside the

- service. Keep transactions around related persistence, with version conditions or

- locks where stale state matters. For external effects, define operation identity,

- unknown outcomes and reconciliation; do not hold a database transaction open

- while a remote provider decides. Preserve cancellation and cleanup ownership.

- Trace the result through the shared client and each affected UI. Errors should

- remain recognizable enough for a client to preserve its draft, explain the failure

- and retry deliberately. Avoid returning success for a rejected effect or exposing

- internal exceptions and credentials as UI copy.

- For example, moving a task between projects requires source/destination scope,

- stage compatibility, a concurrency condition and a consistent API result. Updating

- one route without its shared schema and mobile caller leaves the feature incomplete.

- When verification is authorized, check the legitimate outcome, denied access,

- stale update and relevant retry behavior at the owning boundary. Return the changed

- contract, affected callers, evidence and recovery limits. Hand persisted-format

- changes to [data migration](../orbyn-data-migration/SKILL.md), visible flows to

- [UI design](../orbyn-ui-design/SKILL.md), and coordinated work to

- [orbyn-workflow](../orbyn-workflow/SKILL.md).

- ## Worked example

- [Retrying an external effect](examples/retry-safe-effect.md) separates request

- identity, durable state and an unknown provider outcome in a synthetic task.

- Pair the effect contract with [language guidance](../language-best-practices/SKILL.md)

- for the actual service/runtime. Database syntax and isolation need the engine's

- SQL reference; language types alone do not prove transaction or authorization

- behavior. Choosing a replacement stack belongs to stack selection and architect,

- not an incidental service implementation.

- ## Production behavior and diagnostics

+ Use the project's own stack: do not introduce Fastify, PostgreSQL, Zod or any other

+ Orbyn stack component merely because it appears in an example.

- Use [production service contracts](references/service-contracts.md) for bounded input/work, error semantics, concurrency and stable pagination. Use [observability](references/observability.md) when the changed operation needs diagnosable phases and privacy-aware records; installing telemetry or a provider is a separate decision.

+ ## Method

- ## Boundary and retry rules

+ 1. **State the contract:** the caller's input, allowed identity/scope, successful result and expected domain failures.

+ 2. **Identify the authority reads:** which reads establish authority/freshness, and which write or external effect must preserve them. Check access to the referenced tenant resource; a parsed ID and a signed-in session do not prove it.

+ 3. **Validate at the trust boundary.** Place parsing there and reuse the owning schema inside the service. Express failures in the owning contract, and do not scatter defensive checks over already valid internal values.

+ 4. **Protect the write.** Keep transactions around related persistence, with version conditions or locks where stale state matters. Concurrent writers need application-level ownership or fencing; a Git worktree cannot isolate them.

+ 5. **Handle external effects.** Define operation identity, unknown outcomes and reconciliation, and do not hold a database transaction open while a remote provider decides. Retries, crashes and duplicate delivery need an explicit idempotency key, effect identity or recovery contract. Preserve cancellation and cleanup ownership.

+ 6. **Trace the result through the shared client and each affected UI.** Keep errors recognizable enough for a client to preserve its draft, explain the failure and retry deliberately. Never return success for a rejected effect or expose internal exceptions and credentials as UI copy.

+ 7. **Verify, when authorized,** the legitimate outcome, denied access, stale update and relevant retry behavior at the owning boundary.

+ 8. **Return** the changed contract, affected callers, evidence and recovery limits.

- For critical retry, lease or worker lifecycle rules, connect current effect

- boundaries to [statecharts](../architect/references/statecharts.md) and

- [property verification](../tdd/references/formal-verification.md) when justified.

- For example, a lost save response needs reconciliation/idempotency at the real

- backend boundary; a simulated preview cannot prove absence of duplicate effects.

+ For example, moving a task between projects requires source/destination scope, stage compatibility, a concurrency condition and a consistent API result. Updating one route without its shared schema and mobile caller leaves the feature incomplete. A lost save response needs reconciliation/idempotency at the real backend boundary; a simulated preview cannot prove absence of duplicate effects. [Retrying an external effect](examples/retry-safe-effect.md) separates request identity, durable state and an unknown provider outcome in a synthetic task.

- Validate at actual trust/effect boundaries and express failures in the owning

- contract; do not scatter defensive checks over already valid internal values.

- Retries, crashes and duplicate delivery need an explicit idempotency key, effect

- identity or recovery contract. Concurrent writers need application-level ownership

- or fencing; a Git worktree cannot isolate them. Use the

- [boundary method](references/principles/boundary-discipline.md) and

- [idempotency method](references/principles/make-operations-idempotent.md) for examples.

+ ## Hand off

- When a model proposes tool arguments or generated data, use

- [AI application engineering](../orbyn-ai-application/SKILL.md) for its context,

- quality and bounded-loop contract. This backend owner still enforces current

- authorization, semantic validation and durable effect identity outside the model.

+ - Persisted-format changes: [data migration](../orbyn-data-migration/SKILL.md).

+ - Visible flows: [UI design](../orbyn-ui-design/SKILL.md).

+ - Coordinated work: [orbyn-workflow](../orbyn-workflow/SKILL.md).

+ - Choosing a replacement stack: stack selection and architect, not an incidental service implementation.

+ - Model-proposed tool arguments or generated data: [AI application engineering](../orbyn-ai-application/SKILL.md) for context, quality and the bounded-loop contract. This backend owner still enforces current authorization, semantic validation and durable effect identity outside the model.

- ## Router API effects

+ ## Read when needed

- For supported Expo Router server endpoints, use [API route authority](references/expo-api-routes.md). Native/browser route state cannot establish server resource access.

+ - Service readiness or a material workload change: the [operating contract](../architect/references/service-readiness.md) covers the user completion indicator and observation window, demand/quota bounds, operator/recovery ownership, and data classification, retention/deletion and safe diagnostic fields. Put these in the returned criteria; unknown targets or policies remain unresolved gates.

+ - Actual service/runtime: [language guidance](../language-best-practices/SKILL.md). Database syntax and isolation need the engine's SQL reference; language types alone do not prove transaction or authorization behavior.

+ - Bounded input/work, error semantics, concurrency and stable pagination: [production service contracts](references/service-contracts.md).

+ - An operation needing diagnosable phases and privacy-aware records: [observability](references/observability.md). Installing telemetry or a provider is a separate decision.

+ - Critical retry, lease or worker lifecycle rules, when justified: connect current effect boundaries to [statecharts](../architect/references/statecharts.md) and [property verification](../tdd/references/formal-verification.md).

+ - Worked examples: the [boundary method](references/principles/boundary-discipline.md) and [idempotency method](references/principles/make-operations-idempotent.md).

+ - Supported Expo Router server endpoints: [API route authority](references/expo-api-routes.md). Native/browser route state cannot establish server resource access.