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
@@ -430,50 +430,3 @@ enum instead of a generic `Result<Output, string>`.
- TypeScript reference: `/workspace/@alkdev/operations/src/types.ts`
L3847 (`ErrorDefinitionSchema`), L94, L112 (`errorSchemas` on
`OperationSpec`), `error.ts` L2551 (`mapError`)
## Port notes
- Renames: "alknet-http" → alkhttp; "alknet-core"/"alknet-call" → alkcall
("the call crate (now alkcall)").
- `OperationType::Subscription``Sub` (alkcall rename; alkcall ADR-046
added `OperationType::Pub`, producer→consumer streaming via
`call.published`, `HandlerKind::Sink`). Corrections flowing from this:
the `INVALID_OPERATION_TYPE` table row now lists the dispatch-path
mismatches per the current handler-kind model (`invoke()` on a `Sub`,
`invoke_streaming()` on a `Query`/`Mutation`, `invoke_sink()` on a
`Query`/`Mutation`/`Sub`, and `OperationEnv::invoke()` on a `Sub` during
composition) and cites alkcall ADR-021 (this crate's
[ADR-049](049-streaming-handler-for-subscriptions.md)) and alkcall ADR-046
for `Pub`/`Sink`. `from_openapi` produces no `Pub` ops in v1 (SSE
responses detect as `Sub`), so the adapter-fidelity discussion is
unaffected by `Pub`.
- Producer/consumer terminology: "A client calling `/fs/readFile`" → "a
consumer"; "clients get typed errors" → "consumers get typed errors";
§2 `code` bullet "Clients should switch on `code`" → "Consumers should
switch on `code`"; §3 "Clients should handle protocol-level codes" →
"Consumers should handle". HTTP/MCP/OpenAPI client references
(§5's "HTTP clients", the client code generation, "brittle clients")
keep their names — those are inherent-directionality roles of the
external systems, not call-protocol roles. Wire-format backward
compatibility bullets retain "existing clients" wording (wire consumers).
- `from_openapi` example: the original said the adapter maps "the OpenAPI
error schema to alknet's JSON Schema format" — corrected to "the call
protocol's JSON Schema format".
- §5 closing sentences extended to note that `from_openapi`/`to_openapi`
live in alkhttp and that the `HTTP_<status>` rule is part of this crate's
gateway error-fidelity contract (ADR-047) — port framing, not a new
decision.
- Cross-reference remappings (verified alknet→alkcall ADR mapping): alknet
ADR-017 (adapter contract) → alkcall ADR-022; alknet ADR-049 (streaming
handler) → alkcall ADR-021. ADR-014 and ADR-015 are ported to this crate
under the same numbers and linked.
- Review/spec paths (`docs/reviews/...`, `docs/sdd_process.md`,
`call-protocol.md` L-references) are alknet mono-repo artifacts; annotated
as alknet-record citations. The `call-protocol.md` relative link and its
line-number citation for the unknown-code rule became a textual "the
alkcall crate's `call-protocol.md`" reference.
- No decision content changed — the `error_schemas` field, the `details`
payload field, the protocol-vs-operation code namespace split, the handler
error mapping, the `HTTP_<status>` prefix rule, and the `services/schema`
exposure are verbatim from the alknet ADR modulo the corrections logged
above.