cartethyia 2.5.4 → 2.5.7

package/src/boot/timeout.ts

@@ -24,19 +24,8 @@ export function withTimeout<T>(
 }
 
 /**
- * Creates a standalone timeout promise that rejects after the specified duration.
- * The timer is unref'd to prevent keeping the event loop alive.
- */
-export function timeoutAfter(ms: number, message: string): Promise<never> {
-  return new Promise<never>((_, reject) => {
-    const timer = setTimeout(() => reject(new Error(message)), ms);
-    if (typeof timer.unref === "function") timer.unref();
-  });
-}
-
-/**
- * Cancellable variant of {@link timeoutAfter}: the loser timer is cleared
- * when the raced operation wins, instead of firing later against nothing.
+ * The loser timer is cleared when the raced operation wins, instead of firing
+ * later against nothing.
  */
 export function cancellableTimeout(ms: number, message: string): { promise: Promise<never>; cancel: () => void } {
   let timer: ReturnType<typeof setTimeout> | undefined;

package/src/config/cooldowns.ts

@@ -1,138 +1,186 @@
-/**
- * Account/pool health cooldown fallback resolvers.
- */
-
-import { CONFIG_SPEC, readInt } from "./spec";
-
-/** Fallback cooldown for a provider rate limit (default 15m). */
-export function resolveAccountRateLimitCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
-  );
-}
-
-/**
- * Fallback cooldown for provider quota exhaustion when the error states no
- * reset window (default 1h). A provider-specific rule (xAI Grok Build's
- * rolling 24-hour free-tier window) overrides it inside the classifier.
- */
-export function resolveAccountQuotaCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
-  );
-}
-
-/** Fallback cooldown for model-capacity overload (default 2m). */
-export function resolveAccountModelCapacityCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
-  );
-}
-
-/** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
-export function resolveAccountTransientCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
-  );
-}
-
-/** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
-export function resolveAccountUnclassifiedCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
-  );
-}
-
-/**
- * Ceiling an escalated fallback cooldown may reach (default 1h).
- *
- * A fallback duration is one the provider never stated, so escalating it is our
- * own estimate. The cap keeps that estimate from outliving a short transient
- * window: an account that recovers on its own must not sit parked for a day
- * because a burst of 5xx happened to arrive while it was already cooling.
- */
-export function resolveAccountCooldownEscalationMaxMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
-  );
-}
-
-/** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
-export function resolvePoolCooldownMs(): number {
-  return readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
-}
-
-/**
- * Backoff for an auth rejection that names no revocation (default 5m).
- *
- * A bare `401`/`403` is weak evidence: it covers clock skew, a key rotated
- * upstream a moment ago, an edge cache, and a load balancer that answers before
- * the credential is loaded. None of those is the credential's death, and this
- * outcome used to be `disabled` — the one state no sweep recovers, so the
- * account left rotation until an operator noticed. A cooldown costs the same
- * requests for five minutes and comes back on its own.
- *
- * Only a *named* revocation (`token revoked`, `invalidated oauth token`) still
- * parks the account: the upstream stated the credential itself is dead, there is
- * no expiry to wait out and no refresh to run, so a cooldown would only return
- * it to rotation to fail again. Set this to `0` to restore the old behavior.
- */
-export function resolveAccountAuthRejectedCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
-  );
-}
-
-/**
- * Base backoff for the buddy policy/channel block (default 5m).
- *
- * Deliberately a *base*, not the 24h flat penalty it replaced. `11140` has two
- * documented causes our classifier cannot separate from the response alone: the
- * user's prompt failed a safety review, **and** sending the wrong desktop
- * `User-Agent` brand (`workbuddy/shared.ts`). A flat 24h meant that after we
- * fixed a header regression every buddy account stayed dead for up to a further
- * day, and one unsafe prompt cost a whole account a day.
- *
- * As a base it escalates through the consecutive-failure ladder instead, which
- * distinguishes the two causes by what they do next: a genuinely blocked account
- * is refused again on its very next request and parks itself within minutes,
- * while a single bad prompt costs five minutes.
- */
-export function resolveAccountPolicyBlockCooldownMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
-  );
-}
-
-/**
- * How long an **automatically** disabled account stays out of rotation (default 24h).
- *
- * `disabled` used to be terminal: nothing recovered it, so a credential rejected
- * once — a revoked key, a definitively dead refresh grant — left rotation until an
- * operator noticed and clicked Recover by hand. That is the wrong default for a
- * credential that may come back on its own: keys get re-issued, grants get
- * re-authorized, and an upstream's notion of "invalid" can outrun ours.
- *
- * The deadline is what makes this safe to automate rather than a policy guess. A row
- * this gateway disables **by itself** carries the deadline; a row an **operator**
- * disables keeps `cooldownUntil` null, and the recovery sweep selects only rows whose
- * deadline has elapsed. So an operator's decision still outranks the machine, with no
- * extra column and no way to confuse the two.
- *
- * Long on purpose: the states that reach here are the ones where retrying sooner
- * only reproduces the refusal. Set to `0` to restore the old terminal behavior.
- */
-export function resolveAccountDisabledRecoveryMs(): number {
-  return readInt(
-    "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
-    CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
-  );
-}
+/**
+ * Account/pool health cooldown fallback resolvers.
+ */
+
+import { CONFIG_SPEC, readInt } from "./spec";
+
+let _rateLimitCooldown: number | undefined;
+/** Fallback cooldown for a provider rate limit (default 15m). */
+export function resolveAccountRateLimitCooldownMs(): number {
+  if (_rateLimitCooldown === undefined)
+    _rateLimitCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_RATE_LIMIT_COOLDOWN_MS,
+  );
+  return _rateLimitCooldown;
+}
+
+let _quotaCooldown: number | undefined;
+/**
+ * Fallback cooldown for provider quota exhaustion when the error states no
+ * reset window (default 1h). A provider-specific rule (xAI Grok Build's
+ * rolling 24-hour free-tier window) overrides it inside the classifier.
+ */
+export function resolveAccountQuotaCooldownMs(): number {
+  if (_quotaCooldown === undefined)
+    _quotaCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_QUOTA_COOLDOWN_MS,
+  );
+  return _quotaCooldown;
+}
+
+let _modelCapacityCooldown: number | undefined;
+/** Fallback cooldown for model-capacity overload (default 2m). */
+export function resolveAccountModelCapacityCooldownMs(): number {
+  if (_modelCapacityCooldown === undefined)
+    _modelCapacityCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_MODEL_CAPACITY_COOLDOWN_MS,
+  );
+  return _modelCapacityCooldown;
+}
+
+let _transientCooldown: number | undefined;
+/** Backoff for a transient 5xx/network fault, recorded as `cooldown` (default 30s). */
+export function resolveAccountTransientCooldownMs(): number {
+  if (_transientCooldown === undefined)
+    _transientCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_TRANSIENT_COOLDOWN_MS,
+  );
+  return _transientCooldown;
+}
+
+let _unclassifiedCooldown: number | undefined;
+/** Backoff for a failure no rule matched, recorded as `cooldown` (default 1m). */
+export function resolveAccountUnclassifiedCooldownMs(): number {
+  if (_unclassifiedCooldown === undefined)
+    _unclassifiedCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_UNCLASSIFIED_COOLDOWN_MS,
+  );
+  return _unclassifiedCooldown;
+}
+
+/**
+ * Ceiling an escalated fallback cooldown may reach (default 1h).
+ *
+ * A fallback duration is one the provider never stated, so escalating it is our
+ * own estimate. The cap keeps that estimate from outliving a short transient
+ * window: an account that recovers on its own must not sit parked for a day
+ * because a burst of 5xx happened to arrive while it was already cooling.
+ */
+let _escalationMaxCooldown: number | undefined;
+export function resolveAccountCooldownEscalationMaxMs(): number {
+  if (_escalationMaxCooldown === undefined)
+    _escalationMaxCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_COOLDOWN_ESCALATION_MAX_MS,
+  );
+  return _escalationMaxCooldown;
+}
+
+let _poolCooldown: number | undefined;
+/** How long a proxy pool stays `cooldown` after a transport fault (default 2m). */
+export function resolvePoolCooldownMs(): number {
+  if (_poolCooldown === undefined)
+    _poolCooldown = readInt("CARTETHYIA_POOL_COOLDOWN_MS", CONFIG_SPEC.CARTETHYIA_POOL_COOLDOWN_MS);
+  return _poolCooldown;
+}
+
+let _authRejectedCooldown: number | undefined;
+/**
+ * Backoff for an auth rejection that names no revocation (default 5m).
+ *
+ * A bare `401`/`403` is weak evidence: it covers clock skew, a key rotated
+ * upstream a moment ago, an edge cache, and a load balancer that answers before
+ * the credential is loaded. None of those is the credential's death, and
+ * `disabled` is the one state no sweep recovers — the account would leave
+ * rotation until an operator noticed. A cooldown costs the same
+ * requests for five minutes and comes back on its own.
+ *
+ * Only a *named* revocation (`token revoked`, `invalidated oauth token`) still
+ * parks the account: the upstream stated the credential itself is dead, there is
+ * no expiry to wait out and no refresh to run, so a cooldown would only return
+ * it to rotation to fail again. Set this to `0` to return the account to
+ * rotation immediately, with no backoff to wait out.
+ */
+export function resolveAccountAuthRejectedCooldownMs(): number {
+  if (_authRejectedCooldown === undefined)
+    _authRejectedCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_AUTH_REJECTED_COOLDOWN_MS,
+  );
+  return _authRejectedCooldown;
+}
+
+let _policyBlockCooldown: number | undefined;
+/**
+ * Base backoff for the buddy policy/channel block (default 5m).
+ *
+ * Deliberately a *base*, not the 24h flat penalty it replaced. `11140` has two
+ * documented causes our classifier cannot separate from the response alone: the
+ * user's prompt failed a safety review, **and** sending the wrong desktop
+ * `User-Agent` brand (`workbuddy/shared.ts`). A flat 24h meant that after we
+ * fixed a header regression every buddy account stayed dead for up to a further
+ * day, and one unsafe prompt cost a whole account a day.
+ *
+ * As a base it escalates through the consecutive-failure ladder instead, which
+ * distinguishes the two causes by what they do next: a genuinely blocked account
+ * is refused again on its very next request and parks itself within minutes,
+ * while a single bad prompt costs five minutes.
+ */
+export function resolveAccountPolicyBlockCooldownMs(): number {
+  if (_policyBlockCooldown === undefined)
+    _policyBlockCooldown = readInt(
+    "CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_POLICY_BLOCK_COOLDOWN_MS,
+  );
+  return _policyBlockCooldown;
+}
+
+let _disabledRecovery: number | undefined;
+/**
+ * How long an **automatically** disabled account stays out of rotation (default 24h).
+ *
+ * A credential rejected once — a revoked key, a definitively dead refresh grant —
+ * would otherwise leave rotation until an operator noticed and clicked Recover by
+ * hand. That is the wrong default for a credential that may come back on its own:
+ * keys get re-issued, grants get re-authorized, and an upstream's notion of
+ * "invalid" can outrun ours.
+ *
+ * The deadline is what makes this safe to automate rather than a policy guess. A row
+ * this gateway disables **by itself** carries the deadline; a row an **operator**
+ * disables keeps `cooldownUntil` null, and the recovery sweep selects only rows whose
+ * deadline has elapsed. So an operator's decision still outranks the machine, with no
+ * extra column and no way to confuse the two.
+ *
+ * Long on purpose: the states that reach here are the ones where retrying sooner
+ * only reproduces the refusal. Set to `0` to make an automatic disable terminal.
+ */
+export function resolveAccountDisabledRecoveryMs(): number {
+  if (_disabledRecovery === undefined)
+    _disabledRecovery = readInt(
+    "CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS",
+    CONFIG_SPEC.CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS,
+  );
+  return _disabledRecovery;
+}
+
+/**
+ * Resets all cached cooldown values. Call this in tests that override
+ * cooldown env-vars between test cases.
+ */
+export function resetCooldownCacheForTests(): void {
+  _rateLimitCooldown = undefined;
+  _quotaCooldown = undefined;
+  _modelCapacityCooldown = undefined;
+  _transientCooldown = undefined;
+  _unclassifiedCooldown = undefined;
+  _escalationMaxCooldown = undefined;
+  _poolCooldown = undefined;
+  _authRejectedCooldown = undefined;
+  _policyBlockCooldown = undefined;
+  _disabledRecovery = undefined;
+}

