Refactor Hercules into a production-ready 0.9 runtime - #94

Summary

• rebuild runtime ownership around one serialized DuckDB engine, deterministic startup phases, supervised Source refreshes, and bounded shutdown
• publish immutable last-known-good Metric Snapshots outside the Prometheus scrape path, with strict result conversion and cardinality budgets
• add strict versioned configuration and Package compilation, dependency ordering, collision detection, variable expansion, and package-relative Source resolution
• harden remote Packages with opt-in host, redirect, digest, cache, size, and offline policies; gate DuckDB extensions explicitly
• add readiness, liveness, collection telemetry, TLS, bearer authentication, preflight CLI commands, release automation, non-root multi-architecture containers, ADRs, schemas, and operator documentation
• remove obsolete global-registry, scrape-time query, unsupervised worker, and duplicated helper modules

Operator-visible changes

Configuration now requires version: 1 and fails closed on unknown or invalid values. The listener defaults to loopback, DuckDB defaults to in-memory storage, resource budgets are explicit, remote Packages and extensions are denied by default, and Metric Definitions use stricter Prometheus naming and result rules.

New check-config, check, print-effective-config, and package-digest commands support rollout and diagnostics. Metrics scrapes serve the latest complete snapshot and no longer execute SQL.

Failure behavior

Startup compiles configuration and Packages before opening DuckDB, then initializes extensions, macros, Sources, and the initial Metric Snapshot in order. Any startup-phase failure prevents readiness. Later collection failures retain the previous complete snapshot; Source refresh failures retain existing state and back off.

Shutdown disables readiness, cancels worker contexts, drains or force-closes HTTP within the caller deadline, joins workers before closing DuckDB, and supports repeated callers observing the same cleanup.

Compatibility

This is an intentional breaking alpha update from 0.8 to 0.9. Existing deployments must update configuration, Package metadata, extension allowlists, metric names and result layouts, and scrape-freshness alerting. See docs/migrating-to-0.9.md for the migration path.

Validation

• go test -race -count=1 ./...
• golangci-lint fmt --diff
• golangci-lint run ./...
• go vet ./...
• go mod verify
• production binary build
• govulncheck v1.5.0: no reachable vulnerabilities
• statement coverage: 66.4%
• focused lifecycle tests repeated five times under the race detector