---
id: update-call-graph-and-operations-docs
name: Update call-graph.md and operations.md for @alkdev/operations API
status: completed
depends_on: []
scope: moderate
risk: medium
impact: component
level: 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)