go-queue-failure-reason-persistence

Answer

I've written the solution to /workspace/solution.md. Here's a recap of what it contains and the one environment caveat you should know about.

Important environment note

The source repository for this problem is not mounted in this environment — /workspace contains only problem.json, and a filesystem-wide search for MarkFailed, entryToWire, queue_entries, or queue.sql returned no Go source. So I could not apply the patch to a live tree. I reconstructed the landed fix from the specification and empirically validated the two non-obvious mechanisms with runnable checks.

Deliverable: /workspace/solution.md

• Root cause: a five-layer data-loss chain — MarkFailed discarded reason, the column didn't exist, scanEntry never read it, all four explicit SELECTs omitted it, and the wire/OpenAPI layer never exposed it. Also ReapStale failed rows with no reason.
• Exact fix, keyed to the names in the change:
• failure_reason TEXT NOT NULL DEFAULT '' appended to queue.sql
• Idempotent ALTER TABLE ADD COLUMN in Open() swallowing only duplicate column name
• MarkFailed sets failure_reason = ? through a rune-boundary-safe 4000-byte capFailureReason
• Entry.FailureReason + appended scan arg
• Appended to Get / List / Dequeue / findPendingDuplicate without reordering
• entryToWire with json:"failure_reason,omitempty"
• ReapStale stamps a stale-reap reason
• OpenAPI QueueEntry.failure_reason using inline scalars only, asserted via api.JSONBytes()
• Verification: build/vet/test, migration idempotency + old-DB upgrade, rune-boundary unit test, persistence round-trip, ReapStale assertion, end-to-end curl (including has("failure_reason") == false for successful entries), and the parsed-spec assertion.

Empirical validation performed

• Rune cap: capFailureReason on 3-byte runes returned 3999 bytes (trimmed one partial byte), on 4-byte runes returned exactly 4000, both valid UTF-8, short strings untouched.
• Migration: SQLite raises duplicate column name: <col> on the second ALTER TABLE, confirming the substring match isDuplicateColumn must use; inserts/reads of the new column succeed.