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:
2026-06-07 09:01:01 +00:00
parent 5c820a41e9
commit 84f16d66e7
15 changed files with 877 additions and 0 deletions

View 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