#17 A dead-lettered command gets a terminal processing_failed first, so Watcher isn't left waiting

[gregoryfoster]

Closes #17. Refs #1, CannObserv/watcher#325.

Why. Watcher's reaper now re-issues only while other content.derived facts flow (watcher#325, issuecomment-5958475061). A command Processor dead-letters at the escape cap used to get no fact. It would sit in flight, and Watcher's 'Processor not consuming' signal would fire against a healthy Processor in any quiet period.

What. At the cap, before dead-lettering a decodable command, the consumer publishes processing_failed with terminal=true, reason=extraction_error, and detail = dead-lettered: gave up on attempt 3: … (handler.publish_gave_up).

• No second fact. Skipped when this entry's fact already went out: a refused ack, or a dead-letter retried after the fact landed. Tracked in Consumer._fact_out and cleared on ack, dead-letter, or a deleted reclaim.
• A transient refusal leaves the entry pending (uncapped). A non-transient one is logged (failure fact refused) and the entry is dead-lettered anyway.
• Frames that are not commands get no fact, as before.
• Docs. Spec §4 (both escape rows, plus a new note) and DEPLOYMENT.md's dead-letter line are amended.

Tests (red first, c2ec537):

• the escape cap publishes one terminal fact, then dead-letters;
• a refused ack at the cap adds no failure fact;
• a transiently refused failure fact leaves the entry pending, then lands once;
• a retried dead-letter doesn't duplicate the fact;
• a non-transiently refused failure fact still dead-letters.

Full suite: 235 passed.

Conflicts: #18 also edits spec §4 (a different bullet). Whichever ships second gets rebased.

🤖 Generated with Claude Code