hub/tasks/sync/update-call-graph-and-operations-docs.md

id, name, status, depends_on, scope, risk, impact, level

id	name	status	depends_on	scope	risk	impact	level
update-call-graph-and-operations-docs	Update call-graph.md and operations.md for @alkdev/operations API	completed		moderate	medium	component	implementation

Description

These two architecture docs describe the call protocol and operations system, both of which are now implemented in @alkdev/operations. They need significant updates to reflect the actual API surface.

call-graph.md changes

1. PendingRequestMap section — Replace the schematic implementation with actual @alkdev/operations API:

   • new PendingRequestMap({ eventTarget }) constructor with optional EventTarget
   • call(operationId, input, { deadline, identity }) returns Promise<ResponseEnvelope>
   • subscribe(operationId, input, { idleTimeout, identity }) returns AsyncIterable<ResponseEnvelope>
   • respond(requestId, output) requires isResponseEnvelope(output)
   • emitError(requestId, code, message, details?), complete(requestId), abort(requestId)
   • Built-in deadline and idle timeout support

2. CallHandler section — Reference buildCallHandler from @alkdev/operations

3. buildEnv section — Remove callMap parameter. New API:

   • buildEnv({ registry, context }) — sets trusted: true on nested context
   • No callMap parameter — PendingRequestMap handles call routing
   • Returns env functions that return Promise<ResponseEnvelope>

4. Dependencies section — Replace direct graphology deps. graphology is now a transitive dep through @alkdev/taskgraph. For call graph storage, the hub can still use graphology directly or use @alkdev/taskgraph's TaskGraph class.

5. CallEventSchema — Cross-reference that the TypeBox schemas are in @alkdev/operations and may differ slightly from what's documented. Add note to verify against package source.

6. Transport mapping table — Update WebSocket row: @alkdev/pubsub/event-target-websocket-server for hub, @alkdev/pubsub/event-target-websocket-client for spoke

operations.md changes

1. Remove "In-repo location: packages/core/operations/" — now @alkdev/operations npm package
2. Update component descriptions to reference @alkdev/operations exports
3. Add ResponseEnvelope concept (universal result wrapper: local/http/mcp)
4. Add CallError / InfrastructureErrorCode concept
5. Add subscribe() helper for subscription operations
6. Add ScannerFS interface (Deno/Node agnostic)
7. Update Schema Adapters section to use SchemaAdapter pattern from @alkdev/operations/from-typemap
8. Remove "SSE Subscription Handler Fix" from open issues — fixed in @alkdev/operations/from-openapi
9. Update Call Protocol Integration section to reference @alkdev/operations API
10. Update buildEnv to remove callMap parameter

Acceptance Criteria

• call-graph.md PendingRequestMap section shows actual @alkdev/operations API
• call-graph.md buildEnv section has no callMap parameter
• call-graph.md dependencies reference @alkdev/taskgraph transitively
• call-graph.md transport table references @alkdev/pubsub event targets
• operations.md references @alkdev/operations package throughout
• operations.md open issues no longer include fixed items
• operations.md documents ResponseEnvelope and CallError
• No references to packages/core/operations/ remain in either doc

References

• docs/reviews/core-library-extraction-sync-2026-05-18.md (Section 2.4, 2.5)