Synced from `specs/repo.yaml`
Stable roots9
contractcoreroutermiddlewaresecuritystorehealthlogmetrics
Modules Overview
Modules Overview
Section titled “Modules Overview”Plumego keeps long-lived public packages at the repository root and places optional or fast-moving capabilities under x/*. This split is intentional: it keeps the stable surface small, keeps ownership easier to classify, and prevents the default learning path from being redefined by extension work.
Tier summary
Section titled “Tier summary”| Tier | Count | Adoption guidance |
|---|---|---|
| Stable (GA) | 9 packages | Production-ready. v1 compatibility promise applies. |
| Beta | 7 families | API frozen between consecutive minor release refs. Production-safe with release-note checks before upgrading. |
| Experimental | 7 primary families | API may change without a deprecation period. Wrap behind an app-local interface in stable service paths. |
Full maturity evidence, per-extension dashboard, and release matrix: Status →
Synced module inventory
Section titled “Synced module inventory”Synced from `specs/task-routing.yaml`
Primary extension families14
x/tenantx/fileapix/messagingx/gatewayx/restx/websocketx/frontendx/observabilityx/openapix/resiliencex/rpcx/datax/aix/validate
These lists are generated by the prebuild sync scripts instead of being hand-maintained twice.
Repository layer map
Section titled “Repository layer map”1stable rootskernel, router, contract, middleware
2reference appbootstrap, route wiring, handlers
3x/*optional families, start from the primary entrypoint
4docs/specs/tasksintent, machine rules, execution scope
1
Default service path
kernel, router, contract, middleware
2
Runnable shape
bootstrap, route wiring, handlers
3
Capability work
optional families, start from the primary entrypoint
4
Control plane
intent, machine rules, execution scope
stable roots core router contract middleware security store health log metrics
x/* families optional capability and protocol surfaces
control plane reference docs specs tasks module.yamlClassification matrix
Section titled “Classification matrix”| Work type | Start here | Why |
|---|---|---|
| Kernel, lifecycle, route structure, transport contracts, or stable middleware | Stable Roots | This is the default path every service should understand |
| Capability, protocol, tenant, gateway, data-topology, or observability-adapter work | x/* Family | Optional capability work should not expand stable roots |
| App-local bootstrap and service wiring | Reference App | The canonical service shape lives outside runtime package ownership |
| Ownership rules, routing taxonomy, import boundaries, or execution scope | Repository Boundaries | These are docs/specs/tasks control-plane questions |
Extension entrypoint rule
Section titled “Extension entrypoint rule”| If the work is about | Start at | Then go narrower when |
|---|---|---|
| Messaging, queues, pubsub, scheduling, or webhooks | x/messaging |
The task is clearly scheduler-, webhook-, pubsub-, or mq-specific |
| Edge transport, reverse proxying, or load balancing | x/gateway |
The task is clearly discovery- or ipc-specific |
| Reusable resource-interface work | x/rest |
You are inside a specific CRUD/resource controller concern |
| Higher-level observability adapters | x/observability |
The task is clearly ops- or devtools-specific |
| Data topology, sharding, durable KV, or read/write splitting | x/data |
The task is clearly cache-specific |
Module primers to open next
Section titled “Module primers to open next”Once the top-level question is clear, continue into the primer that matches the owning module.
Stable roots — ga
Section titled “Stable roots — ga”These modules carry the v1 stable-root compatibility promise. They are the recommended first scope for production evaluation.
| If the question is mainly about | Open this primer next | Why this is the right next read |
|---|---|---|
| app construction, lifecycle, and route attachment | Core Primer · Stable | core owns the HTTP application kernel and the canonical lifecycle path |
| HTTP transport wrappers, request IDs, tracing, rate limiting, and access logging | Middleware Primer · Stable | middleware keeps ordering-sensitive HTTP behavior narrow and explicit |
| route matching, path parameters, route groups, and reverse routing | Router Primer · Stable | router owns the trie-based route matching surface |
| request/response contracts, error model, context helpers, and trace metadata | Contract Primer · Stable | contract defines the canonical error and response shape every handler uses |
| auth primitives, JWT, password helpers, security headers, and input validation | Security Primer · Stable | security provides fail-closed authentication and validation primitives |
| storage contracts, file abstractions, cache primitives, and idempotency contracts | Store Primer · Stable | store defines the stable persistence layer before topology-heavy data concerns begin |
| liveness and readiness model types and health aggregation | Health Primer · Stable | health owns the component checker contracts and readiness state model |
| base logging contracts and structured logger wiring | Log Primer · Stable | log defines the logging surface that extensions and stable roots share |
| base metrics contracts and collector registration | Metrics Primer · Stable | metrics defines the metrics surface without owning exporter or adapter behavior |
Extension families
Section titled “Extension families”Start from the primary family entrypoint, not from subordinate packages. Use the maturity tier as your adoption signal.
API is frozen between consecutive minor release refs. Safe to adopt in production; check release notes before upgrading.
| If the question is mainly about | Open this primer next | Promoted | Subordinate packages |
|---|---|---|---|
| reusable CRUD transport and resource route standardization | x/rest Primer | v0.2.0 | — |
| real-time WebSocket connection lifecycle, hub management, or auth | x/websocket Primer | v0.2.0 | — |
| reverse proxying, gateway routing, load balancing, or edge transport | x/gateway Primer | v0.2.0 | x/gateway/discovery · x/gateway/ipc (experimental) |
| Prometheus exporters, OTel wiring, record buffering, or DB analytics | x/observability Primer | v0.2.0 | x/observability/ops · x/observability/devtools (experimental) |
| multi-tenant resolution, policy, quota, rate limiting, or session | x/tenant Primer | v1.1.0 | resolve, policy, quota, ratelimit, session, store |
| static asset serving, embedded FS, or SPA fallback routing | x/frontend Primer | v1.1.0 | — |
| app-facing queue, pubsub, scheduler, or webhook orchestration | x/messaging Primer | v1.1.0 (app-facing) | scheduler · webhook · pubsub · mq (subordinate primitives are experimental) |
Beta surfaces in experimental families
Section titled “Beta surfaces in experimental families”The parent family root is still experimental, but these subpackages have release-backed API stability at v1.1.0.
| Beta surfaces | Parent family primer | Notes |
|---|---|---|
x/ai/provider · x/ai/session · x/ai/streaming · x/ai/tool |
x/ai Primer | Use these subpackages for stable AI work; remaining subpackages and the root family are experimental |
x/data/file · x/data/idempotency |
x/data Primer | Use these subpackages for stable file and idempotency work; topology surfaces and x/data/cache remain experimental |
Experimental
Section titled “Experimental”API compatibility is not frozen. Evaluate before adopting; wrap behind an app-local interface in stable service paths.
| If the question is mainly about | Open this primer next | Subordinate packages |
|---|---|---|
| AI provider adapters, session, streaming, or tool invocation | x/ai Primer | provider, session, streaming, tool are beta surfaces — see above; orchestration, semanticcache, distributed, resilience remain experimental |
| read-write splitting, sharding, durable KV, or idempotency topology | x/data Primer | x/data/cache; file and idempotency are beta surfaces — see above |
| HTTP transport for file upload, download, or streaming delivery | x/fileapi Primer | — |
| shared circuit breakers, retry wrappers, or resilience adapters across extensions | x/resilience Primer | — |
| gRPC + HTTP service hosting or outbound RPC client pooling | x/rpc Primer | — |
| OpenAPI 3.1 document generation from registered routes | x/openapi Primer | — |
| explicit JSON binding and caller-owned request validation | x/validate Primer | — |
What this page should help you avoid
Section titled “What this page should help you avoid”The current repo actively discourages broad or ambiguous roots such as ai, tenant, rest, pubsub, frontend, utils, or validator at the top level. If the name sounds like a feature catalog or a vague bucket, it is probably the wrong place to begin.
Read next
Section titled “Read next”- API Quick Reference — complete function signatures for core, contract, and router
- Stable Roots
- x/* Family
- Core Primer
- x/rest Primer
- Repository Boundaries