coding-os 0.3.2__py3-none-any.whl

core/skills/graph-explorer/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: graph-explorer
+tier: exploration
+domain: [universal]
+description: Navigate the graph_os knowledge graph before editing load-bearing code. Use when tracing dependencies, planning a rename, auditing API surface, or answering "what breaks if I change this?". Pairs with codebase-explorer — graph-explorer wins for symbol-precise queries, codebase-explorer wins for conceptual code-reading.
+last_reviewed: "2026-05-11"
+
+---
+
+# graph-explorer
+
+Purpose: Load the graph_os toolset (`cos_graph_*` MCP tools) and
+use it deliberately before any non-trivial code edit. The graph is the
+third retrieval layer (CLAUDE.md Three-Layer Retrieval) — use it when
+tree-grep or past-memory searches return noise.
+
+Read when: Editing `src/core/**` or `src/cli/**`, producing a rename plan,
+auditing API/MCP contracts, answering "what depends on X".
+
+Skip when: You already know the blast radius, or the change is a
+self-contained one-file edit with no callers.
+
+## Decision ladder
+
+1. **Need to know "what calls this?"** → `cos_graph_references(uid)`.
+2. **Need surrounding context before editing?** → `cos_graph_context(uid_or_name, depth=1)` (Implementer pre-impl step).
+3. **Planning a refactor?** → `cos_graph_impact(uid, depth=3)` (Analyst dependency map) groups edges by risk tier.
+4. **Renaming a symbol?** → `cos_graph_rename_plan(uid, new_name)` before any `Edit` — returns call-sites, doc refs, tests, string literals.
+5. **API / contract audit?** → `cos_graph_contracts(kinds=["http","mcp"])` (Documenter + Deployer).
+6. **Tracing a fault?** → `cos_graph_trace(entry_uid)` (Debugger fault isolation step).
+7. **"Is anything similar?"** → `cos_graph_similar(uid, top_k=5)`.
+8. **Shortest dependency path?** → `cos_graph_path(source, target)`.
+9. **Need a diagram?** → `cos_graph_export(format="mermaid", root_uid=...)`.
+10. **Pre-commit self-review?** → `cos_graph_detect_changes(files=[...])` — call BEFORE `make verify`.
+
+> **Method blast-radius — use `impact`, not bare `references(kinds="calls")`.**
+> Static AST cannot resolve instance-method calls on locally-typed
+> receivers (`backend.upsert_node(...)` — the type of `backend` is
+> unknown), so `references(method, kinds="calls")` under-reports those
+> call sites. `cos_graph_impact` compensates by traversing
+> method→class→`constructs`, so "what breaks if I change this method?"
+> stays complete. Treat `references(calls)` as a lower bound for methods.
+
+> **Function blast-radius — import bindings are first-class (TASK-402).**
+> Every `from M import name` site emits an `import_` node which the
+> `link_import_bindings` pass binds to the real symbol (exactly-one
+> match; ambiguous → skipped, never guessed). `references(function)`
+> with default kinds therefore returns BOTH direct `calls` edges AND
+> `imports` edges whose `import_` source node carries the caller's
+> `file_path` — the init_db probe went from 6 to 80 of 106 caller files
+> once this pass landed. Two caller classes stay invisible to static
+> resolution and need a grep complement on security-critical sweeps:
+> module-alias attribute calls (`import database as db; db.init_db()`)
+> and calls embedded in string literals (`python -c "from … import …"`).
+
+Every response carries `data.meta.layer="graph"` and `data.meta.backend`
+(`sqlite` — the single store since Kùzu was retired 2026-05-18). The
+`meta.backend_fallback` flag is reserved for a future graph-native
+plug-in; today it is always absent/false, so you never need to treat a
+result as a lower-precision fallback.
+
+## Coverage contract — never trust a single call blindly
+
+The biggest soundness trap in graph queries is **silent truncation**:
+asking "who calls X?" on a 500-caller hub with `limit=100` (the
+default) returns 100 rows and **no signal** that 400 more exist —
+unless you read the coverage metadata. Every coverage-sensitive tool
+exposes it; the rule below is mandatory before you act on a result.
+
+### Signals to read on every response
+
+| Tool | `data.total_count` | Coverage signal in meta | `data.meta.<budget>` |
+|---|---|---|---|
+| `cos_graph_references` | ✓ | `result_truncated` (limit hit or token-trim) | `limit` |
+| `cos_graph_impact` | – | `walk_truncated` (BFS cap hit) | `visit_limit` · `depth` |
+| `cos_graph_context` | – | `walk_truncated` (BFS cap hit) | `visit_limit` · `depth` |
+| `cos_graph_path` | – | `walk_truncated` (hop saturation) | `hop_limit` |
+| `cos_graph_export` | – | `result_truncated` + `max_nodes_requested` vs `max_nodes_effective` (ceiling 50k); Hub badge renders the same meta | `max_nodes` · `max_hops` |
+
+**`result_truncated == true` or `walk_truncated == true` ⇒ the answer
+is incomplete. Do NOT proceed on it.**
+
+Why two names? `result_truncated` / `walk_truncated` flag *coverage*
+truncation (a caller `limit` or BFS cap was hit); `data.meta.truncated`
+flags that the envelope's *token-budget* trimmer ran (response too big,
+tail rows dropped). They are separate causes, but a token-budget trim
+that drops list items now ALSO sets `result_truncated` (TASK-056) — the
+trimmer can silently shorten a `contracts` / `references` payload, and
+the coverage check must catch that too. Net: **`result_truncated == true`
+means this list is incomplete for ANY reason — re-query**; `meta.truncated`
+additionally tells you the cause was the token budget.
+
+### The mandatory 2-step probe → widen workflow
+
+```python
+# 1. probe with defaults (cheap, gives you the lay of the land)
+r = cos_graph_references(uid)                  # default limit=100
+total = r["data"]["total_count"]
+shown = r["data"]["count"]
+
+# 2. if incomplete, widen with the actual total
+if r["data"]["meta"]["result_truncated"]:
+    r = cos_graph_references(uid, limit=total)  # exhaustive
+    # alternative: narrow the kinds filter first when total is huge
+    # r = cos_graph_references(uid, kinds=["calls"], limit=total)
+```
+
+For `cos_graph_impact` and `cos_graph_context`, the budget is
+`visit_limit` (default 500 nodes). When `meta.walk_truncated` is true:
+
+```python
+# option A — raise the cap deliberately
+r = cos_graph_impact(uid, depth=3, visit_limit=5000)
+
+# option B — step DOWN in depth and walk each frontier separately
+# (more expensive but produces tier-quality risk grouping)
+r1 = cos_graph_impact(uid, depth=1)
+for caller in r1["data"]["tiers"]["will_break"]:
+    cos_graph_impact(caller["uid"], depth=2)
+```
+
+### Per-task-class budget recipes
+
+| Task class | Tool | Budget |
+|---|---|---|
+| Quick probe ("does X have any callers?") | `cos_graph_references` | `limit=20` |
+| Implementation pre-check ("what neighbours?") | `cos_graph_context` | `depth=1` |
+| Refactor planning ("what breaks?") | `cos_graph_impact` | `depth=3`, `visit_limit=2000` |
+| Rename — must hit every site | `cos_graph_rename_plan` | (exhaustive by design) |
+| Security audit — every caller chain | `cos_graph_references` then `cos_graph_impact` per caller | `limit=10_000`, `visit_limit=10_000` |
+| Doc cross-reference audit | `cos_graph_references` | `kinds=["references_doc","links_to","cites_heading"]`, `limit=1000` |
+
+**Cost math:** `cos_graph_references` is O(N) with an index; `limit=10_000`
+runs in <50 ms on the highest-degree hubs in this repo. There is no
+reason to under-budget a coverage-critical sweep. Pay the 50 ms.
+
+### Anti-patterns
+
+- Calling `cos_graph_references(uid)` once and treating the slice as
+  complete — without reading `total_count` or `meta.truncated`.
+- Setting `limit=20` for a rename or security audit because "small is
+  safer" — small **hides** coverage gaps, doesn't prevent them.
+- Calling `cos_graph_impact(uid, depth=4)` on a hub and not noticing
+  `meta.truncated` — `depth=4` × hub frontier blows past `visit_limit`
+  before you reach the interesting frontier.
+- Asking the graph the same question twice with the same params hoping
+  a different answer comes back — the result is deterministic; widen
+  the budget or narrow the filter.
+
+## Enforcement
+
+- `enforce-graph-context.sh` — when editing a file matching one of the
+  `rag-config.yaml::graph.enforce_context_on` globs, the hook warns (or
+  blocks in strict mode) unless `cos_graph_context` wrote a *fresh*
+  `.graph/ctx-<sha>` marker this session (content-hash-bound — a consult
+  that went stale because the file changed no longer counts).
+  `enforce-skill.sh` reads the same glob list to require `graph-explorer`
+  on those files.
+- `enforce-rename-plan.sh` — if you attempt a multi-file rename-like
+  Edit without a prior `cos_graph_rename_plan` in this session, the
+  hook warns + suggests the command.
+
+Both hooks default to **warn** so agents discover the graph layer
+instead of writing blind. Opt-out with `COS_ENFORCE_GRAPH_CONTEXT=off`
+(or `=0`); promote to block with `=strict`. Same for
+`COS_ENFORCE_RENAME_PLAN`.
+
+## Auto-reindex contract
+
+The PostToolUse hook `auto-reindex-docs.sh` re-indexes **only the file
+just written** via `graph_os.tools.reindex_dispatch.dispatch(path)` —
+not the whole repo. The dispatcher is incremental: it extracts that
+single file's nodes / edges, upserts them into the existing graph
+(idempotent on `uid`), and short-circuits via `file_index_state` when
+the content hash hasn't changed. Typical cost: 20–100 ms per file,
+fire-and-forget background. Use `cos graph-reindex --force` only after
+a bulk shell move (`mv` / `cp` / `git checkout`) where the hook never
+fired.
+
+## Fail-loud failure modes
+
+- MCP backend down → tools return `fail("unavailable", ...)` with
+  `retryable=true`. Retry after `cos graph-reindex` / server restart
+  — do NOT guess.
+- Graph empty (fresh repo) → `_query`/`_context` return empty lists.
+  Run `make docs-index` / `make task-sync` / `cos graph-reindex` first.
+- Confidence below 0.3 → the edge is probably a false positive.
+  `_impact` clusters these under the `context` tier so agents can
+  ignore noise.
+
+## Web UI
+
+For visual exploration, the unified React SPA exposes the graph at
+[http://127.0.0.1:9188/graph](http://127.0.0.1:9188/graph). Start it
+with `cos hub start` (FastAPI + uvicorn singleton on port 9188 that
+serves every registered project). The page picks a root node, runs
+depth-bounded BFS, and renders with Sigma.js + Graphology — useful
+when:
+
+- An impact/rename plan returns >10 affected files and the agent (or
+  user) wants to see clusters before approving.
+- Walking a CONTAINS spine (Folder→File→Class→Method) is easier than
+  re-issuing tool calls.
+- Sharing a snapshot with a human collaborator who needs to *see* the
+  blast radius rather than read JSON envelopes.
+
+For one-off static export (no live server, embeddable HTML), the
+legacy `cos graph-viz` command still works — kept intentionally for
+sharing/embedding.
+
+## Link-backs
+
+- Knowledge-graph plan: [docs/phase-i-knowledge-graph-plan.md](../../../docs/phase-i-knowledge-graph-plan.md)
+- MCP envelope: [docs/engineering/mcp-error-envelope.md](../../../docs/engineering/mcp-error-envelope.md)
+- Rule 14 (envelope): [CLAUDE.md](../../../CLAUDE.md)

core/skills/graph-explorer/scripts/explain-impact.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Pretty-print cos_graph_impact output for human review.
+# Reads JSON from stdin (the raw envelope from cos_graph_impact) and
+# renders it as a tier-grouped checklist suitable for a human reviewer
+# or a PR description.
+#
+# Usage:
+#   cos_graph_impact <uid> | bash explain-impact.sh
+#
+# Falls back to readable output even if jq is missing.
+set -euo pipefail
+
+# Safety: ensure core POSIX tools resolvable even when caller PATH is restricted.
+export PATH="/usr/bin:/bin:/usr/local/bin:${PATH:-}"
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "[explain-impact] jq not installed — emitting raw JSON" >&2
+  cat
+  exit 0
+fi
+
+INPUT="$(cat)"
+
+# Envelope check
+if ! echo "$INPUT" | jq -e '.ok' >/dev/null 2>&1; then
+  err_cat=$(echo "$INPUT" | jq -r '.error.category // "unknown"')
+  err_msg=$(echo "$INPUT" | jq -r '.error.message // "no message"')
+  echo "FAIL: cos_graph_impact returned $err_cat — $err_msg" >&2
+  exit 1
+fi
+
+ROOT=$(echo "$INPUT" | jq -r '.data.root_uid // .data.uid // "(unknown)"')
+TOTAL=$(echo "$INPUT" | jq -r '.data.edges | length // 0')
+
+cat <<EOF
+# Impact analysis — $ROOT
+Total edges: $TOTAL
+
+EOF
+
+# Group by tier. Tiers (per graph-explorer SKILL.md): strong / weak / context.
+for tier in strong weak context; do
+  count=$(echo "$INPUT" | jq -r --arg t "$tier" '[.data.edges[] | select((.tier // "context") == $t)] | length')
+  if [ "$count" -eq 0 ]; then
+    continue
+  fi
+  cat <<EOF
+## $tier tier ($count)
+
+EOF
+  echo "$INPUT" | jq -r --arg t "$tier" '
+    .data.edges[]
+    | select((.tier // "context") == $t)
+    | "- \(.kind) — `\(.target_uid)` (conf=\(.confidence // "?"))\(if .file_path then " — \(.file_path):\(.start_line // "?")" else "" end)"'
+  echo
+done
+
+# Optional: rename-plan hint if many sites
+if [ "$TOTAL" -gt 10 ]; then
+  cat <<'EOF'
+> **Heads-up:** > 10 affected sites. Consider running `cos_graph_rename_plan`
+> for a sequenced edit checklist before opening any `Edit`.
+EOF
+fi

core/skills/graphql/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: graphql
+description: Build and operate production GraphQL servers — schema-first SDL design, resolver architecture, the N+1 problem and DataLoader batching, pagination (Relay cursor connections), error handling, schema federation/stitching, persisted queries, and depth/complexity/cost limiting. Use when authoring a GraphQL schema or resolver, debugging N+1 query storms, designing a federated supergraph, hardening a public GraphQL endpoint, or choosing Apollo / graphql-yoga / gqlgen / Strawberry. Boundary vs api-design — api-design owns the protocol-neutral contract decision (REST vs GraphQL, versioning strategy, idempotency keys, RFC 9457 error envelopes for HTTP) and stops at "pick GraphQL"; this skill owns everything GraphQL-internal after that pick (SDL types, resolver/DataLoader runtime, GraphQL-native errors, federation), and defers raw realtime transport to realtime-websockets even when delivering GraphQL subscriptions.
+tier: cross-cutting
+domain: [backend]
+depends_on:
+  - api-design
+  - clean-code
+  - observability
+last_reviewed: "2026-06-14"
+---
+
+# GraphQL — Schema, Resolvers, Federation, Hardening
+
+A practical guide to running GraphQL in production. Stack-agnostic; concrete patterns reference Apollo Server / graphql-yoga (Node), Strawberry / Ariadne (Python), and gqlgen (Go).
+
+## When to Use This Skill
+
+- Authoring a new GraphQL schema (SDL) or adding types/fields to an existing one.
+- Writing or reviewing resolvers — especially when an endpoint is slow under load.
+- Diagnosing an N+1 query storm (one list query firing hundreds of row fetches).
+- Designing pagination for a GraphQL list field (Relay cursor connections).
+- Splitting a monolith schema into a federated supergraph (Apollo Federation / schema stitching).
+- Hardening a public GraphQL endpoint against deep/expensive queries.
+- Choosing a server library or deciding persisted-queries vs ad-hoc queries.
+
+Skip when: the decision is still "REST or GraphQL" (that is api-design's call), or the transport question is "how do I push live updates over a socket" (that is realtime-websockets).
+
+## Boundary — GraphQL vs api-design vs realtime-websockets
+
+| Concern | Owner |
+|---|---|
+| REST vs GraphQL decision, versioning posture, idempotency keys, RFC 9457 HTTP error envelope | **api-design** |
+| SDL type design, resolver architecture, DataLoader, GraphQL `errors[]` + `extensions`, federation, persisted queries, depth/cost limits | **graphql** (this skill) |
+| The websocket transport carrying `graphql-ws` subscription frames, heartbeats, backpressure, reconnect | **realtime-websockets** |
+
+api-design decides *whether* the API is GraphQL and how it errors at the HTTP layer; this skill decides *how* the GraphQL schema and runtime behave once that choice is made. Subscriptions are defined here (the `Subscription` type, resolver, event source) but the socket they ride is realtime-websockets' job.
+
+## Schema-First — SDL Is the Contract
+
+Author the schema in SDL before writing a resolver. The SDL is the source of truth; codegen produces typed resolver signatures from it, never the reverse.
+
+```graphql
+type Query {
+  order(id: ID!): Order
+  orders(first: Int!, after: String): OrderConnection!
+}
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  lineItems: [LineItem!]!   # nullability is a contract — see below
+  customer: Customer!
+}
+
+enum OrderStatus { PENDING PAID SHIPPED CANCELLED }
+```
+
+**Nullability is load-bearing.** A non-null field (`!`) that resolves to null nulls out its *entire parent object* and propagates up to the nearest nullable ancestor. Mark a field non-null only when the resolver can truly never return null; default to nullable for any field backed by a remote call that can fail.
+
+**Design rules:**
+
+- **Nouns and fields, not verbs.** Mutations are the only verbs (`createOrder`, `cancelOrder`). Queries are nouns.
+- **One input type per mutation.** `createOrder(input: CreateOrderInput!)` — never a long positional arg list. Additive input fields are non-breaking; positional args are not.
+- **Return a payload type from every mutation**, not the bare entity: `type CreateOrderPayload { order: Order, userErrors: [UserError!]! }`. This carries field-level business errors without using the transport `errors[]` array (see error section).
+- **Enums over magic strings.** Adding an enum value is non-breaking for outputs; removing one is breaking.
+
+## The N+1 Problem — DataLoader Is Mandatory
+
+The defining GraphQL performance trap: a query for 100 orders, each resolving `customer`, fires 1 + 100 database round-trips. GraphQL resolves fields depth-first per-object, so naive resolvers multiply.
+
+```js
+// BAD — one DB hit per order
+const resolvers = {
+  Order: {
+    customer: (order) => db.customer.findById(order.customerId),  // N+1
+  },
+};
+
+// GOOD — batch within a single tick via DataLoader
+const customerLoader = new DataLoader(async (ids) => {
+  const rows = await db.customer.findManyByIds(ids);   // ONE query
+  const byId = new Map(rows.map((r) => [r.id, r]));
+  return ids.map((id) => byId.get(id) ?? null);        // MUST preserve order + arity
+});
+
+const resolvers = {
+  Order: { customer: (order) => customerLoader.load(order.customerId) },
+};
+```
+
+**DataLoader rules:**
+
+- **One loader instance per request**, never module-global — a shared loader leaks data across users and never invalidates. Construct loaders in the per-request context factory.
+- **The batch function MUST return one result per input key, in input order**, filling misses with `null` (or an `Error` instance). Returning a shorter array silently misaligns every record.
+- **Loaders are read caches scoped to one request.** They are not your application cache. For cross-request caching, layer Redis behind the batch function, not in place of the loader.
+
+DataLoader solves batching, not authorization — still authorize each field (see security).
+
+## Pagination — Relay Cursor Connections
+
+GraphQL's de-facto pagination standard is the Relay Connection spec. Use it for any list that can grow.
+
+```graphql
+type OrderConnection {
+  edges: [OrderEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int        # nullable — expensive; omit on huge sets
+}
+type OrderEdge { node: Order!, cursor: String! }
+type PageInfo { hasNextPage: Boolean!, hasPreviousPage: Boolean!, endCursor: String, startCursor: String }
+```
+
+- **Cursors are opaque.** Base64 an internal keyset token (e.g. `{sort_value, id}`); never expose a raw offset or DB id as the cursor. Clients must not parse them.
+- **`first` + `after` for forward paging; `last` + `before` for backward.** Cap `first`/`last` server-side (e.g. ≤100) and reject larger requests — an uncapped page size is a DoS vector.
+- **Prefer keyset over offset** behind the cursor for growing datasets (consistent with api-design's pagination guidance) — offset pagination is race-prone and slow at depth.
+
+## Error Handling — Two Channels, Don't Confuse Them
+
+GraphQL has two distinct error paths:
+
+1. **Transport `errors[]`** (top-level, per the GraphQL spec) — for *exceptional* failures: a resolver threw, a field was unauthorized, the query was malformed. Attach a stable machine code under `extensions.code` (`UNAUTHENTICATED`, `FORBIDDEN`, `NOT_FOUND`, `INTERNAL`). Strip stack traces, SQL, and file paths from `message` in production exactly as api-design's RFC 9457 rule demands for HTTP.
+
+```json
+{ "errors": [{ "message": "Order not found",
+  "path": ["order"], "extensions": { "code": "NOT_FOUND" } }],
+  "data": { "order": null } }
+```
+
+2. **`userErrors` in the mutation payload** — for *expected* business outcomes (validation failed, insufficient funds). These are part of `data`, are strongly typed, and never abort the operation. A form that fails validation is a successful query returning `userErrors`, not a transport error.
+
+Rule of thumb: if a frontend would `try/catch` it, it is a transport error; if a frontend would render it next to a field, it is a `userError`.
+
+## Hardening a Public Endpoint
+
+A naked GraphQL endpoint lets a client request an arbitrarily deep, arbitrarily expensive query. Three layers, all required for a public schema:
+
+| Control | Why | Tooling |
+|---|---|---|
+| **Depth limit** | Stops recursive `friends { friends { friends … } }` blowups | `graphql-depth-limit`, built-in to most servers |
+| **Cost/complexity limit** | Caps total resolver work per query (weight fields by expense) | `graphql-query-complexity`, Apollo plugin |
+| **Persisted queries (APQ)** | Only pre-registered query hashes run — eliminates arbitrary-query attack surface and shrinks payloads | Apollo APQ, relay persisted |
+| **Disable introspection in prod** | Hides the full schema map from attackers (keep it on in staging) | server config flag |
+| **Per-field authorization** | DataLoader batches but does not authorize; check the viewer on every protected field | resolver guards / schema directives |
+
+Pair these limits with the rate-limit headers and `429`/`Retry-After` discipline from api-design — GraphQL rides HTTP, so HTTP-layer rate limiting still applies.
+
+## Federation vs Stitching
+
+- **Apollo Federation** (`@key`, `@external`, entity references) — the current standard for composing many subgraph schemas into one supergraph at a gateway. Each team owns a subgraph; the gateway plans cross-subgraph queries. Prefer for multi-team org topologies.
+- **Schema stitching** — older, gateway merges remote schemas by type name; more manual conflict resolution. Acceptable for a small number of schemas under one team; federation has largely superseded it.
+- **Avoid premature federation.** One team, one schema → a single executable schema. Federate only when subgraph ownership genuinely splits across teams (mirrors anti-overengineering's rule-of-three).
+
+## Observability for GraphQL
+
+Standard HTTP metrics under-report GraphQL because every operation hits one URL (`POST /graphql`). Instrument by **operation name and field**, not by route:
+
+- Tag traces/metrics with the GraphQL `operationName` and the resolved field path, not the URL (otherwise every dashboard shows one endpoint).
+- Emit a span per resolver for slow fields; the resolver tree maps cleanly onto an OpenTelemetry span tree (see observability skill).
+- Track the `errors[]` rate separately from HTTP 5xx — a GraphQL response is `200 OK` even when `errors[]` is populated, so HTTP-status dashboards miss GraphQL failures entirely.
+
+## Anti-Patterns (reject in review)
+
+1. **Resolver hitting the DB directly without a loader** on a list-reachable field — guaranteed N+1.
+2. **Module-global DataLoader** — cross-request data leak + stale cache.
+3. **Batch function that returns filtered/reordered results** — misaligns keys to values silently.
+4. **Non-null fields backed by fallible remote calls** — one failure nulls the whole parent object.
+5. **Business validation thrown as a transport error** — belongs in `userErrors`.
+6. **`str(exc)` / stack traces in `errors[].message`** in production — info leak, same as api-design's HTTP rule.
+7. **Public endpoint with no depth/cost limit** — trivial DoS.
+8. **Versioned schemas (`/graphql/v2`)** — GraphQL evolves by deprecating fields (`@deprecated(reason:)`), not by versioning the endpoint.
+9. **`updatedAt: String`** for timestamps — use a scalar that enforces RFC 3339 (`DateTime`).
+
+## Pairs With
+
+- **api-design** — owns the upstream REST-vs-GraphQL decision and the HTTP-layer error/idempotency/rate-limit contract this skill builds on.
+- **realtime-websockets** — carries GraphQL subscription frames over a live socket.
+- **observability** — operation-level tracing and the `errors[]`-vs-5xx metric split.
+- **clean-code** — fail-closed resolvers, no info leak in error messages.
+
+## Source Material
+
+- GraphQL Specification (graphql.org/learn) — the canonical SDL + execution model.
+- Relay Cursor Connections Specification — the pagination standard above.
+- Apollo Federation docs — subgraph/supergraph composition.
+- *Production Ready GraphQL* (Marc-André Giroux) — N+1, security, versioning at scale.
+- DataLoader (graphql/dataloader) README — batching + caching contract.

core/skills/grpc-microservices/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: grpc-microservices
+description: Build and operate gRPC services and the service-to-service mesh — Protobuf schema design with wire-compatible evolution, the four RPC kinds (unary, server/client/bidi streaming), deadline propagation, retries and hedging, status-code semantics, interceptors for auth/tracing/metrics, mTLS, load balancing (client-side vs proxy/mesh), and gRPC-Gateway for a REST edge. Use when defining a .proto contract, choosing gRPC vs REST for internal traffic, debugging DEADLINE_EXCEEDED or backward-incompatible schema changes, wiring interceptors, or designing a microservice mesh. Boundary vs api-design — api-design owns the public/external HTTP contract (REST/GraphQL, RFC 9457 envelopes, idempotency keys) for heterogeneous consumers; this skill owns binary east-west gRPC between services controlled on both sides, including Protobuf evolution and gRPC status codes. Defers raw long-lived bidirectional sockets to realtime-websockets and the REST translation edge to api-design.
+tier: cross-cutting
+domain: [backend]
+depends_on:
+  - api-design
+  - clean-code
+  - observability
+last_reviewed: "2026-06-14"
+---
+
+# gRPC + Microservices — Protobuf, RPC, Mesh
+
+A practical guide to gRPC for east-west (service-to-service) traffic. Stack-agnostic; concrete patterns reference `grpc-go`, `grpcio` (Python), and `@grpc/grpc-js` (Node), with Envoy / a service mesh as the proxy layer.
+
+## When to Use This Skill
+
+- Defining or evolving a `.proto` service contract.
+- Choosing gRPC vs REST/GraphQL for traffic *between services you control on both ends*.
+- Debugging `DEADLINE_EXCEEDED`, `UNAVAILABLE`, or a backward-incompatible Protobuf change.
+- Designing streaming RPCs (server-stream, client-stream, bidi).
+- Wiring interceptors for auth, tracing, metrics, retries.
+- Standing up mTLS, client-side load balancing, or a gRPC mesh.
+- Exposing a gRPC service to external REST clients via gRPC-Gateway.
+
+Skip when: the consumer is a browser/mobile/3rd-party over public HTTP (that is api-design's REST/GraphQL territory), or the need is a long-lived bidirectional *browser* socket (that is realtime-websockets).
+
+## Boundary — gRPC vs api-design vs realtime-websockets
+
+| Concern | Owner |
+|---|---|
+| Public, external, heterogeneous HTTP API (REST/GraphQL), RFC 9457 envelopes, URL/header versioning, idempotency keys | **api-design** |
+| Binary east-west gRPC between controlled services: Protobuf evolution, the four RPC kinds, gRPC status codes, deadlines, interceptors, mesh | **grpc-microservices** (this skill) |
+| Long-lived bidirectional sockets to browsers (WebSocket/SSE), heartbeats, reconnect, fan-out | **realtime-websockets** |
+
+The split is **who controls both ends and over what network**. api-design serves consumers that cannot be coordinated and speak HTTP/JSON; this skill serves internal services that share a generated stub and speak HTTP/2 + Protobuf. When a gRPC service must face external REST clients, gRPC-Gateway translates at the edge — and that REST surface is then governed by api-design.
+
+## Protobuf — Schema Evolution Is the Whole Game
+
+The `.proto` is the contract; the wire format is field-number-based, which makes additive evolution safe and renames cheap — *if* the rules are followed.
+
+```protobuf
+syntax = "proto3";
+package orders.v1;
+
+message Order {
+  string id = 1;
+  OrderStatus status = 2;
+  int64 created_at_unix = 3;
+  reserved 4;                 // a removed field's number — NEVER reuse
+  reserved "legacy_total";    // and its name
+  string customer_id = 5;
+}
+
+enum OrderStatus {
+  ORDER_STATUS_UNSPECIFIED = 0;  // proto3 enums MUST have a zero default
+  ORDER_STATUS_PENDING = 1;
+  ORDER_STATUS_PAID = 2;
+}
+
+service OrderService {
+  rpc GetOrder(GetOrderRequest) returns (Order);
+}
+```
+
+**Wire-compatibility rules (violating these breaks deployed clients):**
+
+- **Field numbers are forever.** Adding a field = new number = backward-compatible. Removing a field → `reserved` its number and name so they are never reused.
+- **Never change a field's type or number.** `int32`→`int64` is wire-compatible in some cases but `int`→`string` is not; treat type changes as breaking.
+- **Every proto3 enum needs a `_UNSPECIFIED = 0`** default — an unset enum reads as zero, and a meaningful zero hides "field absent".
+- **Package the version (`orders.v1`).** A genuinely breaking redesign ships as `orders.v2` in a new package, run side-by-side — the gRPC analog of api-design's URL versioning.
+- **Buf for lint + breaking-change detection in CI** — `buf breaking` against the main branch is the gRPC equivalent of api-design's schema/contract tests; make it a merge gate.
+
+## The Four RPC Kinds
+
+| Kind | Shape | Use when |
+|---|---|---|
+| **Unary** | 1 req → 1 resp | The default; most calls. Maps to a REST-like operation. |
+| **Server streaming** | 1 req → N resp | Server pushes a sequence: a result feed, progress, a large paged export. |
+| **Client streaming** | N req → 1 resp | Client uploads a stream: telemetry ingest, chunked upload, aggregation. |
+| **Bidirectional** | N req ↔ N resp | Both stream independently: chat-like internal protocols, live sync. |
+
+Streaming RPCs are *internal* plumbing. For browser-facing live updates, prefer WebSocket/SSE (realtime-websockets) — browsers cannot speak native gRPC streaming without grpc-web's limitations.
+
+## Deadlines — Propagate, Never Drop
+
+The single most important gRPC reliability discipline: **every call carries a deadline, and the deadline propagates down the call chain.** Without it, a slow downstream service holds the whole chain's threads hostage and cascades into a fleet-wide outage.
+
+```go
+// Caller sets an absolute deadline; gRPC propagates it as a header.
+ctx, cancel := context.WithTimeout(ctx, 300*time.Millisecond)
+defer cancel()
+resp, err := client.GetOrder(ctx, &pb.GetOrderRequest{Id: id})
+
+// Callee budgets the REMAINING time across its own downstream calls.
+if deadline, ok := ctx.Deadline(); ok && time.Until(deadline) < dbBudget {
+    return nil, status.Error(codes.DeadlineExceeded, "insufficient time budget")
+}
+```
+
+- **Set a deadline on every outbound call** — a missing deadline is an unbounded hang.
+- **Budget the remaining deadline across downstream calls** — do not pass the full parent deadline to each child; the chain must fit inside the caller's budget.
+- **Cancellation propagates** — when the caller's context is cancelled, abort in-flight downstream work; do not finish wasted computation.
+
+## Status Codes + Retries
+
+gRPC has its own status enum (not HTTP statuses). Map domain errors to the right code — clients (and retry policies) branch on it.
+
+| gRPC code | Meaning | Retryable? |
+|---|---|---|
+| `OK` | success | — |
+| `INVALID_ARGUMENT` | client sent bad input | no |
+| `NOT_FOUND` | entity absent | no |
+| `ALREADY_EXISTS` / `FAILED_PRECONDITION` | conflict / state mismatch | no |
+| `PERMISSION_DENIED` / `UNAUTHENTICATED` | authz / authn | no |
+| `DEADLINE_EXCEEDED` | ran out of time | yes (with backoff) |
+| `UNAVAILABLE` | transient — server down/restarting | yes (with backoff) |
+| `RESOURCE_EXHAUSTED` | rate-limited / quota | yes (honor backoff) |
+| `INTERNAL` / `UNKNOWN` | server bug | no (don't retry a bug) |
+
+- **Retry only the retryable codes**, with exponential backoff + jitter, via the built-in gRPC retry policy (service config) — not hand-rolled loops.
+- **Retries require idempotency.** A retried mutation must be safe — pass an idempotency key in metadata (consistent with api-design's idempotency rule) so a duplicate is deduped server-side.
+- **Hedging** (fire a second attempt after a delay, take the first response) cuts tail latency for read-heavy paths — enable it only for genuinely idempotent reads.
+- **Strip internals from status messages** in production — no stack traces or SQL in the `status.message`, same discipline as api-design's HTTP errors. Use `error_details` (`google.rpc.Status`) for structured, machine-readable detail.
+
+## Interceptors — Cross-Cutting Plumbing
+
+Interceptors (middleware) are where auth, tracing, metrics, and retries live — never copy-pasted into each handler.
+
+- **Order matters:** recovery (panic → `INTERNAL`) outermost, then tracing, then auth, then metrics, then the handler. A panic must never crash the server process.
+- **Auth interceptor** validates the token from call metadata and injects the identity into context; handlers read identity from context, never re-parse the token.
+- **Tracing/metrics interceptors** emit one span + RED metrics per RPC automatically (see observability) — tag by `service/method`, never by a per-entity id (cardinality).
+
+## Transport Security + Load Balancing
+
+- **mTLS for east-west by default.** Services authenticate *each other* with certificates; a service mesh (Istio/Linkerd) can provide this transparently, or do it in-process. Plaintext gRPC belongs only inside a trusted boundary, never across one.
+- **Load balancing is L7, not L4.** gRPC multiplexes many calls over one long-lived HTTP/2 connection, so a naive L4 (TCP) load balancer pins all traffic to one backend. Use **client-side LB** (gRPC's `round_robin`/`pick_first` + service discovery) or an **L7 proxy/mesh** (Envoy) that understands HTTP/2 streams.
+- **Connection reuse:** keep a long-lived channel per upstream; do not open a channel per call (the handshake cost dominates). Tune keepalive pings so idle channels stay healthy through proxies.
+
+## gRPC-Gateway — The REST Edge
+
+When external clients need REST/JSON over a gRPC service, generate a reverse-proxy from `google.api.http` annotations.
+
+- Annotate RPCs (`option (google.api.http) = { get: "/v1/orders/{id}" }`); gRPC-Gateway emits a REST handler that transcodes JSON↔Protobuf.
+- **The REST surface it exposes is governed by api-design** — RFC 9457 errors, pagination, versioning all apply to that edge. gRPC owns the internal contract; api-design owns the translated public one. Keep the two boundaries explicit so the same operation does not get two competing error formats.
+
+## Anti-Patterns (reject in review)
+
+1. **Reusing a `reserved` field number** — silently corrupts deployed clients reading the old number.
+2. **Changing a field's type or number** in place — wire-incompatible; ship a v2 package instead.
+3. **No `_UNSPECIFIED = 0` enum default** — unset reads as a real value, hiding "absent".
+4. **Calls without a deadline** — an unbounded hang that cascades across the mesh.
+5. **Passing the full parent deadline to every child** — the chain can't fit; budget it.
+6. **Retrying non-idempotent mutations** or non-retryable codes (`INVALID_ARGUMENT`, `INTERNAL`).
+7. **L4 load balancer in front of gRPC** — pins all multiplexed calls to one backend.
+8. **A channel per call** — pays the HTTP/2 + TLS handshake every time.
+9. **Plaintext gRPC across a trust boundary** — east-west traffic needs mTLS.
+10. **Stack traces / SQL in `status.message`** — info leak, same as api-design's HTTP rule.
+
+## Pairs With
+
+- **api-design** — owns the external REST/GraphQL contract and the gRPC-Gateway REST edge; this skill owns the internal binary contract.
+- **realtime-websockets** — for browser-facing live streams (gRPC streaming is internal-only).
+- **observability** — per-RPC spans and RED metrics via interceptors.
+- **clean-code** — interceptor ordering, fail-closed handlers, no info leak in status messages.
+
+## Source Material
+
+- Protocol Buffers Language Guide (proto3) + the official schema-evolution rules.
+- gRPC Core Concepts (grpc.io) — RPC kinds, deadlines, status codes, channels.
+- `buf` documentation — lint + breaking-change detection in CI.
+- gRPC-Gateway docs — `google.api.http` transcoding to REST.
+- *gRPC: Up and Running* (Indrasiri & Kuruppu) — interceptors, security, deployment.