alknet/tasks/architecture/spec-services.md at 84f16d66e79e19dbdbddb9e25bbb3254ef0be760 - alknet - Gitea: Git with a cup of tea

alkdev/alknet

Files

glm-5.1 84f16d66e7 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

2026-06-07 09:01:01 +00:00

3.6 KiB

Raw Blame History

id, name, status, depends_on, scope, risk, impact, level

id

name

status

depends_on

scope

risk

impact

level

architecture/spec-services

Create services.md architecture spec (irpc service layer + OperationEnv)

pending

architecture/adr-033-operationenv-irpc-call-protocol

architecture/adr-027-crate-decomposition

architecture/adr-028-auth-irpc-service

architecture/adr-032-event-boundary-discipline

broad

high

project

implementation

Description

Create docs/architecture/services.md — the irpc service layer spec. This integrates three things that the research treated separately:

irpc service protocols — AuthProtocol, SecretProtocol, ConfigProtocol, StorageProtocol — their enum definitions, wire formats, and backends
OperationEnv — the universal composition mechanism with three dispatch paths (local, irpc, remote)
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