feat(storage): define the outbound pending-message contract and CBOR envelope

[lykakis]

Parent epic: #337
Delivery step 2; depends on the architecture, interfaces and working memory baseline in #338. Blocks #344 and filesystem implementation #339.

Goal

Refine the pending-message store contract introduced in #338, define the versioned Jackson CBOR envelope, and add reusable behavioral tests against its memory baseline and later durable backends. This is the admission and authoritative source-record boundary; it does not define router-queue or routed-destination storage.

Contract

• Admit a validated complete message or multipart part and return a stable pending handle only when the selected backend has accepted it; report duplicate multipart ordinals separately.
• Recover published pending items by stable handle, and complete one handle or all source handles of a multipart aggregate after all required work is terminal.
• Distinguish admission, capacity, corruption, ownership, and completion failures sufficiently for ingress and readiness. Admission failure must never silently enqueue untracked work.
• Expose backend identity and readiness without leaking SQL, paths, CBOR, or backend-specific types into protocol/routing/worker APIs.
• Keep the accepted source record until terminal completion and any required DLR handoff. Completion is idempotent only when absence can be established safely.
• Exercise and refine the existing non-durable memory pending implementation from feat(storage): define outbound stage abstractions and memory baseline #338 through the shared contract suite; memory mode makes no restart promise.

Versioned envelope

Encode a documented schema, not Java serialization or StandardMessage directly. Preserve gateway UUID, account/system/ingress identity, sender and recipient, body and encoding/data coding/UDH, message type, priority, validity, routing inputs and required filter/worker fields, and DLR request and return metadata. Preserve multipart group identity, ordinal, declared total, original part UUID, and absolute first-part deadline. Document a deterministic supported subset of extension values; fail admission for unsupported values before protocol success. Define schema-version compatibility, corruption handling, and unknown-version behavior.

Multipart contract

• Admit each accepted SMPP part to the selected backend before STATUS_OK; durable backends persist it. The first accepted value for a group/ordinal wins and duplicates are acknowledged without replacement.
• Derive group identity from at least account/system, sender, recipient, reference, declared total, and normalized UDH. Downtime counts toward the saved absolute timeout.
• Reconstruct complete and incomplete groups on startup. Aggregate as a runtime projection retaining source handles; never route source parts and aggregate independently. On expiry, release received parts for independent routing according to existing behavior.
• Complete source handles only after aggregate terminal processing, including required DLR handoff.

Behavioral tests and acceptance criteria

• Contract tests cover admission before HTTP/SMPP success, recovery and safe completion, multipart duplicates/recovery/timeout, storage unavailable/full/locked, and idempotent completion.
• Codec tests cover round trip of all supported fields, extensions, truncated/corrupt records, and unknown schema versions.
• Protocol and worker callers can use the interface without selecting a physical backend.
• The pending record remains authoritative when router/routed-work state uses memory; later stage contracts own select-and-stage, routing decisions, and per-destination completion.

Out of scope

Reimplementing the memory baseline from #338, physical file layout/publication and PostgreSQL schema, select-and-stage, routed destination state, persisted retries or provider outcomes, redesign of the existing DlrStorage contract, and exactly-once provider submission.

Related: architecture #338; stage contracts #344; filesystem pending implementation #339; PostgreSQL #333.