Skip to main content

Delivery, retries, and acknowledgements

Planned

Delivery is planned. The gateway-side durability behavior and wire ACK are already implemented, and the agent's compatibility tests record that contract.

Success condition​

For the response to a particular request, normal delivery completes only when accepted == true, durable == true, and received equals the number of submitted records. The ACK does not echo the batch ID or identify accepted records individually. Transport must keep request/response association intact. Inventory counts records, not the items inside them.

  • Spoolplanned
  • Deliveryplanned
  • ingest-gatewayimplemented
  1. 1Spool to Delivery: Stable records and original IDs
  2. 2Delivery to ingest-gateway: mTLS batch

  3. ifMatched durable ACK with full count

    1. 3ingest-gateway to Delivery: BatchAck
    2. 4Delivery to Spool: Persist acknowledgement state
    3. 5Spool: Reclaim acknowledged records

    elseTimeout, refusal, or incomplete ACK

    1. 3Delivery to Spool: Keep records
    2. 4Delivery: Classify failure and schedule retry

Retry classes​

Transient network or broker failures require bounded retry/backoff without changing observation identity. Publication may have partly succeeded, so retry can repeat events. A schema/protocol incompatibility must be distinguishable from corrupted producer data; the implemented internal/protocol refusal classifier supplies this distinction.

Malformed data, capacity pressure, expired certificates, revoked agent state, and a backend that does not speak the schema are different failures. An uploader that retries every refusal forever with the same delay can fill its spool without giving an operator a usable diagnosis.

Ordering and backpressure​

The target must define in-flight batch limits, concurrency, retry scheduling, and pressure propagation to collection. Preserve per-source progress requirements without inventing global ordering across all collectors. A separate inventory stream cannot be broken into misleading complete scans merely to fit a batch.

Security limits​

mTLS proves possession of a trusted private key. It does not prove the endpoint's observations are truthful or that the executable is authentic. Initial server trust must arrive through an authenticated provisioning path. There is no supported insecure-verification switch.

See gateway admission, spool requirements, and PKI limits.

Source evidence​

Reviewed against the source baseline. Seagull-contracts/proto/seagull/ingest/v1/ingest.proto · Seagull-agent-v2/internal/protocol/protocol.go · Seagull-backend-v2/internal/ingest/http.go.