feat(infra): full-surface integration suite + docs sync + publish prep

Full-surface integration suite (tests/full_surface.rs, mcp feature):
- one HttpAdapter over real TCP (ProtocolHandler::handle path) serving
  gateway endpoints, /openapi.json, /mcp, and the WS channels session
- gateway: search/schema/call/subscribe/batch/publish presence,
  envelope shapes, error fidelity end-to-end
- from_openapi import -> Internal-by-default invisible from the wire ->
  External facade composes it via env.invoke -> upstream HTTP API
  called end-to-end (ADR-015 composition model exercised)
- to_openapi 6-path doc validated against openapiv3 over the wire
- to_mcp: MCP client connects to /mcp on the served adapter, lists the
  4 gateway tools, search returns ACL-filtered ops (Sub excluded)

Production fix: the WS upgrade route was reserved but never wired into
HttpAdapter's router (the ws-upgrade-session tests built their own
router). Now wired with ws_bearer_auth (401 without a resolvable
token) around ws_upgrade_handler.

Docs sync: all 28 'Port notes' sections/blockquotes stripped from
ported ADRs/specs; OQ-01/OQ-02 statuses corrected to resolved in
overview.md, websocket.md, and the README table (open-questions.md was
already current).

Publish prep: cargo publish --dry-run --allow-dirty succeeds;
cargo doc --no-deps warning-free (ADR link targets fixed); feature
combinations (default / test-support / mcp / wss / all) compile
warning-free under clippy -D warnings.

Verified: cargo test (182 lib default), --all-features (227 lib + 29
integration), clippy -D warnings x3 feature sets, fmt, doc,
publish --dry-run.
This commit is contained in:
2026-08-28 16:07:56 +00:00
parent bc99ec7188
commit 4a825d33e7
41 changed files with 700 additions and 1035 deletions
@@ -370,53 +370,3 @@ implementation detail within the one-way decision.
live in this crate's `docs/architecture/`): `operation-registry.md`,
`call-protocol.md`, `http-server.md`, `http-adapters.md`, `http-mcp.md`,
`client-and-adapters.md`
## Port notes
- Renames: "alknet-http" → alkhttp; "alknet-core"/"alknet-call" → alkcall.
- **`OperationType::Subscription``Sub`** throughout (alkcall rename;
`OperationSpec.op_type` value and TS-mapping references). The TS prior-art
identifiers (`SUBSCRIPTION`, `SubscriptionHandler`) are left verbatim —
they are the TypeScript package's names, not the Rust enum's.
- **Producer/consumer terminology**: "the **server side** does not" → "the
**producer side** did not (in the original design)"; "The **client side**
works — a client can subscribe" → "The **consumer side** works — a
consumer can subscribe"; "server-side handler → server-side dispatch" →
"producer-side handler → producer-side dispatch"; "the client-side
`CallConnection::subscribe()`" → "the consumer-side"; §4 "client-side
programming error" → "caller-side programming error"; §6 heading
"Server-side dispatch branches on `op_type`" → "Dispatch branches on
`op_type`". HTTP/TS inherent directionality untouched (`buildCallHandler`
is TS prior-art code; `client.ts` citations keep their names).
- **`Pub`/`Sink` note (alkcall ADR-046)**: the original defined two
`HandlerKind` variants (`Once`, `Stream`) — annotated. The §2 code block
now shows the three-variant enum with a block-quote annotation marking the
`Sink` variant as the alkcall ADR-046 addition (decision history
retained); §2's validation sentence and §6's dispatch branch table add the
`Pub``invoke_sink()` row with the alkcall ADR-046 citation; the Door
type section's one-way enum-shape sentence updated to acknowledge the
third variant. `from_openapi` produces no `Pub` ops in v1 (SSE detection
yields `Sub`), so §7–§9 need no change. The original two-variant decision
text is otherwise retained verbatim as decision history.
- §7 title: "(alknet-http)" → "(alkhttp)". The `/subscribe` endpoint and
`GatewayDispatch::invoke_streaming()` are this crate's gateway surface
(ADR-042/ADR-047); the Context's first downstream bullet names
`GatewayDispatch::invoke()``subscribe_handler`, which is the alkhttp
gateway dispatch spine.
- Cross-reference remappings (verified alknet→alkcall ADR mapping): alknet
ADR-012 (stream model) → alkcall ADR-015; alknet ADR-016 (abort cascade) →
alkcall ADR-020; alknet ADR-022 (handler registration) → alkcall ADR-018;
alknet ADR-017 (adapter contract) → alkcall ADR-022; alknet ADR-015
(privilege model) → alkcall ADR-017; alknet ADR-029 (peer-graph routing) →
alkcall ADR-024; alknet ADR-009 (one-way door framework) → alkcall ADR-032.
ADR-015/017/022/023 are ported to this crate under the same numbers and
linked; their alkcall record numbers are noted alongside.
- The amended-spec list at the end of References is annotated: those spec
documents live in the alknet mono-repo spec tree (and the alkcall crate's
docs for the call-side ones); the alkhttp equivalents are this crate's
`docs/architecture/http-server.md` and `http-adapters.md`.
- No decision content changed — the `StreamingHandler` type, the
`HandlerKind` enum, `invoke_streaming()`, the `INVALID_OPERATION_TYPE` code,
the `OperationEnv` request/response-only boundary, the dispatch branch, and
the gateway/from_call/from_openapi streaming paths are verbatim from the
alknet ADR modulo the corrections logged above.