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
@@ -262,42 +262,3 @@ without auth before identity is resolvable.
the decision this ADR resolves
- `http-server.md` (in this crate's `docs/architecture/`) — the spec that
implements this mapping (alknet original: `crates/http/http-server.md`)
## Port notes
- Renames: "alknet-http" → alkhttp; "alknet" (the system/node being
described) → alkhttp where the HTTP-served surface is meant.
- `OperationType::Subscription``Sub` (alkcall rename) in the method
table and the SSE section. alkcall ADR-046 later added
`OperationType::Pub` (producer→consumer streaming via `call.published`,
`HandlerKind::Sink`); `Pub` has no row in this ADR's HTTP method table —
its HTTP projection is the `/publish` gateway endpoint (alkhttp
ADR-068).
- **Gateway endpoint count**: the alknet record's "5 fixed gateway
endpoints" statements are preserved verbatim as history; alkhttp extends
the set with `/publish` (alkhttp ADR-068) — marked with an inline
annotation in the amendment blockquote, not silently rewritten.
- Cross-reference remappings (verified alknet→alkcall ADR mapping): alknet
ADR-016 (abort cascade) → alkcall ADR-020. ADR-004/010/015/017/023 are
ported to this crate under the same numbers and linked; their alkcall
record numbers are noted alongside where cited (015→alkcall ADR-017,
017→alkcall ADR-022, 023→alkcall ADR-016).
- Producer/consumer terminology: the original contained no call-protocol
server/client role framing; "external HTTP clients (curl, axios, browser
`fetch`)" and similar retain their names — those are inherent-directionality
roles of the HTTP/OpenAPI surface, not call-protocol roles.
- Spec-document links converted per alkhttp conventions:
`crates/http/http-server.md``http-server.md` in this crate's
`docs/architecture/`; `operation-registry.md` → textual "the alkcall
crate's docs/architecture/operation-registry.md"; `auth.md` and
`endpoint.md` are alknet mono-repo spec-tree documents cited textually
(the auth model is ADR-004, the stealth mapping ADR-010).
- OQ references (OQ-11, OQ-13, OQ-17) are alknet OQ-tracker items, cited
textually; the operation path format is owned by the alkcall crate.
- The `docs/research/alknet-http/phase-0-findings.md` pointer is kept as a
historical alknet mono-repo reference (no alkhttp equivalent exists).
- No decision content changed — the three-option framing, the direct-path
decision (retained as the historical record of the ADR-047-superseded
routing), the method table, SSE projection, auth, stealth decoy,
`/healthz`, consequences, and assumptions are verbatim from the alknet
ADR modulo the adaptations above.