glm-5.1
84f16d66e7
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
69 lines
3.6 KiB
Markdown
69 lines
3.6 KiB
Markdown
---
|
|
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 |