HeliosDB-Proxy

Configure a running plugin's behaviour without restarting via `PUT/GET/DELETE /admin/kv/<plugin>/<key>`. Per-plugin namespaced state. Use when the user says "set the budget", "configure the residency map", "/admin/kv", "plugin runtime config", or wants to push a new mask rule live.

Bring up any of the 22 v0.4.0 demos under `demos/v0.4.0/<n>/`. Each ships a `demo.sh up\|run\|down` and a self-contained `docker-compose.yml`. Use when the user says "run a demo", "demo.sh", "show me X working", "anomaly detection demo", or asks for a runnable example.

Deploy HeliosProxy via Kubernetes operator (CRD), Terraform provider, or Pulumi. Quick-start per surface and which to pick when. Use when the user says "operator", "Kubernetes", "CRD", "HeliosProxy resource", "Terraform", "TF provider", "Pulumi", "IaC".

Install HeliosProxy from crates.io or build from source. Pick feature flags. Verify with `--version`. Use when the user says "install heliosproxy", "set up the proxy", "cargo install heliosdb-proxy", or hits a "command not found" on `heliosdb-proxy`.

Start the HeliosProxy daemon — `heliosdb-proxy --config proxy.toml` or all-CLI-args mode. Use when the user says "start the proxy", "run heliosproxy", "set up the daemon", "systemd unit", or hits "connection refused" against the admin port.

Top-level navigation for HeliosProxy. Auto-loads when the user mentions "heliosproxy", "helios proxy", or pastes its admin REST output / config / log lines. Routes to one of 21 domain skills (install, start, config, shutdown, connect, topology, health, chaos, switchover, time-travel, shadow-execute, anomaly, plugin-{pack,load,kv,catalog}, edge, demo-{up,down}, release, iac). Use this skill to find the right skill before going deep.

Cut a HeliosProxy release. Bump version → CHANGELOG → commit → tag → push. The `crates-io.yml` workflow runs `cargo publish` on tag push. Use when the user says "release", "cut a version", "publish to crates.io", "tag a release", "bump version".

Catalog of the eight first-party plugins (cost-governor, ai-classifier, token-budget, llm-guardrail, pgvector-router, column-mask, audit-chain, residency-router). What each fires on, what it gates, what KV keys it reads. Use when the user says "which plugin does X", "I need to mask PII", "I need to gate AI traffic", "guardrails", "how does residency-router decide".

Use the `helios-plugin` CLI to pack, sign, inspect, and verify WASM plugin artefacts. OCI-style `.tar.gz` (manifest + .wasm + .sig). Generate Ed25519 keys with openssl. Use when the user says "pack a plugin", "sign WASM", "trust root", "helios-plugin", "OCI artefact".

Read the in-process anomaly detector — SQL injection patterns, auth-burst credential stuffing, rate-spike z-score, novel-query shapes. Use when the user says "/anomalies", "anomaly", "SQL injection", "auth burst", "credential stuffing", "rate spike", or wires up an alerting hook.

Inject controlled faults via `POST /api/chaos`. Force a node unhealthy, restore it, or reset all overrides at once. Use when the user says "chaos drill", "force the primary down", "fault injection", "test failover", "restore the node", or wants to validate the failover path.

Author or edit `proxy.toml`. Walk through every block (server, nodes, pool, ha, plugins, anomaly, edge, multi-tenancy, etc.). Use when the user asks "how do I configure X", "where do I put Y in proxy.toml", or after pasting a TOML snippet that doesn't load.

Connect a PostgreSQL client to HeliosProxy. psql / asyncpg / jdbc / Rust tokio-postgres / Go pgx. Sanity-check `SELECT 1`. Force routing with `/*+ route=primary */` hints. Use when the user says "connect to the proxy", "psql -h proxy", "first SQL round-trip", "force read to primary".

Tear down any v0.4.0 demo cleanly. Volume cleanup, port liberation, log collection before stop. Use when the user says "tear down", "demo.sh down", "stuck on port", "clean up after demo", "where are the logs".

Geo / edge proxy mode. Register edges with the home proxy, push table-level invalidation broadcasts, watch cache hits across regions. Use when the user says "edge proxy", "geo cache", "/api/edge", "register edge", "invalidate", "last-write-wins TTL".

Liveness + readiness + metrics + sessions + pools + version. Every read-only observability endpoint. Use when the user says "is the proxy up", "Prometheus", "metrics", "what to alert on", "active sessions", "pool stats", or wires up a health-check probe.

Get a packed/signed `.wasm` or `.tar.gz` plugin into the running proxy. Drop into `plugin_dir`, hot-reload, verify via `GET /plugins`. Configure `trust_root`. Use when the user says "load a plugin", "drop the wasm", "/plugins is empty", "trust root", "hot reload".

Run a query against two backends in parallel and diff the results. Validates that a new-version replica matches the source. Use when the user says "shadow", "/api/shadow", "diff results", "validate migration", "PG-version upgrade test".

Stop the proxy gracefully. SIGTERM triggers a drain — wait for active sessions to close, then exit. Use when the user says "stop the proxy", "shutdown", "drain", "restart for config change", or asks why a `kill` left clients hanging.

Failover and switchover semantics — automatic primary detection, switchover buffer, manual triggering via chaos. What happens between "primary down" and "promoted standby is now serving". Use when the user says "failover", "switchover", "promote", "what happens during failover", "currentPrimary stuck null", "lastFailoverAt".

Replay a window of the transaction journal onto a target backend via `POST /api/replay`. Validate failover, hydrate staging from prod, debug "what happened yesterday at 14:32". Use when the user says "replay", "time-travel", "/api/replay", "hydrate staging", "rerun the last hour against staging".

Inspect cluster topology — current primary, healthy/unhealthy nodes, per-node detail, raw config. Enable / disable a node. Use when the user says "what's the primary", "topology", "/topology", "which nodes are up", "disable that replica", or "currentPrimary is null".