alkdev/operations
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update architecture docs for handler separation and pubsub API changes

Browse Source 
- api-surface.md: Updated registry API table (registerSpec, registerHandler,
  getHandler, separated spec/handler storage), OperationSpec description,
  IOperationDefinition marked as convenience type, adapter return types
- call-protocol.md: Added pubsub EventEnvelope unwrapping details,
  subscribe(type, id) 2-arg API, handler separation in buildCallHandler
  and subscribe(), handler separation section
- adapters.md: Updated return types (OperationSpec & { handler }),
  scanner validates against OperationSpecSchema, new module shape examples
  showing spec-only and spec+handler patterns, typemap mention
- README.md: Core principle updated for spec/handler separation
- build-distribution.md: Updated pubsub dep description, registry.ts description
- AGENTS.md: Updated key points, source layout, provenance status
This commit is contained in:
glm-5.1
2026-05-09 08:34:41 +00:00
parent 4f11f8e7a0
commit d0017df2bf
6 changed files with 109 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/architecture/README.md
View File

@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-04-30
last_updated: 2026-05-09
---
# @alkdev/operations Architecture
@@ -18,7 +18,7 @@ Extracted from `@alkdev/alkhub_ts/packages/core/operations/` and `packages/core/
## Core Principle
**The operation definition is the contract.** Every API endpoint, agent action, coordination tool, and MCP tool is an `IOperationDefinition` with typed input/output schemas, access control, and a handler. The registry executes them. The call protocol routes them. Adapters generate them from external specs.
**The spec is the contract; the handler is the runtime.** Every API endpoint, agent action, coordination tool, and MCP tool has an `OperationSpec` (serializable, hashable descriptor) and optionally a handler function. The registry stores specs and handlers separately — they can be registered together with `register()` or independently with `registerSpec()` and `registerHandler()`. The call protocol routes invocations through specs. Adapters generate specs (and handlers) from external definitions.
All paths funnel into the same registry:
@@ -34,8 +34,8 @@ Access control, validation, and error handling are consistent regardless of entr
## What This Package Provides
- **Core types** — `IOperationDefinition`, `OperationSpec`, `OperationType`, `AccessControl`, `Identity`, `OperationContext`
- **Registry** — `OperationRegistry` with register, execute, validate, spec extraction
- **Core types** — `OperationSpec`, `IOperationDefinition`, `OperationType`, `AccessControl`, `Identity`, `OperationContext`, `OperationHandler`, `SubscriptionHandler`
- **Registry** — `OperationRegistry` with `register`, `registerSpec`, `registerHandler`, `execute`, `getSpec`, `getHandler`, spec extraction
- **Call protocol** — `PendingRequestMap`, `CallHandler`, `call≡subscribe` event semantics
- **Subscribe** — `subscribe()` for `AsyncGenerator`-based subscription operations
- **Env builder** — `buildEnv()` for nested operation calls (direct or call protocol mode)