package/src/config/network.ts

@@ -83,20 +83,15 @@ export function resolveProxyMaxFreeSockets(): number {
 }
 
 // Proxy pool egress is dialed in-process by `network/pool/agent.ts` (http,
-// https, socks5). The former child-process pool flavor — generated config
-// files, a binary path, a local SOCKS port range, and a uid/gid drop — was
-// removed with that feature; do not reintroduce its resolvers without the
-// daemon that consumed them.
+// https, socks5). Add a resolver here only alongside the consumer it feeds.
 
 // ─── Process-wide resource bounds ───────────────────────────────────────────
 
 /**
  * Live process-wide resource bounds. Only bounds with a production consumer
  * live here: `maxPostgresPoolSize` feeds `poolMaxFromEnv()`, and
- * `maxTelemetryQueueBytes` caps `TelemetryBatchBuffer`. Everything else
- * that used to live in this module (`maxRedisPoolSize`, provider/network/
- * catalog/replay bounds, `BoundedConfig` + its validators) had zero callers
- * and was removed — re-add a bound only with its consumer in the same change.
+ * `maxTelemetryQueueBytes` caps `TelemetryBatchBuffer`. Re-add a bound only
+ * with its consumer in the same change.
  */
 export const DEFAULT_BOUNDS = {
   maxTelemetryQueueBytes: 10 * 1024 * 1024,
@@ -105,12 +100,11 @@ export const DEFAULT_BOUNDS = {
    *
    * This is a *ceiling*, not a reservation: the pool opens connections on
    * demand and returns them to idle, so a value the workload never reaches
-   * costs nothing today — it only bounds the worst case. The old value (60)
-   * was justified in a comment as "bursty 10k-inflight traffic", which is a
-   * property of the proxy path. The proxy path is *mostly* database-free —
-   * routing comes from `InMemoryRouteSnapshotService` and admission counters
-   * live in Redis — but not entirely: a dispatch attempt resolves its
-   * credential with a per-attempt read, health transitions write, and tenant
+   * costs nothing today — it only bounds the worst case. The proxy path is
+   * *mostly* database-free — routing comes from `InMemoryRouteSnapshotService`
+   * and admission counters live in Redis — but not entirely: a dispatch attempt
+   * resolves its credential with a per-attempt read, health transitions write,
+   * and tenant
    * preferences are read behind a short cache. Those are small, bounded reads
    * on the request's own attempt, not a per-request fan-out. The larger
    * database consumers remain the console API, one telemetry flush at a time,

package/src/config/providers.ts

@@ -1,10 +1,10 @@
 /**
- * Provider-specific knobs config.ts formerly owned: Kimi OAuth/quota hosts,
- * the GitHub Enterprise domain for the Copilot device login, and the OAuth
- * callback URL builders built on the public origin.
+ * Provider-specific knobs: Kimi OAuth/quota hosts, the GitHub Enterprise domain
+ * for the Copilot device login, and the OAuth callback URL builders built on the
+ * public origin.
  */
 
-import { CONFIG_SPEC, readInt, readList, readRequired, readText } from "./spec";
+import { CONFIG_SPEC, readInt, readRequired, readText } from "./spec";
 
 /** Reads and normalizes the public OAuth origin. */
 export function requirePublicOrigin(): string {
@@ -64,14 +64,11 @@ export function resolveOpenCodeUnavailableFree():
   const raw = process.env.CARTETHYIA_OPENCODE_UNAVAILABLE_FREE?.trim();
   if (raw === undefined || raw === "") return undefined;
   if (raw.toLowerCase() === "none") return "none";
-  const parsed = readList(
-    "CARTETHYIA_OPENCODE_UNAVAILABLE_FREE",
-    CONFIG_SPEC.CARTETHYIA_OPENCODE_UNAVAILABLE_FREE,
-  );
-  // Separators only: readList drops the empties and yields nothing. Treating
+  // Separators only: dropping empties and yielding nothing. Treating
   // that as "trust everything" would un-block every refused model on a typo,
   // so it falls back to the bundled list instead.
-  return parsed === undefined || parsed.length === 0 ? undefined : parsed;
+  const entries = raw.split(",").map((v) => v.trim()).filter(Boolean);
+  return entries.length === 0 ? undefined : entries;
 }
 
 /**

package/src/config/runtime.ts

@@ -1,76 +1,76 @@
-/**
- * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
- */
-
-import { CONFIG_SPEC, readInt, readOptionalText, readText } from "./spec";
-import { resolvePackagePath } from "./package-paths";
-
-/** Resolves the HTTP listener port from the process environment. */
-export function resolvePort(): number {
-  return readInt("PORT", CONFIG_SPEC.PORT);
-}
-
-/** Resolves the dashboard static asset directory. */
-export function resolveDashboardDist(): string {
-  if (!process.env.DASHBOARD_DIST?.trim()) return resolvePackagePath("dist", "dashboard");
-  return readText("DASHBOARD_DIST", CONFIG_SPEC.DASHBOARD_DIST);
-}
-
-/**
- * Resolves the configured default gateway API key (`CARTETHYIA_API_KEY`), if
- * one is set. Consumers that need the raw secret — first-boot seeding and the
- * console's legacy-key recovery — read it here instead of probing
- * `process.env` directly.
- */
-export function resolveDefaultGatewayApiKey(): string | undefined {
-  return readOptionalText("CARTETHYIA_API_KEY", CONFIG_SPEC.CARTETHYIA_API_KEY);
-}
-
-/** Resolves the request-body ceiling shared by the Bun listener and ingress middleware. */
-export function resolveMaxBodyBytes(): number {
-  return readInt("CARTETHYIA_SERVER_MAX_BODY_BYTES", CONFIG_SPEC.CARTETHYIA_SERVER_MAX_BODY_BYTES);
-}
-
-/** Resolves the listener idle-socket timeout (seconds). */
-export function resolveIdleTimeout(): number {
-  return readInt("CARTETHYIA_SERVER_IDLE_TIMEOUT", CONFIG_SPEC.CARTETHYIA_SERVER_IDLE_TIMEOUT);
-}
-
-/** Resolves the graceful-shutdown drain window: time for in-flight requests to finish before abort. */
-export function resolveShutdownDrainWindowMs(): number {
-  return readInt(
-    "CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS",
-    CONFIG_SPEC.CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS,
-  );
-}
-
-/** Resolves the operator drain token, or `undefined` when the drain route is disabled. */
-export function resolveDrainToken(): string | undefined {
-  const raw = process.env.CARTETHYIA_DRAIN_TOKEN?.trim();
-  return raw !== undefined && raw.length > 0 ? raw : undefined;
-}
-
-/**
- * Whether Elysia precompiles route handlers at startup (AOT).
- *
- * Precompilation takes the eager validator branch, which calls TypeBox's
- * `SchemaCompile(schema)` and then reads `.buildResult.external` off the
- * result. In a source-run process that field is absent — the lazy
- * `require("typebox/schema")` resolves to a namespace that does not carry it —
- * and the process dies at the first schema-bearing route with
- * `undefined is not an object (evaluating 'this.tb.buildResult.external')`.
- * `scripts/binary/aot.ts` avoids this by rewriting the call site and bundling
- * the namespaces statically, so only the built artifact can actually take the
- * eager path.
- *
- * So: precompilation is on for production *builds*, and off for a source run
- * even when `NODE_ENV=production`. A deployment that runs
- * `bun run src/main.ts` must not be pushed onto the eager branch.
- *
- * `CARTETHYIA_SOURCE_RUN` marks a source run explicitly. It is set by
- * `scripts/deploy/*.sh`, which are the only supported way to run from source.
- */
-export function resolveElysiaPrecompile(): boolean {
-  if (process.env.CARTETHYIA_SOURCE_RUN === "1") return false;
-  return process.env.NODE_ENV === "production";
-}
+/**
+ * HTTP listener, dashboard runtime, and graceful-shutdown drain resolvers.
+ */
+
+import { CONFIG_SPEC, readInt, readOptionalText } from "./spec";
+import { resolvePackagePath } from "./package-paths";
+
+/** Resolves the HTTP listener port from the process environment. */
+export function resolvePort(): number {
+  return readInt("PORT", CONFIG_SPEC.PORT);
+}
+
+/** Resolves the dashboard static asset directory. */
+export function resolveDashboardDist(): string {
+  const raw = process.env.DASHBOARD_DIST?.trim();
+  if (!raw) return resolvePackagePath("dist", "dashboard");
+  return raw;
+}
+
+/**
+ * Resolves the configured default gateway API key (`CARTETHYIA_API_KEY`), if
+ * one is set. Consumers that need the raw secret — first-boot seeding and the
+ * console's key recovery from existing installations — read it here instead of
+ * probing `process.env` directly.
+ */
+export function resolveDefaultGatewayApiKey(): string | undefined {
+  return readOptionalText("CARTETHYIA_API_KEY", CONFIG_SPEC.CARTETHYIA_API_KEY);
+}
+
+/** Resolves the request-body ceiling shared by the Bun listener and ingress middleware. */
+export function resolveMaxBodyBytes(): number {
+  return readInt("CARTETHYIA_SERVER_MAX_BODY_BYTES", CONFIG_SPEC.CARTETHYIA_SERVER_MAX_BODY_BYTES);
+}
+
+/** Resolves the listener idle-socket timeout (seconds). */
+export function resolveIdleTimeout(): number {
+  return readInt("CARTETHYIA_SERVER_IDLE_TIMEOUT", CONFIG_SPEC.CARTETHYIA_SERVER_IDLE_TIMEOUT);
+}
+
+/** Resolves the graceful-shutdown drain window: time for in-flight requests to finish before abort. */
+export function resolveShutdownDrainWindowMs(): number {
+  return readInt(
+    "CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS",
+    CONFIG_SPEC.CARTETHYIA_SHUTDOWN_DRAIN_WINDOW_MS,
+  );
+}
+
+/** Resolves the operator drain token, or `undefined` when the drain route is disabled. */
+export function resolveDrainToken(): string | undefined {
+  return readOptionalText("CARTETHYIA_DRAIN_TOKEN", CONFIG_SPEC.CARTETHYIA_DRAIN_TOKEN);
+}
+
+/**
+ * Whether Elysia precompiles route handlers at startup (AOT).
+ *
+ * Precompilation takes the eager validator branch, which calls TypeBox's
+ * `SchemaCompile(schema)` and then reads `.buildResult.external` off the
+ * result. In a source-run process that field is absent — the lazy
+ * `require("typebox/schema")` resolves to a namespace that does not carry it —
+ * and the process dies at the first schema-bearing route with
+ * `undefined is not an object (evaluating 'this.tb.buildResult.external')`.
+ * `scripts/build/aot.ts` avoids this by rewriting the call site and bundling
+ * the namespaces statically, so only the built artifact can actually take the
+ * eager path.
+ *
+ * So: precompilation is on for production *builds*, and off for a source run
+ * even when `NODE_ENV=production`. A deployment that runs
+ * `bun run src/main.ts` must not be pushed onto the eager branch.
+ *
+ * `CARTETHYIA_SOURCE_RUN` marks a source run explicitly. It is set by
+ * `scripts/deploy/*.sh`, which are the only supported way to run from source.
+ */
+export function resolveElysiaPrecompile(): boolean {
+  if (process.env.CARTETHYIA_SOURCE_RUN === "1") return false;
+  return process.env.NODE_ENV === "production";
+}

package/src/config/security.ts

@@ -37,6 +37,21 @@ export function resolveModelBanTtlMs(): number {
   return readInt("CARTETHYIA_MODEL_BAN_TTL_MS", CONFIG_SPEC.CARTETHYIA_MODEL_BAN_TTL_MS);
 }
 
+/**
+ * The longest model-abuse ban the console will record, however long a request
+ * asks for.
+ *
+ * A separate knob from the ban TTL because the two are different decisions:
+ * the TTL is what a graduated ban gets, this is the ceiling on what an
+ * operator may ask for by hand. Raising one was never meant to raise the other.
+ */
+export function resolveModelBanMaxTtlMs(): number {
+  return readInt(
+    "CARTETHYIA_MODEL_BAN_MAX_TTL_MS",
+    CONFIG_SPEC.CARTETHYIA_MODEL_BAN_MAX_TTL_MS,
+  );
+}
+
 /** Reads the application encryption key without caching it. */
 export function requireEncryptionKeyEnv(): string {
   return readRequired("CARTETHYIA_ENCRYPTION_KEY", CONFIG_SPEC.CARTETHYIA_ENCRYPTION_KEY);