feat(api): record and reload item deliveries over HTTP

[cursor]

Why

A purchaser can start listing instruments (#165) and creating sessions (#149), but still cannot record that a published item was shown or reload that ledger to resume. That is the next buyer-facing hole after session create.

What

• In-process POST and GET /v1/sessions/{session_ref}/item-deliveries
• Server-ordered sequence, exact Idempotency-Key replay that matches delivery_ref
• Fail closed on items outside the bound release, inactive sessions, conflicting replay, and numeric/blank identities
• As-built OpenAPI 3.2 contract limited to those two operations (openapi/item-deliveries.yaml)
• RFC 9457 problem details; no raw request/SQL/provider echo

Boundary

No live fast-mlsirm item selection or calibration. No session create/start (keep #149). No response, scoring, or result HTTP. No PostgreSQL ledger durability (keep #186/#110 reload persist). Do not mix those onto this head.

Verification

• cargo test --test item_delivery_http_contract
• cargo test --test item_delivery_http_listener_contract
• cargo test --test documentation_architecture_contract
• full Runtime CI, exact statement/branch coverage, docs, security, and independent review on the exact head

Next action after this lands

Record an accepted response event over HTTP against the same Active session, still without inventing a score.

  

[cursor]

Stale comment

GET cannot resume administration, and a purchaser following this family will stall after the first accepted delivery.

The domain slice is real: first POST returns 201, exact Idempotency-Key == delivery_ref replay returns 200 without a second row, and unpublished items / paused new deliveries / conflicting replay fail closed with application/problem+json. That is not enough.

Required before this head is a landing vehicle:

1. GET must return allowed_item_version_refs, release_content_digest, and session_state, or stop claiming resume.
2. 201/200 and every problem detail must name the next call. Catalog the problem type URIs in OpenAPI.
3. The TCP accept loop must read Content-Length bytes after the header terminator. A mid-character Content-Length must fail closed, not panic.
4. Colliding seeded session_ref values must fail closed. Document capability-URL authority and the absence of tenant isolation.
5. Idempotency-Key must use the same normalized_reference predicate as other public IDs.
6. POST must require Content-Type application/json.

Keep this draft unmerged. The same-slice successor on cursor/bc-202765b3-6d0e-4a63-9cc8-6a638afe7692-a197 applies those fixes on top of this head. Do not open a third item-delivery HTTP family.

  

_{Sent by Cursor Automation: Fix Issues}

[cursor]

Draft HTTP record/reload is the right buyer family after durable persist. Keep this slice on #197. Do not open a second item-delivery HTTP PR.

Rebase onto #224 before this can compile against current persist/reload. #224 adds ItemDeliveryError::CorruptHistory. delivery_problem in src/item_delivery_http.rs is not exhaustive for that variant, so this head will fail to build once it picks up the reload domain.

HTTP still trims Idempotency-Key. valid_idempotency_key returns the trimmed spelling, so a padded header can match an exact delivery_ref. After #224, persist/reload reject padded aliases. This transport should fail closed on a padded key instead of aliasing.

In-process only: no PostgreSQL durability (keep #224). No session create (#149). No response HTTP (#195/#221). Do not merge this Draft in parallel with #224. Do not self-approve. Independent last-push review still required after rebase.

View PR

  

_{Sent by Cursor Automation: Fix Issues}