fix(dm): report observed durable-ACK ingress provenance separately from send strategy (#461)

[dirvine]

What this fixes (#461)

The durable-ack receipt path hardcoded path: gossip_inbox — the send strategy the sender chose, not the transport that actually carried the ACK. When the gossip-inbox publish was slow or lost and the durable ACK was hedged home over the direct typed/raw-QUIC path, the response still said gossip_inbox.

Design

• Actual ACK ingress vs chosen strategy, reported separately: a new additive DmAckIngress { DirectTyped, Subscription } is stamped at the single authenticated waiter completion (first-valid-matching-ACK wins; failed attempts stamp nothing; unstamped stays None — unknown is never fabricated). The existing DmReceipt.path keeps its meaning (send strategy — docs corrected to say so); the observed ingress rides an internal Result<(DmReceipt, Option<DmAckIngress>)> exposed to the /direct/send route as an optional observed_ack_ingress JSON key (direct_typed/subscription), present only when known.
• Public receipt compatibility preserved: DmReceipt keeps its original four public fields; every pre-existing public signature is unchanged (send_via_gossip and send_direct_with_config are thin wrappers). A downstream-crate fixture (tests/dm_receipt_compat.rs) constructs the ORIGINAL struct literal — any required-field addition breaks that compilation.
• Outbound history preserved: the ADR-0023 §4 wiring (durable-payload classification + record_dm_outbound) lives in the single common provenance path; the public method only maps away the tuple. Regression provenance_entry_records_outbound_history_on_success drives a fully offline agent (no sockets, no daemon) through the route's exact entry and asserts the Outbound row in the agent's real history store.
• Production-selected ingress label: the subscription loop's dispatch is a production seam that itself selects Subscription; both dm: /direct/send response path reports gossip_inbox even when the receipt was hedged home over the direct/raw-QUIC path #461 controls (label stamping; invalid-signature-first-leaves-None-then-valid-wins) drive that seam, so a test cannot choose the label it asserts.

Verification (exact tree 5c13dd5, CARGO_BUILD_JOBS=2)

• Focused 8/8 exit 0 (waiter both-order/wrong-binding, seam-driven subscription label, direct-hedge ingest stamping, invalid-signature-then-valid) + compat fixture 1/1 exit 0.
• Four ordered gates with logged commands and EXIT=0 each (fmt; all-target clippy -D warnings; production lib/bins panic/unwrap/expect clippy; workspace all-target check); post-fmt sha256 of all six changed files recorded in the same log.

Not claimed: network/mesh acceptance runs (no runtime executed by reviewers); wire-format changes (none — the ACK wire is untouched).

Fixes #461

P2 correction (follow-up commits)

Senior + Claude found an authenticated v1 gossip ACK could populate observed_ack_ingress, which the field describes as the durable-ACK transport. Fixed at the central stamping point: resolve_inner stamps the ingress cell only when the resolved waiter negotiated protocol_version >= DM_PROTOCOL_DURABLE_ACK. A v1 waiter still completes normally (no v1 failure, no negotiation change, internal ACK behavior preserved); v2 stamping is unchanged; unknown stays None and the HTTP mapper omits the field by construction. Regression: v1_ack_resolves_waiter_but_stamps_no_durable_ingress — a fully signed/attested V1 envelope through the real subscription dispatch seam resolves its v1 waiter while the cell stays None, paired with v2 stamping positives through the same seam.

Honest test-scope note (no overclaim): no HTTP-level response regression was added or run — the existing receipt tests are internal, and the REST-side guard was source-verified only. This focused code-fix proof is accepted for the PR; full live HTTP/E2E coverage remains a separate, unmet requirement.

Verified on the admitted head a4748815 (integrated with main fe0a775): four ordered gates with commands/EXIT=0, focused 10/10, post-fmt source hashes in the gate log.

Greptile Summary

This PR separates the selected DM send strategy from the observed transport of the winning authenticated durable ACK.

• Adds locally stamped direct_typed and subscription ACK-ingress provenance without changing the public DmReceipt shape.
• Exposes known durable-ACK ingress as the optional observed_ack_ingress field on successful /direct/send responses.
• Preserves outbound-history recording through the common provenance-aware send path.
• Suppresses provenance for v1/non-durable ACKs while preserving normal v1 waiter completion.
• Adds compatibility and ingress-resolution regressions and updates the API documentation.

Confidence Score: 5/5

The PR appears safe to merge; the previously reported v1 provenance issue is fully fixed and no new actionable defects remain.

ACK resolution still requires exact protocol, recipient, and machine binding, and ingress is stamped only for waiters using the durable protocol or newer. The v1 path continues to resolve normally while leaving provenance absent, so the earlier misleading durable-ingress response is no longer present.

Important Files Changed

Filename	Overview
src/dm.rs	Adds protocol-bound winning-ACK ingress stamping and correctly excludes v1 waiters from durable provenance.
src/dm_inbox.rs	Labels authenticated ACKs according to their production subscription or direct-typed ingress seam and adds focused regressions.
src/dm_send.rs	Carries optional winning-ACK provenance alongside the unchanged public receipt while preserving retry behavior.
src/lib.rs	Introduces the internal provenance-aware send path while retaining public signatures and outbound-history recording.
src/server/routes/direct.rs	Adds the optional observed_ack_ingress response field without changing path semantics.
tests/dm_receipt_compat.rs	Ensures downstream code can still construct the original four-field DmReceipt.
docs/api-reference.md	Documents the distinction between send strategy and durable-ACK return transport.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    C[Direct-send client] --> R[POST /direct/send]
    R --> S[Select payload send strategy]
    S --> W[Register protocol-bound ACK waiter]
    S --> P[Publish DM]
    P --> A{Authenticated matching ACK}
    A -->|Direct typed/raw QUIC| D[Stamp DirectTyped]
    A -->|Gossip subscription| G[Stamp Subscription]
    A -->|v1 or unknown| N[Leave provenance unset]
    D --> J[Return receipt plus observed ingress]
    G --> J
    N --> J
    J --> H[HTTP response]
    H --> X[path: send strategy]
    H --> Y[observed_ack_ingress: optional ACK transport]

Loading

_{Reviews (2): Last reviewed commit: "docs: explain observed durable ACK ingre..." | Re-trigger Greptile}

Context used:

• Knowledge Base — Direct messaging delivery
• Knowledge Base — Server APIs and live streams

[dirvine]

Greptile: the durable-type invariant is enforced at the central internal guard (resolve_inner stamps provenance only for waiters negotiated at >= DM_PROTOCOL_DURABLE_ACK). An authenticated v1 waiter completes normally with None; v2 positives pass. Note: no HTTP-level response regression was added/run — existing receipt tests are internal; the REST guard was source-verified. Full live HTTP/E2E remains a separate unmet goal requirement, not claimed here.