Explain and resolve incomplete Builder source hydration

[3mdistal]

Problem

Builder-backed Content imports could finish with generic unavailable bodies even when the exact Builder entry still existed and intentionally contained no visual blocks. The retry loop erased the distinction between an empty body, a missing entry, permissions, transient reads, malformed payloads, and conversion failures, leaving users and operators without an actionable terminal reason.

Approach

Introduce a feature-flagged outcome contract at the exact Builder body-read boundary. A provider-confirmed empty body is a successful hydrated result. Every actual failure retains a typed reason, provider status, attempt count, and retryability; transient failures use bounded backoff, while changed upstream source data resets the retry schedule. The feature is off by default under content.builder-body-hydration-reasons.

What changed

• Added discriminated exact-entry read results and typed failures for missing, authentication, access, transient, malformed, unsupported, and conversion boundaries.
• Added additive, dialect-portable hydration evidence columns plus next_attempt_at for honest retry scheduling.
• Preserved legacy behavior while the flag is off; strict payload classification and reasoned terminal outcomes activate only under the flag.
• Show specific terminal evidence in both database preview and full-page Content editing surfaces, and hide retry actions when all failures are non-retryable.
• Added focused provider, queue/database, lifecycle, retry-backoff, and editor tests.

Product impact

• Chapter: Connect your sources
• Feature: content.feature.connect-your-sources
• Capability: content.source.adapters
• User promise: Every expected Builder item either becomes usable Content or exposes a specific reason and honest recovery path; intentionally empty Builder entries no longer look like failed imports.

Safety and operations

• Builder access remains read-only; this diff adds no Builder mutation path.
• Migration 85 is additive only. Existing rows retain their prior status and nullable evidence.
• Rollout is flag-gated and reversible by disabling content.builder-body-hydration-reasons; the new evidence columns can remain safely in place.
• Production acceptance, flag enablement, and disposable Content-fixture cleanup are intentionally post-integration Land assertions because beta/production publish from main. This draft PR does not merge, deploy, or change production flags.

Verification

• pnpm --filter content typecheck passes (with expected local-production database configuration warnings).
• 270 focused tests pass across exact reads, hydration queue/database behavior, lifecycle serialization, and both editor surfaces.
• pnpm guards passes all 63 repository guards.
• The full Content suite reaches 2,334 passing tests; one unrelated pre-existing roadmap capability projection test fails against the newer row-action contract, so this is not presented as a green full-suite run.
• Independent bounded review found five initial boundary issues; all were repaired, and final re-review reported no remaining blocker.

Review focus

• Does the strict body projection distinguish explicit empty blocks from malformed/missing body fields without weakening flag-off compatibility?
• Are terminal retryability and source-version recovery honest across automatic queue processing and user-visible actions?
• Are the additive schema and feature-flag rollback safe for mixed-version deployments?
• Do both editor surfaces preserve enough provider evidence for an actionable diagnosis without exposing sensitive data?