glm-5.1
2b63cda1c7
Copy architecture docs, ADRs, storage domain specs, research, reviews, and 56 storage architecture tasks from the alkhub_ts monorepo. Adapt for standalone @alkdev/hub repo structure (src/ not packages/hub/). Sanitize all sensitive information: - Replace private IPs (10.0.0.1) with localhost defaults - Remove internal server hostnames (dev1, ns528096) - Replace /workspace/ private paths with npm package references - Remove hardcoded credentials from examples - Rewrite infrastructure.md without private network details Add Deno project scaffolding: deno.json (pinned deps), .gitignore, AGENTS.md, entry point. Migrate existing code stubs (crypto, config types, logger) with updated import paths.
65 lines
3.5 KiB
Markdown
65 lines
3.5 KiB
Markdown
---
|
|
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) |