Add a carrier-aware mailbox read-state diagnostic

Context

#15825 tracks the unresolved mechanism behind mailbox read-state resurfacing. Fresh direct and broadcast probes on 2026-07-28 preserved their receipts across new Memory Core stdio lifetimes, so reconnect alone is a bounded negative—not a root cause. The parent must remain open until a real recurrence identifies the dropping or skipping path.

The investigation still lacks a rerunnable instrument that reads the correct carrier from an explicitly selected graph database. The existing ticket's original one-carrier SQL shape can misclassify every direct message because direct and receipt-backed broadcast state live on different graph records.

A bounded implementation is prepared in commit 7ce334e3d9; this leaf gives that independently mergeable diagnostic an honest close target without closing the mechanism investigation.

The Problem

Manual inspection currently requires the operator to remember the route-dependent storage contract:

• direct message: MESSAGE.properties.readAt;
• receipt-backed broadcast: the affected recipient's DELIVERED_TO.properties.readAt.

Looking only for DELIVERED_TO turns a healthy direct message into an apparent missing receipt. Loading the active AiConfig to find a database also makes the result dependent on the inspecting process's seat/configuration—the wrong property for a forensic instrument intended to compare explicit stores.

The diagnostic must distinguish an observed anomaly from a probe execution failure. A missing row, null receipt, timestamp, malformed record, and conflicting topology are storage observations; invalid input or an unreadable database means the instrument did not run.

The Architectural Reality

• learn/agentos/A2A.md defines the direct MESSAGE versus broadcast DELIVERED_TO carrier split.
• ai/services/memory-core/MailboxService.mjs resolves the route through SENT_TO, persists direct receipts through the message node, and persists broadcast receipts through the recipient delivery edge.
• ai/graph/storage/SQLite.mjs stores canonical graph columns plus the JSON node/edge record used by the mailbox service.
• Structure-map gate: ai/scripts/diagnostics is the existing owner for read-only, rerunnable instruments (28 files at creation time), with planePlacementCensus.mjs and walSnapshotClone.mjs as sibling precedents. The focused spec belongs under test/playwright/unit/ai/scripts/diagnostics/.

No service, daemon, MCP schema, AiConfig leaf, or mailbox mutation belongs in this leaf.

The Fix

Add ai/scripts/diagnostics/mailboxReadStateProbe.mjs with:

• mandatory --db-path, --message-id, and --recipient;
• better-sqlite3 opened with readonly plus fileMustExist, with connection-level query_only;
• direct-versus-broadcast resolution from persisted SENT_TO topology before reading readAt;
• bounded legacy identity spelling compatibility matching current mailbox comparisons;
• one JSON result envelope whose ok field means inspection completed and whose state names the observation.

Add test/playwright/unit/ai/scripts/diagnostics/mailboxReadStateProbe.spec.mjs using real temporary SQLite rows for both carrier classes and their negative controls.

Contract Ledger

Decision Record impact

none — the leaf instruments the existing mailbox storage contract and does not change architectural authority.

Acceptance Criteria

• The CLI requires explicit --db-path, --message-id, and --recipient inputs and never resolves the active database from AiConfig.
• Direct messages are classified from MESSAGE.properties.readAt; receipt-backed broadcasts are classified from the affected recipient's DELIVERED_TO.properties.readAt.
• Results distinguish missing message, missing recipient carrier, explicit unread (null), read timestamp, malformed storage, conflicting storage, input failure, and open/query failure.
• The inspected SQLite file is opened read-only and a byte-identical before/after test proves the happy path does not mutate it.
• Focused unit coverage exercises real SQLite rows for both carriers and the negative controls through Neo's custom unit-test runner.
• The implementation PR references #15825 without closing it and changes no mailbox service, daemon, repair, configuration, or sender-provenance behavior.

Out of Scope

• Naming or fixing the positive read-state loss mechanism tracked by #15825.
• Autonomous sender provenance and authorization design in D#16083.
• Stale/orphaned runtime liveness tracked by #14477.
• Automatic repair, WAL replay, receipt mutation, active-plane discovery, or production logging.

Avoided Traps

• One-carrier SQL: rejected because it false-positives on direct messages.
• Active-config inference: rejected because a forensic probe must inspect the store the caller names, not whichever store the current seat resolves.
• Probe-time repair: rejected because observing an incident and mutating it in the same command destroys the specimen.
• Permanent draft PR: rejected because the diagnostic is complete and independently reviewable; the mechanism ticket remains open through an explicit scope split instead.

Related

• Parent mechanism investigation: #15825
• Sender-provenance design (separate scope): https://github.com/orgs/neomjs/discussions/16083
• Runtime freshness (separate scope): #14477

Duplicate Sweep

• Semantic ticket sweep: no equivalent dedicated diagnostic found; nearest results were #15825, #15448, #15322, and historical mailbox investigations.
• Local issue/discussion archaeology: existing artifacts cover manual probes, repair, restore preservation, and wake behavior; none owns this CLI deliverable.
• Live latest-open + in-flight claim sweep: checked the latest 20 created-open issues and latest 30 all-state A2A messages at 2026-07-28T10:58:22Z; no equivalent ticket or competing claim found.

Origin Session ID: 019fa530-53d6-7271-bf05-51497720b29c

Retrieval Hint: #15825 carrier-aware mailbox read-state diagnostic explicit SQLite MESSAGE DELIVERED_TO

Authored by @neo-gpt.