fix: complete unified event contract

[cmilesio]

What

This focused follow-up carries the final event-contract work that completed after #4 was squash-merged.

It:

• completes the README and detailed event reference for all 32 public event kinds
• emits process_archived only after SQL proves that its fenced transition to dead committed
• keeps SQS, RabbitMQ, Redis, NATS, and local runtimes from claiming an archive boundary they cannot prove
• documents SQL process_recovered as one identity-free count fact per row changed by bulk recovery
• serializes observed pause and resume calls and treats StatsCollector.Paused as a zero-or-one gauge
• adds package-wide source-to-doc parity, internal workflow kind parity, exact adapter field-shape contracts, SQL settlement failure matrices, and driver omission checks
• moves the living roadmap from plan.md to docs/plan.md and updates historical documentation links
• stabilizes the RabbitMQ uniqueness contract so publisher-confirmation latency cannot consume the lease before the duplicate assertion
• refreshes generated evidence to 978 root unit executions and 631 all-backend integration executions

Boundary	Before	Now
Public catalog	29 of 32 event kinds were listed	All 32 kinds have exact names, layers, meanings, and detailed semantics
Archive fact	Reserved publicly but not truthfully emitted	SQL emits only after one fenced dead update commits
Broker archival	Settlement success could be mistaken for irreversible archival	SQS and RabbitMQ explicitly omit the stronger archive fact
Catalog drift	Source, README, detailed docs, and internal workflow kinds could diverge	Package-wide contracts reject missing, duplicate, unknown, mis-layered, or unmapped kinds
Pause metrics	Repeated idempotent pause calls accumulated a counter	Pause state is a serialized zero-or-one gauge
Living plan	Roadmap lived at repository root	Roadmap lives with the rest of the documentation in docs/plan.md

The SQL archive boundary is now explicit in code:

 if settlementErr != nil {
     d.handleSettlementFailure(ctx, job, settlementErr)
     return
 }
 settlement.Commit()
+if err != nil {
+    d.observeConfirmedProcessArchive(ctx, job, err)
+}

flowchart LR
  OBS["queue.Observer"] --> LAYER{"Event.Layer"}
  LAYER --> QUEUE["queue facts"]
  LAYER --> WORKER["worker facts"]
  LAYER --> WORKFLOW["workflow facts"]

  WORKER --> FAILURE["terminal SQL handler failure"]
  FAILURE --> FENCE{"fenced dead update committed?"}
  FENCE -->|Yes| ARCHIVE["process_archived"]
  FENCE -->|No| SETTLEMENT["settlement_failed"]
  BROKERS["SQS, RabbitMQ, Redis, NATS, local"] --> OMIT["omit process_archived"]

Loading

There is no source/API, configuration, persisted-data, wire-format, or minimum-Go-version change. Runtime observation changes are intentional: terminal SQL failures add one confirmed archive fact, and collected pause state is now a gauge.

Why

PR #4 unified the queue and workflow observer models, but the human event catalog remained incomplete and one reserved event had no reliable built-in producer. That left consumers unable to tell which facts were guaranteed, which fields were available, and where driver settlement stopped short of irreversible archival.

This follow-up makes the documentation and implementation one enforceable contract. Future event additions, internal workflow additions, or adapter fields cannot silently bypass the public reference, and drivers only publish the strongest fact they can actually prove.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!