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,69 @@
---
id: architecture/spec-services
name: Create services.md architecture spec (irpc service layer + OperationEnv)
status: pending
depends_on:
- architecture/adr-033-operationenv-irpc-call-protocol
- architecture/adr-027-crate-decomposition
- architecture/adr-028-auth-irpc-service
- architecture/adr-032-event-boundary-discipline
scope: broad
risk: high
impact: project
level: implementation
---
## Description
Create `docs/architecture/services.md` — the irpc service layer spec. This integrates three things that the research treated separately:
1. **irpc service protocols** — AuthProtocol, SecretProtocol, ConfigProtocol, StorageProtocol — their enum definitions, wire formats, and backends
2. **OperationEnv** — the universal composition mechanism with three dispatch paths (local, irpc, remote)
3. **OperationContext** — the request context that handlers receive
This is the second most complex new spec (after interface.md). The integration plan spends the most words on this topic because it's where the most confusion existed between irpc services, call protocol operations, and external services.
The spec must make it crystal clear:
- irpc services are in-cluster, Rust-to-Rust, postcard serialization
- Call protocol operations are cross-node, cross-language, JSON EventEnvelope
- OperationEnv unifies them from the handler's perspective
- An irpc service can back a call protocol operation via OperationEnv
- Both are Layer 3 but at different scope boundaries
**Source**: `docs/research/services.md` (808 lines) + integration plan's OperationEnv and dispatch path sections + ADR-033
## Acceptance Criteria
- [ ] `docs/architecture/services.md` exists with YAML frontmatter (`status: draft`)
- [ ] Follows spec format: What, Why, Architecture, Constraints, Open Questions, Design Decisions
- [ ] Documents irpc service pattern: `#[rpc_requests]` enum, Serializable vs WithChannels, `Client<S>`
- [ ] Documents all four service protocols: AuthProtocol, SecretProtocol, ConfigProtocol, StorageProtocol (type signatures, not full implementations — those go in per-crate specs)
- [ ] Documents OperationContext struct: request_id, parent_request_id, identity, metadata, env, trusted
- [ ] Documents OperationEnv as universal composition mechanism per ADR-033
- [ ] Shows three dispatch paths with examples: local (direct call), irpc service (postcard over mpsc/QUIC), remote (call protocol EventEnvelope)
- [ ] Shows OperationEnv wiring for minimal and production deployments
- [ ] Shows how adapters (MCP, OpenAPI, HTTP, DNS) map to OperationEnv
- [ ] Consistent naming: irpc service / operation / external service (per ADR-033)
- [ ] Composition diagram: Call Protocol → irpc Service → Honker Streams (per ADR-032)
- [ ] Hard constraint stated: handler-facing OperationEnv API matches @alkdev/operations behavioral contract
- [ ] Event boundary per ADR-032: domain events never cross boundaries without projection
- [ ] References ADR-027, ADR-028, ADR-032, ADR-033
- [ ] `docs/architecture/README.md` updated to include services.md
## References
- docs/research/services.md — full service protocol definitions, OperationContext, OperationEnv
- docs/research/integration-plan.md — OperationEnv section, three dispatch paths, adapter patterns
- docs/architecture/decisions/033-operationenv-irpc-call-protocol.md
- docs/architecture/decisions/027-crate-decomposition.md
- docs/architecture/decisions/028-auth-irpc-service.md
- docs/architecture/decisions/032-event-boundary-discipline.md
- @alkdev/operations — TypeScript OperationEnv implementation
## Notes
> To be filled by implementation agent
## Summary
> To be filled on completion