config

type Config struct {
	// Addr is the listen address. CARTOGRAPH_ADDR, default ":8080". A bare
	// port ("8080", what PORT-style platforms hand out) is accepted, and
	// "unix:///path/to.sock" listens on a UNIX domain socket instead.
	Addr string

	// Vault is the directory of manifests to serve, or a SQLite file.
	// CARTOGRAPH_VAULT, default ".". A positional argument on the command line
	// wins over both.
	Vault string

	// Store, when set, is a postgres:// (or postgresql://) URL, and the
	// manifests, project state, bundles and shared drafts live in that
	// database instead of a vault: what a stateless deployment of many
	// replicas needs. CARTOGRAPH_STORE, default empty: serve Vault.
	Store string

	// Fanout carries "this document changed" and presence between
	// replicas: "memory" (one replica) or "postgres" (LISTEN/NOTIFY on
	// the Store database). CARTOGRAPH_FANOUT, default empty, which means
	// postgres when Store is set and memory otherwise; FanoutAdapter
	// resolves it.
	Fanout string

	// FanoutURL, when set, is the Postgres URL the fan-out's listening
	// connection uses instead of Store. LISTEN needs a session of its own,
	// so when Store goes through a pooler in transaction mode (PgBouncer's
	// usual setting), this must reach Postgres directly.
	// CARTOGRAPH_FANOUT_URL, default empty: the Store URL.
	FanoutURL string

	// MetricsAddr, when set, serves Prometheus metrics at /metrics on a
	// listener of its own, kept off the address users reach.
	// CARTOGRAPH_METRICS_ADDR, default empty: no metrics listener.
	MetricsAddr string

	// SyncPing is how often the sync socket pings an idle peer, so a load
	// balancer or proxy does not close a quiet connection (nginx and AWS
	// ALB close one after 60 s by default). CARTOGRAPH_SYNC_PING, default
	// 20s; 0 turns pings off.
	SyncPing time.Duration

	// SyncIdle closes a sync connection that has changed no document for
	// this long, so an unattended window holds no replica up and the
	// deployment can scale to zero (docs/adr/0015). Pings and presence
	// do not count. CARTOGRAPH_SYNC_IDLE, default 10m; 0 never closes.
	SyncIdle time.Duration

	// DocCache bounds how many shared documents a replica keeps in
	// memory; the least recently used are dropped first, and a dropped
	// one is loaded again from the store when next needed.
	// CARTOGRAPH_DOC_CACHE, default 1000.
	DocCache int

	// CompactAfter is how old a version must be, beside not being its
	// manifest's latest, before a Postgres store keeps it as a patch
	// instead of whole (docs/adr/0013). It is the time a rolling upgrade
	// from 2.2 has to finish: a 2.2 replica cannot read a compacted
	// version. CARTOGRAPH_COMPACT_AFTER, default 24h; 0 turns it off.
	CompactAfter time.Duration

	// Reports is the reporting adapter (docs/adr/0014): "computed" from
	// the engine's reads on any store, "postgres" as views beside a
	// Postgres store, or "off" for a deployment that reports elsewhere.
	// CARTOGRAPH_REPORTS, default computed.
	Reports string

	// GraphLayout places the workspace graph: "layered" (the default), a
	// band per stage of the order of work from the top down, or "force",
	// a force-directed layout. CARTOGRAPH_GRAPH_LAYOUT.
	GraphLayout string

	// Semantic is the syntax the KPIs export in as a semantic layer
	// (TAXONOMY.md D57): "dbt" (the default) or "off".
	// CARTOGRAPH_SEMANTIC.
	Semantic string

	// Decide is the decision model the engine asks about what people
	// write (docs/adr/0023): "off" (the default) or "laya", a Laya
	// sidecar at DecideURL, each call given at most DecideTimeout.
	// CARTOGRAPH_DECIDE, CARTOGRAPH_DECIDE_URL, CARTOGRAPH_DECIDE_TIMEOUT.
	Decide        string
	DecideURL     string
	DecideTimeout time.Duration

	// MCP serves agents at /api/v1/mcp (docs/adr/0016): "off" (the
	// default) or "on". With an access list, only the roles its
	// mapping's agents key names may use one. CARTOGRAPH_MCP.
	MCP string

	// MCPTrace keeps every MCP tool call by its shape, for governance
	// and analysis (docs/adr/0028): "off" (the default) or a file path,
	// to which calls are appended as JSON lines. CARTOGRAPH_MCP_TRACE.
	MCPTrace string
	// MCPAuth is who authenticates an agent's requests: "proxy" (the
	// default), whatever authenticates every other request, checking the
	// tokens of the authorization server MCPIssuer names; or
	// "cartograph", Cartograph's own authorization server, at MCPIssuer,
	// which is then Cartograph's public address. CARTOGRAPH_MCP_AUTH.
	MCPAuth string
	// MCPIssuer is the authorization server MCP clients sign in with,
	// advertised as RFC 9728 protected resource metadata; empty
	// advertises none. CARTOGRAPH_MCP_ISSUER.
	MCPIssuer string
	// AgentKey signs what Cartograph's own authorization server issues:
	// at least 32 bytes, the same on every replica. CARTOGRAPH_AGENT_KEY.
	AgentKey string

	// DrainDelay is how long, after SIGTERM, the server keeps serving
	// while /readyz answers 503, so load balancers stop sending it work
	// before it stops accepting any. CARTOGRAPH_DRAIN_DELAY, default 0.
	DrainDelay time.Duration

	// Watch reloads manifests when their files change on disk.
	// CARTOGRAPH_WATCH, default true.
	Watch bool

	// Chromium is the browser to print PDFs with. CARTOGRAPH_CHROMIUM, default
	// empty: the printer then tries the vault's settings, CHROMIUM, then
	// the PATH.
	Chromium string

	// LogFormat is "text" or "json". CARTOGRAPH_LOG_FORMAT, default "text".
	// Logs always go to stdout; the environment decides where they end up.
	LogFormat string

	// LogLevel is debug, info, warn or error. CARTOGRAPH_LOG_LEVEL, default
	// "info".
	LogLevel string

	// ShutdownTimeout is how long in-flight requests get after SIGTERM.
	// CARTOGRAPH_SHUTDOWN_TIMEOUT, default 10s.
	ShutdownTimeout time.Duration

	// Auth selects the authenticator: "none" (every request is the
	// vault's operator) or "proxy" (the identity is the value of
	// AuthProxyHeader, set by an authenticating reverse proxy that is the
	// only way to reach the server). CARTOGRAPH_AUTH, default "none".
	Auth string

	// AuthProxyHeader is the header the proxy authenticator reads.
	// CARTOGRAPH_AUTH_PROXY_HEADER, default "X-Forwarded-User".
	AuthProxyHeader string

	// Authz selects the authorizer: "allow" (every principal may do
	// everything), "roles" (ReadRoles and WriteRoles decide; an anonymous
	// principal is refused, so pair it with an authenticator), or
	// "access" (an access list of people, four roles and teams, with
	// AccessFile mapping directory groups onto them; docs/adr/0011).
	// CARTOGRAPH_AUTHZ, default "allow".
	Authz string

	// AccessFile is the mapping from directory groups to roles and teams
	// for the access authorizer. CARTOGRAPH_ACCESS_FILE, default empty:
	// no group grants anything, and only people an administrator lists
	// may sign in.
	AccessFile string

	// ReadRoles and WriteRoles are comma-separated role names for the
	// roles authorizer. CARTOGRAPH_READ_ROLES (empty: any authenticated
	// principal may read), CARTOGRAPH_WRITE_ROLES (empty: nobody may write).
	ReadRoles  string
	WriteRoles string

	// Codec is the manifest syntax, "yaml" or "json". CARTOGRAPH_CODEC,
	// default "yaml". A vault is written in one codec; changing it is a
	// migration, not a restart.
	Codec string

	// ImportDir, when set, is imported on startup before serving.
	// CARTOGRAPH_IMPORT, default empty.
	ImportDir string
}

type Getenv func(key string) string