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
@@ -527,61 +527,3 @@ protocol-crate take-over that consumes the dial's `Connection`.
See the alkcall crate's `client-and-adapters.md`
§"CallClient" for the reframed operational spec.
## Port notes
- Renames: "alknet-http" → alkhttp; "alknet-core"/"alknet-call" → alkcall;
"alknet node"/"non-alknet systems" → "alk node"/"non-alk systems".
- ALPN correction: `alknet/call``alk/call` (alkcall ADR-004 renamed the
ALPN convention to the `alk/` namespace).
- Producer/consumer terminology: "server side"/"client side" (§Context,
§1, §6) → "accept side"/"connect side" for the connection-establishment
half; "who advertises"/"who opens connection" table retained (it was
already direction-of-establishment language); §2's closing sentence now
says the protocol does not distinguish producer and consumer after
connection establishment. "Node.js and Python clients" → "consumers".
HTTP/MCP inherent directionality is untouched ("HTTP clients", "MCP
servers", "MCP clients" keep their names — those are protocol roles of the
external systems, not call-protocol roles).
- `Subscription``Sub` (alkcall renamed `OperationType::Subscription` to
`Sub`; alkcall ADR-046 added `OperationType::Pub` — producer→consumer
streaming via `call.published`, `HandlerKind::Sink`). §1's
`subscribe()` description, §3's "or streams for subscriptions", and the
Consequences "subscriptions → SSE long-poll" example now say `Sub`.
- §4 corrected to name the concrete alkhttp realizations: `to_openapi` is the
OpenAPI gateway pattern (ADR-042 — five fixed gateway endpoints, not one
path per operation) and `to_mcp` is the MCP tool-gateway pattern (ADR-041 —
four fixed gateway tools). The original predates those ADRs; the decision
content (outbound projections of `External` ops) is unchanged.
- Assumption 5 correction: "a separate HTTP handler (alknet-http)" → "an HTTP
host (alkhttp) ... the gateway dispatch" — the direct-call per-operation
HTTP surface was removed by ADR-047; the gateway is the sole invoke path.
- Amendment remappings (verified alknet→alkcall ADR mapping): alknet
ADR-028 → alkcall ADR-023; alknet ADR-029 → alkcall ADR-024; alknet ADR-016
(abort cascade) → alkcall ADR-020; alknet ADR-024 (registry layering) →
alkcall ADR-019; alknet ADR-065 (`Connection::from_stream`) → alkcall
ADR-007; alknet ADR-080 (`ChannelClient`) → alkcall ADR-043; alknet ADR-089
(dial seam) → alkcall ADR-045; alknet ADR-012 (stream model) → alkcall
ADR-015; alknet ADR-069 (from_call manual free function) → alkcall ADR-028;
alknet ADR-013 (Rust canonical) → alkcall ADR-033; alknet ADR-009 (one-way
door framework) → alkcall ADR-032. The 2026-07-13 amendment title's
"mirrors ADR-080's amendment" cites the alknet number (the amendment
mirrored the alknet-record ADR-080).
- All `client-and-adapters.md` relative links converted to textual
"the alkcall crate's `client-and-adapters.md`" references (the document
lives in the alkcall crate's docs/architecture/).
- alknet OQ numbers (OQ-15, OQ-25..28, OQ-55) are alknet-record citations,
annotated as such — alkcall's OQ numbering differs (e.g., alkcall OQ-25 is
BiStream type definition, not the DC remainders).
- The `QuicCallCredentials`-shaped `connect(addr, credentials)` signature in
§1 is retained as decision history (the 2026-07-16 amendment removes
`connect`); the QUIC-specific wording "opens a QUIC connection" is
softened to "opens a connection" in the §1 prose per the transport-agnostic
amendment, with the amendment block recording the original framing.
- Status line: "per ADR-089 §5" annotated as alknet ADR-089 (alkcall
ADR-045) — the amendment citation refers to the alknet-record number.
- No decision content changed — the shared dispatch loop, the
connection-direction independence, the adapter contract trait, the
cross-node abort cascade, the credential-source rule, and all three
amendment blocks are verbatim from the alknet ADR modulo the mechanical
corrections logged above.