Imported from eshu-hq/eshu (go/cmd/api/AGENTS.md). Install upstream with npx skills add eshu-hq/eshu --skill api. Copyright stays with the author.

AGENTS.md — cmd/api guidance for LLM assistants

Read first

1. go/cmd/api/wiring.go — the wiring sequence: how Postgres and the graph driver are opened, how the query graph is opened, and how the admin surface is mounted via mountRuntimeSurface in wireAPI. The router assembly (newRouter, newRouterWithSemanticEmbedding) and the version/ deprecation middleware live in the sibling go/cmd/api/wiring_router.go.
2. go/cmd/api/main.go — main, telemetry bootstrap, signal handling, and http.Server configuration.
3. go/internal/query/handler.go — APIRouter and APIRouter.Mount; understand this before adding handler families or changing route registration.
4. go/internal/runtime/ — NewStatusAdminMux, OpenNeo4jDriver, ResolveAPIKey; the shared admin seams this binary delegates to.
5. go/cmd/api/README.md — lifecycle summary, env vars, and operational notes.

Invariants this package enforces

• Read-mostly runtime with one bounded policy mutation — normal data routes use read adapters (query.Neo4jReader, query.ContentReader) and the binary never calls graph write methods. The authenticated, all-scopes-only vulnerability-suppression route is the deliberate exception: it writes one immutable operator fact generation and projector intent transactionally through VulnerabilitySuppressionMutationStore. Do not add another fact or queue write here without an owner-approved runtime-boundary review.
• Required Postgres DSN — wireAPI returns an error after ResolveAPIKey succeeds if both ESHU_POSTGRES_DSN and ESHU_CONTENT_STORE_DSN are empty; the binary exits at startup (wiring.go:42).
• Profile and backend validated at startup — loadQueryProfile and loadGraphBackend call ParseQueryProfile and ParseGraphBackend respectively; unrecognized values return errors that cause os.Exit(1) (wiring.go:147).
• Auth wraps the full mux — AuthMiddleware is applied after mountRuntimeSurface, so data routes cannot be reached without auth when a token is configured (wiring.go:105).
• Authenticating is not being admitted — wrapAPIAuth derives a query.BrowserSessionRoutePolicy from ESHU_GOVERNANCE_MODE via query.ScopedRoutePolicyForGovernanceMode and hands it to the middleware that serves both bearer tokens and dashboard browser sessions. Under hosted_multi_tenant, or a mode the binary does not recognize, an all-scope credential is refused with 403 on grant-bound, deployment-scoped, and transitive routes. Thread that policy through any new auth constructor here; query.BrowserSessionRoutePolicy's zero value is fail-closed, so a constructor that drops it refuses all-scope callers on a laptop too. The env var is documented for operators in go/cmd/api/README.md.
• Graceful shutdown timeout — the shutdown goroutine calls Shutdown on the server with a configurable timeout read from ESHU_API_SHUTDOWN_TIMEOUT (default 30 s). Requests not completed within that window are interrupted. Operators setting an explicit 5 s value retain the prior hard-coded behavior. The deadline is read at startup; runtime changes require a restart (main.go:95).
• Recovery response budget — the HTTP write timeout is derived from rebuildreset.DefaultRefinalizeDrainTimeout plus a one-minute margin. A hard-killed reducer can retain its lease for the drain window; shortening the server timeout below that bound drops the eventual recovery response.
• Compile-time port conformance — wiring.go:23 asserts that Neo4jReader satisfies GraphQuery and ContentReader satisfies ContentStore; removing these assertions will silently break port conformance.

Common changes and how to scope them

• Add a new handler family → add the handler struct to internal/query, add a Mount call in APIRouter.Mount, wire the struct in newRouter (wiring_router.go), add a path fragment under internal/query/openapi/paths/<family>/ and reference it in the OpenAPI assembly function, update docs/public/reference/http-api.md, run go test ./cmd/api ./internal/query -count=1. Why: all handler families follow the same struct-and-Mount pattern; missing a step leaves routes unreachable or undocumented.

• Change the listen address or timeouts → edit main.go for ESHU_API_ADDR and newAPIServer. The read-header and idle timeouts are hard-coded; the write timeout follows the recovery drain bound; only the graceful shutdown timeout is configurable via ESHU_API_SHUTDOWN_TIMEOUT. Why: server timeouts are deployment-level contracts that should be changed deliberately, not silently picked up from environment.

