0005: Diagnostic request resources

• ID: PRD-0005
• Status: Accepted
• Decision maker: Trevor Gerhardt
• Scope: Auth, Persistence, Contracts, API, and SDK
• Product owner: Trevor Gerhardt
• Design owner: Trevor Gerhardt
• Engineering owner: Trevor Gerhardt
• Last reviewed: 2026-09-25
• Related issues or projects: Effect migration review
• Related designs: N/A; this change adds no screens
• Related ADRs: HTTP contract, Effect composition
• Related user documentation: API resources, generated SDK

Summary

Record each explicit invitation re-delivery and administrator password-reset request so an authorized operator can inspect what the provider acknowledged. The operation remains synchronous. A record does not promise recipient delivery.

User problem and evidence

A failed or interrupted provider call can leave an operator unsure whether a request was attempted. The approved migration plan requests a durable identifier and safe outcome that can be inspected without sending another message. Existing audit events retain their meaning and retention policy.

Goals and success measures

Non-goals

• Screens, workers, automatic retries, or polling infrastructure.
• Changing initial invitation creation.
• Proving that a recipient received or read a message.

Users and use cases

Use case: Diagnose an explicit attempt

• Actor: An operator authorized for the corresponding command and target.
• Need: Inspect whether a delivery request was recorded and acknowledged.
• Goal: Decide what to do next without accidentally repeating the attempt.

Requirements

PRD-0005-US-01: Record and inspect invitation re-delivery

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an authorized organization operator, I want to inspect an invitation re-delivery attempt, so that I can diagnose a reported failure.
• Requirement: Each explicit re-delivery POST creates a durable request before contacting the provider.
• Done when:
  • Creation returns the request ID on success. Failure after creation includes that ID in the declared error.
  • Authorized collection and individual reads expose the record with bounded cursor pagination.
  • Command and history apply the same authoritative role and target restrictions.
  • Each POST is a new attempt and remains subject to existing rate limits.
  • Initial invitation creation retains its existing behavior.

PRD-0005-US-02: Record and inspect administrator password-reset requests

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an authorized administrator, I want to inspect a password-reset request, so that I can distinguish a provider failure from an account that needs no password email.
• Requirement: Each administrator reset POST records an attempt before provider work, including the no-password case.
• Done when:
  • The command and history enforce the existing administrator and target restrictions.
  • Successful creation returns an ID; later failure includes that ID in the declared error.
  • An account without password credentials records not-applicable and requires no delivery.
  • Collection and individual reads use the same bounded pagination and privacy rules as invitation deliveries.

PRD-0005-US-03: Preserve safe, durable outcomes

• Story status: Current
• Replaces: N/A
• Replaced by: N/A
• User need: As an operator, I want outcomes that reflect known evidence, so that an ambiguous result does not cause an unintended duplicate message.
• Requirement: Store safe diagnostic facts with target-based retention.
• Done when:
  • unconfirmed means no definitive provider outcome was recorded, including interruption or ambiguity.
  • accepted means the provider acknowledged the request; it does not assert recipient delivery.
  • failed means a definite rejection occurred. not-applicable applies to password reset without password credentials.
  • Failure to save a terminal outcome leaves unconfirmed and never repeats the provider call.
  • Separate tables retain identifiers, initiating actor, timestamps, safe outcome codes, and request correlation.
  • Records contain no email bodies, reset tokens, credentials, or raw provider errors.
  • Target deletion cascades to its diagnostic records. Audit retention remains independent.
  • Existing audit events retain their meaning and include request correlation where applicable.

Implementation

Auth stores explicit invitation re-delivery and administrator password-reset attempts. The shared HTTP declaration exposes creation and history through the API and SDK. Repository and API integration tests cover outcomes, access, pagination, and failure IDs.

Experience and content

The API and SDK provide creation, collection reads, and individual reads. An empty collection is a valid result. Errors use safe messages and include the request ID when a record exists. Unauthorized readers gain no broader access through history. No screen or new accessibility interaction is included in this change.

Constraints and dependencies

• Requests execute synchronously. Framework boundaries must retain the lifetime of work that requires completion.
• Existing authorization, audit, and rate-limit requirements remain applicable.
• The API guide lists resource paths. ADR 0004 owns the shared declaration boundary.

User documentation

• Audience: API and SDK operators.
• Tasks to explain: Create an explicit attempt and inspect its outcome by ID.
• Agreed terms: Request, unconfirmed, accepted, failed, not-applicable.
• Examples needed: Successful creation, failure with an ID, and a paginated history read.
• Published documentation: API resource examples and SDK use.

Revision history

• 2026-09-25 — PRD-0005-US-01 through PRD-0005-US-03: Replace the delivery notes with a summary of the current implementation, and accept the implemented stories. PR #168

References

• Effect migration review