---
id: gateway-publish
name: POST /publish endpoint for Pub operations
status: pending
depends_on: [gateway-routes]
scope: narrow
risk: medium
impact: component
level: implementation
tags: [gateway, phase-3]
---

## Description

Implement `POST /publish` per ADR-068: NDJSON request body (each line =
one published chunk) dispatched through `invoke_sink()` (alkcall
ADR-046); handler's final ResponseEnvelope → 200 JSON or mapped error
status. Resolve OQ-02 during this task: first line carries
`{ "operation": "/{service}/{op}", "chunk": {...} }` (subsequent lines
`chunk`-only); terminal errors are plain HTTP status + JSON body (not
an NDJSON line). Client disconnect drops the body stream → sink
cancelled (PublishStream sees EOF). Non-Pub target → 400
INVALID_OPERATION_TYPE. Tests: multi-chunk publish round-trip against a
SinkHandler over DuplexStream, early-disconnect, error mapping.

## Acceptance Criteria

- [ ] /publish wired; OQ-02 convention implemented and documented in ADR-068
- [ ] Sink round-trip test (3+ chunks → final envelope)
- [ ] Disconnect mid-stream cancels the handler (no hang)
- [ ] to_openapi gateway doc gains /publish; gateway `info.version` minor bump
- [ ] `cargo test` passes

## References

- docs/architecture/decisions/068-gateway-publish-endpoint.md
- docs/architecture/open-questions.md (OQ-02)
- alkcall ADR-046 (Pub/invoke_sink/PublishStream)

## Notes

> Agent fills during implementation.

## Summary

> Agent fills on completion.