• Swap the graph backend → set ESHU_GRAPH_BACKEND=nornicdb or ESHU_GRAPH_BACKEND=neo4j; the binary delegates to ParseGraphBackend and openQueryGraph. Do not add backend-conditional branches in this package; those belong in internal/storage/cypher adapters.

• Add a new environment variable → read it in wireAPI via the getenv function parameter (not os.Getenv directly), update doc.go and README.md, and add it to docs/public/reference/cli-reference.md. Why: wireAPI takes getenv func(string) string so tests can inject values without t.Setenv.

Failure modes and how to debug

• Symptom: binary exits immediately after eshu-api starts → likely cause: missing ESHU_POSTGRES_DSN, bad ESHU_QUERY_PROFILE, or graph driver unreachable → check the structured log runtime.startup.failed event; it carries the specific error.

• Symptom: /healthz returns 503 → likely cause: NewStatusAdminMux or the status reader returned an error → check /admin/status for the reported stage and failure fields.

• Symptom: high latency on data routes → likely cause: slow graph or Postgres queries → check eshu_dp_neo4j_query_duration_seconds and eshu_dp_postgres_query_duration_seconds at /metrics; trace individual requests via the otelhttp span named eshu-api.

• Symptom: 401 on all data routes → likely cause: bearer token mismatch → the AuthMiddleware in internal/query skips auth only when the resolved token is empty (dev mode); verify the token resolves via ResolveAPIKey in internal/runtime.

• Symptom: requests interrupted mid-stream during redeploy → likely cause: the graceful Shutdown window (default 30 s, configurable via ESHU_API_SHUTDOWN_TIMEOUT) was exceeded → consider a query-side timeout on long graph traversals before extending the server shutdown window (main.go:95).

Anti-patterns specific to this package

• Calling os.Getenv directly inside wireAPI — wireAPI takes getenv func(string) string for test injection. Direct os.Getenv calls inside wireAPI make the wiring untestable without t.Setenv.

• Adding backend-conditional branches to wiring.go — backend brand differences belong in internal/storage/cypher adapters behind the GraphQuery port. Adding if graphBackend == "nornicdb" in this package leaks dialect logic into the transport layer.

• Adding data routes directly to apiMux in wireAPI — new routes belong in handler structs under internal/query with a Mount method. Bypassing the APIRouter means the route misses OpenAPI registration, capability-matrix gating, and the standard response-envelope contract.

• Mounting the admin surface after AuthMiddleware — admin endpoints (/healthz, /readyz, /admin/status, /metrics) must remain public. mountRuntimeSurface is called before AuthMiddleware is applied; reversing that order blocks health probes.

What NOT to change without an ADR

• ESHU_QUERY_PROFILE accepted values — part of the public truth-label contract; see docs/public/reference/http-api.md and go/internal/query/envelope_aliases.go.
• ESHU_GRAPH_BACKEND accepted values — governed by the backend promotion gate; see docs/public/reference/backend-conformance.md.
• The AuthMiddleware placement relative to mountRuntimeSurface — moving this changes which routes require auth; that is a security-boundary change.
• Any API fact or queue write beyond the bounded, all-scopes vulnerability suppression mutation — data-plane write ownership belongs to intake and resolution runtimes unless an owner-approved boundary change says otherwise.

Evidence (W-1: ESHU_API_SHUTDOWN_TIMEOUT)

• No-Regression Evidence: The change replaces a hardcoded 5*time.Second with an env-read-and-parse that lands on the same 5 s when ESHU_API_SHUTDOWN_TIMEOUT=5s is set explicitly, and defaults to 30 s otherwise. No runtime, storage, Cypher, concurrency, queue, or performance path is affected. The shutdown goroutine remains a single closure with identical scheduling behavior.
• No-Observability-Change: The existing eshu-api OTEL span, eshu_dp_* metrics, and structured log keys already diagnose the API binary lifecycle. The shutdown timeout value change does not alter the signal contract. W-2 adds a dedicated eshu_dp_shutdown_duration_seconds histogram for the shutdown path.