tasks: decompose Phase 0b spec documents and Phase 0c review
Add 15 new tasks under tasks/architecture/ for Phase 0b (spec writing) and Phase 0c (review): Phase 0b — New specs (6): - spec-configuration: promote from research, cleanup, align with ADRs - spec-identity: carry from auth.md + services.md, canonical Identity - spec-secret-service: from research/services.md SecretProtocol - spec-storage: from research/storage.md, contract-level - spec-flowgraph: from research/flow.md, pure computation crate - spec-interface: new Layer 2 spec (highest risk new spec) - spec-services: irpc service layer + OperationEnv (broadest scope) Phase 0b — Spec updates (6): - spec-update-overview: add crate structure, Layer 3, services - spec-update-auth: IdentityProvider vs AuthService relationship - spec-update-call-protocol: OperationEnv dispatch paths - spec-update-server: DynamicConfig, ForwardingPolicy, IdentityProvider - spec-update-napi: reload API, call protocol references - spec-update-open-questions: resolve OQs per ADR decisions Phase 0b — Assembly (1): - spec-update-readme: add new docs and ADRs to tables Phase 0c — Review (1): - review-spec-foundation: validate consistency checklist Generation structure (6 total): Gen 1: 6 independent ADRs (parallel) Gen 2: adr-027, adr-028 (depend on adr-029) Gen 3: adr-033 + 6 spec docs + open-questions update (parallel) Gen 4: adr review + interface/services specs + 4 spec updates Gen 5: call-protocol update + readme update Gen 6: spec review
This commit is contained in:
61
tasks/architecture/spec-update-call-protocol.md
Normal file
61
tasks/architecture/spec-update-call-protocol.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
id: architecture/spec-update-call-protocol
|
||||
name: Update call-protocol.md — add OperationEnv dispatch paths, irpc as backend
|
||||
status: pending
|
||||
depends_on:
|
||||
- architecture/adr-033-operationenv-irpc-call-protocol
|
||||
- architecture/spec-services
|
||||
- architecture/spec-interface
|
||||
scope: moderate
|
||||
risk: medium
|
||||
impact: phase
|
||||
level: implementation
|
||||
---
|
||||
|
||||
## Description
|
||||
|
||||
Update `docs/architecture/call-protocol.md` to add OperationEnv as the universal composition mechanism with three dispatch paths, and show how irpc is one backend for OperationEnv (not a replacement).
|
||||
|
||||
The current call-protocol.md already covers: operation paths, EventEnvelope wire format, call protocol events, bidirectional routing, head/worker architecture, operation registry, ACL, service discovery, PendingRequestMap, and protocol adapter layer. It was already updated for head/worker terminology.
|
||||
|
||||
**What's missing** (per integration plan):
|
||||
1. **OperationEnv as universal composition mechanism** — the handler-facing API that unifies local calls, irpc service calls, and remote call protocol calls
|
||||
2. **Three dispatch paths** — local dispatch, irpc service dispatch, remote dispatch, all producing the same ResponseEnvelope
|
||||
3. **OperationContext** — request_id, parent_request_id, identity, metadata, env, trusted
|
||||
4. **How irpc is one backend** — not a replacement for the call protocol or for OperationEnv
|
||||
5. **How a call protocol handler can call an irpc service internally** (e.g., /head/auth/verify calls AuthProtocol::VerifyPubkey)
|
||||
|
||||
**What stays the same**: Operation paths, EventEnvelope, call protocol events, bidirectional routing, head/worker architecture, PendingRequestMap, protocol adapter layer.
|
||||
|
||||
**Note**: Hub/spoke was already updated to head/worker. ADR references are partial (currently references 018, 024, 025).
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] OperationEnv section added, documenting it as universal composition mechanism per ADR-033
|
||||
- [ ] Three dispatch paths documented with examples: local (zero serialization), irpc service (postcard), remote (JSON EventEnvelope)
|
||||
- [ ] OperationContext struct documented (request_id, parent_request_id, identity, metadata, env, trusted)
|
||||
- [ ] ResponseEnvelope as universal return type documented
|
||||
- [ ] Operation handlers receive `(input: Value, context: OperationContext) -> ResponseEnvelope`
|
||||
- [ ] irpc explicitly positioned as one dispatch backend for OperationEnv per ADR-033
|
||||
- [ ] Shows how a call protocol handler can internally call an irpc service (example: /head/auth/verify → AuthProtocol::VerifyPubkey)
|
||||
- [ ] Hard constraint stated: OperationEnv composition model matches @alkdev/operations behavioral contract
|
||||
- [ ] ADR table updated with references to 028, 033
|
||||
- [ ] Reference to services.md for full OperationEnv and irpc service details
|
||||
- [ ] Reference to interface.md for how EventEngrams flow from interfaces
|
||||
- [ ] `last_updated` in YAML frontmatter updated
|
||||
- [ ] No hub/spoke terminology in any new content
|
||||
|
||||
## References
|
||||
|
||||
- docs/architecture/call-protocol.md — current content to update
|
||||
- docs/research/integration-plan.md — call-protocol.md update entry
|
||||
- docs/architecture/decisions/033-operationenv-irpc-call-protocol.md
|
||||
- @alkdev/operations — TypeScript OperationEnv
|
||||
|
||||
## Notes
|
||||
|
||||
> To be filled by implementation agent
|
||||
|
||||
## Summary
|
||||
|
||||
> To be filled on completion
|
||||
Reference in New Issue
Block a user