@spacefast/common 0.0.10 → 0.0.12

package/dist/agents/connect-targets.d.ts

@@ -1,7 +1,7 @@
 export declare const LOCAL_MCP_PACKAGE = "spacefast";
 export declare const LOCAL_MCP_COMMAND = "npx";
-export declare const LOCAL_MCP_ARGS: readonly ["-y", "spacefast", "mcp"];
-/** The copy-paste one-liner form, e.g. `npx -y spacefast mcp`. */
+export declare const LOCAL_MCP_ARGS: readonly ["-y", "spacefast", "mcp", "--preset", "essential"];
+/** The copy-paste one-liner form with the lean default tool surface. */
 export declare const LOCAL_MCP_COMMAND_LINE: string;
 /**
  * base64 of a UTF-8 string, without Buffer. Byte-identical to
@@ -14,7 +14,7 @@ export declare function localMcpServersJson(): {
     mcpServers: {
         spacefast: {
             command: string;
-            args: ("mcp" | "spacefast" | "-y")[];
+            args: ("mcp" | "essential" | "spacefast" | "-y" | "--preset")[];
             env: {};
         };
     };
@@ -30,7 +30,7 @@ export declare function vscodeMcpServersJson(): {
         spacefast: {
             type: string;
             command: string;
-            args: ("mcp" | "spacefast" | "-y")[];
+            args: ("mcp" | "essential" | "spacefast" | "-y" | "--preset")[];
         };
     };
 };

package/dist/agents/connect-targets.js

@@ -15,8 +15,8 @@
 import { spacefastClaudePluginAddCommand, spacefastClaudePluginInstallCommand, spacefastCodexPluginAddCommand, spacefastCodexPluginInstallCommand, } from "../docs/skill-distribution.js";
 export const LOCAL_MCP_PACKAGE = "spacefast";
 export const LOCAL_MCP_COMMAND = "npx";
-export const LOCAL_MCP_ARGS = ["-y", LOCAL_MCP_PACKAGE, "mcp"];
-/** The copy-paste one-liner form, e.g. `npx -y spacefast mcp`. */
+export const LOCAL_MCP_ARGS = ["-y", LOCAL_MCP_PACKAGE, "mcp", "--preset", "essential"];
+/** The copy-paste one-liner form with the lean default tool surface. */
 export const LOCAL_MCP_COMMAND_LINE = `${LOCAL_MCP_COMMAND} ${LOCAL_MCP_ARGS.join(" ")}`;
 /**
  * base64 of a UTF-8 string, without Buffer. Byte-identical to
@@ -65,7 +65,7 @@ export function vscodeMcpServersJson() {
  * on-device for local ones — but a one-click install must never depend on the
  * user having npm/npx. The hosted URL server needs no runtime at all (the
  * client speaks HTTP + OAuth), so every deeplink and every primary action
- * carries the hosted endpoint. On-device stdio (`npx -y spacefast mcp`) stays
+ * carries the hosted endpoint. On-device stdio (`npx -y spacefast mcp --preset essential`) stays
  * available as the explicitly-labeled alternative for people who run the CLI —
  * their environment already provides npx.
  */

package/dist/agents/private-key-oauth.d.ts

@@ -0,0 +1,37 @@
+import { webcrypto } from "node:crypto";
+export type AgentPrivateJwk = webcrypto.JsonWebKey & {
+    kid?: string;
+};
+export type AgentAuthConfig = {
+    client_id: string;
+    token_endpoint: string;
+    private_jwk: AgentPrivateJwk;
+    scope?: string | undefined;
+    resources?: string[] | undefined;
+};
+export type AgentAuthEnvironment = Readonly<Record<string, string | undefined>>;
+export type AgentTokenExchangeErrorInput = {
+    status: number;
+    code: "agent_token_exchange_failed";
+    message: string;
+};
+export type AgentTokenExchangeResult = {
+    accessToken: string;
+    expiresIn: number;
+};
+/** Parse private-key agent credentials using the established bundled-over-split env precedence. */
+export declare function readAgentAuthConfig(env: AgentAuthEnvironment, apiUrl: string): AgentAuthConfig | null;
+export declare function resolveAgentApiAuthorization(config: AgentAuthConfig, apiUrl: string): {
+    resources: string[];
+    scope: string | undefined;
+};
+export declare function createPrivateKeyJwtAssertion(config: AgentAuthConfig, createInvalidConfigError?: (message: string) => Error): Promise<string>;
+export declare function exchangeAgentAccessToken(input: {
+    apiUrl: string;
+    client: string;
+    config: AgentAuthConfig;
+    signal: AbortSignal;
+    createError: (input: AgentTokenExchangeErrorInput) => Error;
+    createInvalidConfigError?: ((message: string) => Error) | undefined;
+    fetch?: typeof globalThis.fetch | undefined;
+}): Promise<AgentTokenExchangeResult>;

package/dist/agents/private-key-oauth.js

@@ -0,0 +1,158 @@
+import { randomUUID, webcrypto } from "node:crypto";
+import { OAUTH_API_RESOURCE_SCOPES, oauthApiResourceUrl } from "../contracts/oauth-resources.js";
+const PRIVATE_KEY_JWT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+const API_RESOURCE_SCOPES = new Set(OAUTH_API_RESOURCE_SCOPES);
+const INVALID_PRIVATE_KEY_MESSAGE = "SPACEFAST_AGENT_CONFIG private_jwk must be an ES256 P-256 JWK.";
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isJwkObject(value) {
+    // Keep parsing permissive here. Web Crypto remains the authority on the JWK's
+    // individual fields, matching the callers' previous behavior.
+    return value !== null && typeof value === "object";
+}
+function readJsonObject(value) {
+    if (!value?.trim()) {
+        return null;
+    }
+    const parsed = JSON.parse(value);
+    return isRecord(parsed) ? parsed : null;
+}
+function stringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : undefined;
+}
+/** Parse private-key agent credentials using the established bundled-over-split env precedence. */
+export function readAgentAuthConfig(env, apiUrl) {
+    const bundled = readJsonObject(env.SPACEFAST_AGENT_CONFIG);
+    const bundledPrivateJwk = bundled?.private_jwk;
+    const privateJwk = isJwkObject(bundledPrivateJwk)
+        ? bundledPrivateJwk
+        : readJsonObject(env.SPACEFAST_AGENT_PRIVATE_JWK);
+    const clientId = (typeof bundled?.client_id === "string" ? bundled.client_id : undefined) ??
+        env.SPACEFAST_AGENT_CLIENT_ID;
+    if (!clientId || !privateJwk) {
+        return null;
+    }
+    const tokenEndpoint = (typeof bundled?.token_endpoint === "string" ? bundled.token_endpoint : undefined) ??
+        env.SPACEFAST_AGENT_TOKEN_ENDPOINT ??
+        `${apiUrl}/v1/auth/oauth2/token`;
+    const scope = (typeof bundled?.scope === "string" ? bundled.scope : undefined) ?? env.SPACEFAST_AGENT_SCOPE;
+    const resources = stringArray(bundled?.resources) ??
+        (env.SPACEFAST_AGENT_RESOURCES
+            ? env.SPACEFAST_AGENT_RESOURCES.split(",")
+                .map((entry) => entry.trim())
+                .filter(Boolean)
+            : undefined);
+    return {
+        client_id: clientId,
+        token_endpoint: tokenEndpoint,
+        private_jwk: privateJwk,
+        ...(scope ? { scope } : {}),
+        ...(resources?.length ? { resources } : {}),
+    };
+}
+export function resolveAgentApiAuthorization(config, apiUrl) {
+    const configuredResources = config.resources;
+    let resources;
+    if (!configuredResources?.length) {
+        resources = [];
+    }
+    else {
+        const apiResource = oauthApiResourceUrl(apiUrl);
+        resources = configuredResources.includes(apiResource) ? [apiResource] : configuredResources;
+    }
+    if (!config.scope || resources.length !== 1) {
+        return { resources, scope: config.scope };
+    }
+    const apiScopes = config.scope
+        .split(/\s+/)
+        .map((entry) => entry.trim())
+        .filter((entry) => API_RESOURCE_SCOPES.has(entry));
+    return {
+        resources,
+        scope: apiScopes.length > 0 ? apiScopes.join(" ") : undefined,
+    };
+}
+function base64urlJson(value) {
+    return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+export async function createPrivateKeyJwtAssertion(config, createInvalidConfigError = (message) => new Error(message)) {
+    if (config.private_jwk.kty !== "EC") {
+        throw createInvalidConfigError(INVALID_PRIVATE_KEY_MESSAGE);
+    }
+    const now = Math.floor(Date.now() / 1000);
+    const key = await webcrypto.subtle.importKey("jwk", config.private_jwk, { name: "ECDSA", namedCurve: "P-256" }, false, ["sign"]);
+    const header = base64urlJson({
+        alg: "ES256",
+        typ: "JWT",
+        ...(config.private_jwk.kid ? { kid: config.private_jwk.kid } : {}),
+    });
+    const payload = base64urlJson({
+        iss: config.client_id,
+        sub: config.client_id,
+        aud: config.token_endpoint,
+        jti: randomUUID(),
+        iat: now,
+        exp: now + 300,
+    });
+    const signingInput = `${header}.${payload}`;
+    const signature = await webcrypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, key, new TextEncoder().encode(signingInput));
+    return `${signingInput}.${Buffer.from(signature).toString("base64url")}`;
+}
+function oauthErrorDescription(payload) {
+    return isRecord(payload) && "error_description" in payload
+        ? String(payload.error_description)
+        : undefined;
+}
+function oauthAccessToken(payload) {
+    return isRecord(payload) && typeof payload.access_token === "string"
+        ? payload.access_token
+        : undefined;
+}
+function oauthExpiresIn(payload) {
+    return isRecord(payload) && typeof payload.expires_in === "number" ? payload.expires_in : 300;
+}
+export async function exchangeAgentAccessToken(input) {
+    const { resources, scope } = resolveAgentApiAuthorization(input.config, input.apiUrl);
+    const body = new URLSearchParams({
+        grant_type: "client_credentials",
+        client_id: input.config.client_id,
+        client_assertion_type: PRIVATE_KEY_JWT_ASSERTION_TYPE,
+        client_assertion: await createPrivateKeyJwtAssertion(input.config, input.createInvalidConfigError),
+    });
+    if (scope) {
+        body.set("scope", scope);
+    }
+    for (const resource of resources) {
+        body.append("resource", resource);
+    }
+    const response = await (input.fetch ?? globalThis.fetch)(input.config.token_endpoint, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/x-www-form-urlencoded",
+            "x-spacefast-client": input.client,
+        },
+        body,
+        signal: input.signal,
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+        throw input.createError({
+            status: response.status,
+            code: "agent_token_exchange_failed",
+            message: oauthErrorDescription(payload) ?? response.statusText,
+        });
+    }
+    const accessToken = oauthAccessToken(payload);
+    if (accessToken === undefined) {
+        throw input.createError({
+            status: response.status,
+            code: "agent_token_exchange_failed",
+            message: "OAuth token endpoint did not return an access_token.",
+        });
+    }
+    return { accessToken, expiresIn: oauthExpiresIn(payload) };
+}

package/dist/config/domains.js

@@ -29,7 +29,7 @@ export function envDomainsFor(domain) {
             superadmin: `superadmin.${domain}`,
             cast: `cast.${domain}`,
             mcp: `mcp.${domain}`,
-            fieldguide: prod ? "fieldguide.view.fast" : `fieldguide.${domain}`,
+            fieldguide: prod ? "pitch.view.fast" : `fieldguide.${domain}`,
         },
     };
 }

package/dist/config/index.d.ts

@@ -1 +1,2 @@
 export * from "./domains.js";
+export * from "./postgres-budget.js";

package/dist/config/index.js

@@ -1,3 +1,4 @@
 // Public entry for the centralized domain/URL registry.
 // Consumers import from "@spacefast/common/config".
 export * from "./domains.js";
+export * from "./postgres-budget.js";

package/dist/config/postgres-budget.d.ts

@@ -0,0 +1,126 @@
+import { z } from "zod";
+declare const postgresConnectionBudgetSchema: z.ZodObject<{
+    server: z.ZodObject<{
+        maxConnections: z.ZodNumber;
+        superuserReservedConnections: z.ZodNumber;
+    }, z.core.$strip>;
+    operationalReserveConnections: z.ZodNumber;
+    transactionPools: z.ZodRecord<z.ZodString, z.ZodObject<{
+        serverConnections: z.ZodNumber;
+    }, z.core.$strip>>;
+    services: z.ZodObject<{
+        api: z.ZodObject<{
+            enabledInProduction: z.ZodBoolean;
+            replicas: z.ZodNumber;
+            poolConnectionsPerReplica: z.ZodNumber;
+            fixedConnectionsPerReplica: z.ZodNumber;
+            maxPinnedTransactionsPerReplica: z.ZodNumber;
+            rolloutOverlapReplicas: z.ZodNumber;
+            connectionBudget: z.ZodString;
+        }, z.core.$strip>;
+        worker: z.ZodObject<{
+            enabledInProduction: z.ZodBoolean;
+            replicas: z.ZodNumber;
+            poolConnectionsPerReplica: z.ZodNumber;
+            fixedConnectionsPerReplica: z.ZodNumber;
+            maxPinnedTransactionsPerReplica: z.ZodNumber;
+            rolloutOverlapReplicas: z.ZodNumber;
+            connectionBudget: z.ZodString;
+        }, z.core.$strip>;
+        cast: z.ZodObject<{
+            enabledInProduction: z.ZodBoolean;
+            replicas: z.ZodNumber;
+            poolConnectionsPerReplica: z.ZodNumber;
+            fixedConnectionsPerReplica: z.ZodNumber;
+            maxPinnedTransactionsPerReplica: z.ZodNumber;
+            rolloutOverlapReplicas: z.ZodNumber;
+            connectionBudget: z.ZodString;
+        }, z.core.$strip>;
+        scanWorker: z.ZodObject<{
+            enabledInProduction: z.ZodBoolean;
+            replicas: z.ZodNumber;
+            poolConnectionsPerReplica: z.ZodNumber;
+            fixedConnectionsPerReplica: z.ZodNumber;
+            maxPinnedTransactionsPerReplica: z.ZodNumber;
+            rolloutOverlapReplicas: z.ZodNumber;
+            connectionBudget: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type PostgresConnectionBudget = z.infer<typeof postgresConnectionBudgetSchema>;
+export type PostgresBudgetService = keyof PostgresConnectionBudget["services"];
+export type PostgresConnectionBudgetSummary = {
+    usableServerConnections: number;
+    directSteadyConnections: number;
+    transactionPoolConnections: number;
+    transactionPoolPinnedConnections: number;
+    transactionPoolQueryHeadroom: number;
+    steadyConnections: number;
+    rollingDeploySurgeConnections: number;
+    operationalReserveConnections: number;
+    plannedConnections: number;
+    unallocatedConnections: number;
+};
+export declare const POSTGRES_CONNECTION_BUDGET: {
+    server: {
+        maxConnections: number;
+        superuserReservedConnections: number;
+    };
+    operationalReserveConnections: number;
+    transactionPools: Record<string, {
+        serverConnections: number;
+    }>;
+    services: {
+        api: {
+            enabledInProduction: boolean;
+            replicas: number;
+            poolConnectionsPerReplica: number;
+            fixedConnectionsPerReplica: number;
+            maxPinnedTransactionsPerReplica: number;
+            rolloutOverlapReplicas: number;
+            connectionBudget: string;
+        };
+        worker: {
+            enabledInProduction: boolean;
+            replicas: number;
+            poolConnectionsPerReplica: number;
+            fixedConnectionsPerReplica: number;
+            maxPinnedTransactionsPerReplica: number;
+            rolloutOverlapReplicas: number;
+            connectionBudget: string;
+        };
+        cast: {
+            enabledInProduction: boolean;
+            replicas: number;
+            poolConnectionsPerReplica: number;
+            fixedConnectionsPerReplica: number;
+            maxPinnedTransactionsPerReplica: number;
+            rolloutOverlapReplicas: number;
+            connectionBudget: string;
+        };
+        scanWorker: {
+            enabledInProduction: boolean;
+            replicas: number;
+            poolConnectionsPerReplica: number;
+            fixedConnectionsPerReplica: number;
+            maxPinnedTransactionsPerReplica: number;
+            rolloutOverlapReplicas: number;
+            connectionBudget: string;
+        };
+    };
+};
+export declare function calculatePostgresConnectionBudget(plan: PostgresConnectionBudget, server?: {
+    maxConnections: number;
+    superuserReservedConnections: number;
+}): PostgresConnectionBudgetSummary;
+export declare function assertPostgresServiceConnectionUrl(service: PostgresBudgetService, rawUrl: string, options?: {
+    allowDirectDevelopmentConnection?: boolean;
+}): void;
+export declare function assertPostgresServicePoolBudget(service: PostgresBudgetService, configuredPoolConnections: number): void;
+export declare function assertPostgresServiceNamedLockBudget(service: PostgresBudgetService, configuredNamedLockTransactions: number): void;
+export declare function assertPostgresServerBudget(server: {
+    maxConnections: number;
+    superuserReservedConnections: number;
+}): PostgresConnectionBudgetSummary;
+export declare const POSTGRES_CONNECTION_BUDGET_SUMMARY: PostgresConnectionBudgetSummary;
+export {};

package/dist/config/postgres-budget.js

@@ -0,0 +1,135 @@
+import { z } from "zod";
+import budgetJson from "./postgres-budget.json" with { type: "json" };
+const serviceBudgetSchema = z.object({
+    enabledInProduction: z.boolean(),
+    replicas: z.number().int().nonnegative(),
+    poolConnectionsPerReplica: z.number().int().positive(),
+    fixedConnectionsPerReplica: z.number().int().nonnegative(),
+    maxPinnedTransactionsPerReplica: z.number().int().nonnegative(),
+    rolloutOverlapReplicas: z.number().int().nonnegative(),
+    connectionBudget: z.string().min(1),
+});
+const postgresConnectionBudgetSchema = z
+    .object({
+    server: z.object({
+        maxConnections: z.number().int().positive(),
+        superuserReservedConnections: z.number().int().nonnegative(),
+    }),
+    operationalReserveConnections: z.number().int().nonnegative(),
+    transactionPools: z.record(z.string().min(1), z.object({
+        serverConnections: z.number().int().positive(),
+    })),
+    services: z.object({
+        api: serviceBudgetSchema,
+        worker: serviceBudgetSchema,
+        cast: serviceBudgetSchema,
+        scanWorker: serviceBudgetSchema,
+    }),
+})
+    .superRefine((plan, context) => {
+    for (const [serviceName, service] of Object.entries(plan.services)) {
+        if (service.connectionBudget !== "direct" &&
+            !Object.hasOwn(plan.transactionPools, service.connectionBudget)) {
+            context.addIssue({
+                code: "custom",
+                message: `service ${serviceName} references unknown transaction pool ${service.connectionBudget}`,
+                path: ["services", serviceName, "connectionBudget"],
+            });
+        }
+    }
+    for (const [poolName, pool] of Object.entries(plan.transactionPools)) {
+        const maxPinnedTransactions = Object.values(plan.services)
+            .filter((service) => service.enabledInProduction && service.connectionBudget === poolName)
+            .reduce((total, service) => total +
+            (service.replicas + service.rolloutOverlapReplicas) *
+                service.maxPinnedTransactionsPerReplica, 0);
+        if (maxPinnedTransactions >= pool.serverConnections) {
+            context.addIssue({
+                code: "custom",
+                message: `transaction pool ${poolName} can pin ${maxPinnedTransactions}/${pool.serverConnections} server connections, leaving no callback query capacity`,
+                path: ["transactionPools", poolName, "serverConnections"],
+            });
+        }
+    }
+});
+export const POSTGRES_CONNECTION_BUDGET = postgresConnectionBudgetSchema.parse(budgetJson);
+function serviceFootprint(service) {
+    return service.poolConnectionsPerReplica + service.fixedConnectionsPerReplica;
+}
+export function calculatePostgresConnectionBudget(plan, server = plan.server) {
+    const usableServerConnections = server.maxConnections - server.superuserReservedConnections;
+    if (usableServerConnections <= 0) {
+        throw new Error(`postgres_connection_budget_invalid: maxConnections=${server.maxConnections} must exceed superuserReservedConnections=${server.superuserReservedConnections}`);
+    }
+    const directServices = Object.values(plan.services).filter((service) => service.enabledInProduction && service.connectionBudget === "direct");
+    const directSteadyConnections = directServices.reduce((total, service) => total + service.replicas * serviceFootprint(service), 0);
+    const transactionPoolConnections = Object.values(plan.transactionPools).reduce((total, pool) => total + pool.serverConnections, 0);
+    const transactionPoolPinnedConnections = Object.values(plan.services)
+        .filter((service) => service.enabledInProduction && service.connectionBudget !== "direct")
+        .reduce((total, service) => total +
+        (service.replicas + service.rolloutOverlapReplicas) *
+            service.maxPinnedTransactionsPerReplica, 0);
+    const transactionPoolQueryHeadroom = transactionPoolConnections - transactionPoolPinnedConnections;
+    const steadyConnections = directSteadyConnections + transactionPoolConnections;
+    const rollingDeploySurgeConnections = directServices.reduce((total, service) => total + service.rolloutOverlapReplicas * serviceFootprint(service), 0);
+    const plannedConnections = steadyConnections + rollingDeploySurgeConnections + plan.operationalReserveConnections;
+    return {
+        usableServerConnections,
+        directSteadyConnections,
+        transactionPoolConnections,
+        transactionPoolPinnedConnections,
+        transactionPoolQueryHeadroom,
+        steadyConnections,
+        rollingDeploySurgeConnections,
+        operationalReserveConnections: plan.operationalReserveConnections,
+        plannedConnections,
+        unallocatedConnections: usableServerConnections - plannedConnections,
+    };
+}
+export function assertPostgresServiceConnectionUrl(service, rawUrl, options = {}) {
+    const parsed = new URL(rawUrl);
+    const hostname = parsed.hostname.toLowerCase();
+    const isLocalDevelopmentHost = hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "::1" ||
+        hostname === "[::1]" ||
+        (!hostname.includes(".") && !hostname.includes(":"));
+    if (options.allowDirectDevelopmentConnection && isLocalDevelopmentHost) {
+        return;
+    }
+    const serviceBudget = POSTGRES_CONNECTION_BUDGET.services[service];
+    if (!serviceBudget.enabledInProduction) {
+        throw new Error(`postgres_connection_budget_service_disabled: service=${service}; add its replicas and rollout overlap to the shared budget before production startup`);
+    }
+    const connectionBudget = serviceBudget.connectionBudget;
+    const port = parsed.port || "5432";
+    if (connectionBudget === "direct") {
+        if (port !== "5432") {
+            throw new Error(`postgres_connection_budget_url_mismatch: service=${service} planned=direct port=${port}`);
+        }
+        return;
+    }
+    if (port !== "6432") {
+        throw new Error(`postgres_connection_budget_url_mismatch: service=${service} planned=transaction_pool pool=${connectionBudget} port=${port}`);
+    }
+}
+export function assertPostgresServicePoolBudget(service, configuredPoolConnections) {
+    const expected = POSTGRES_CONNECTION_BUDGET.services[service].poolConnectionsPerReplica;
+    if (configuredPoolConnections !== expected) {
+        throw new Error(`postgres_connection_budget_pool_mismatch: service=${service} configured=${configuredPoolConnections} planned=${expected}; update the shared budget and every affected service in one change`);
+    }
+}
+export function assertPostgresServiceNamedLockBudget(service, configuredNamedLockTransactions) {
+    const expected = POSTGRES_CONNECTION_BUDGET.services[service].maxPinnedTransactionsPerReplica;
+    if (configuredNamedLockTransactions !== expected) {
+        throw new Error(`postgres_connection_budget_named_lock_mismatch: service=${service} configured=${configuredNamedLockTransactions} planned=${expected}`);
+    }
+}
+export function assertPostgresServerBudget(server) {
+    const summary = calculatePostgresConnectionBudget(POSTGRES_CONNECTION_BUDGET, server);
+    if (summary.unallocatedConnections < 0) {
+        throw new Error(`postgres_connection_budget_exceeded: planned=${summary.plannedConnections} usable=${summary.usableServerConnections} max=${server.maxConnections} superuserReserved=${server.superuserReservedConnections}`);
+    }
+    return summary;
+}
+export const POSTGRES_CONNECTION_BUDGET_SUMMARY = assertPostgresServerBudget(POSTGRES_CONNECTION_BUDGET.server);

package/dist/config/postgres-budget.json

@@ -0,0 +1,50 @@
+{
+    "server": {
+        "maxConnections": 25,
+        "superuserReservedConnections": 3
+    },
+    "operationalReserveConnections": 4,
+    "transactionPools": {
+        "controlPlaneRuntime": {
+            "serverConnections": 8
+        }
+    },
+    "services": {
+        "api": {
+            "enabledInProduction": true,
+            "replicas": 2,
+            "poolConnectionsPerReplica": 4,
+            "fixedConnectionsPerReplica": 0,
+            "maxPinnedTransactionsPerReplica": 1,
+            "rolloutOverlapReplicas": 1,
+            "connectionBudget": "controlPlaneRuntime"
+        },
+        "worker": {
+            "enabledInProduction": true,
+            "replicas": 1,
+            "poolConnectionsPerReplica": 4,
+            "fixedConnectionsPerReplica": 0,
+            "maxPinnedTransactionsPerReplica": 1,
+            "rolloutOverlapReplicas": 1,
+            "connectionBudget": "controlPlaneRuntime"
+        },
+        "cast": {
+            "enabledInProduction": true,
+            "replicas": 1,
+            "poolConnectionsPerReplica": 4,
+            "fixedConnectionsPerReplica": 1,
+            "maxPinnedTransactionsPerReplica": 0,
+            "rolloutOverlapReplicas": 1,
+            "connectionBudget": "direct"
+        },
+        "scanWorker": {
+            "enabledInProduction": false,
+            "replicas": 0,
+            "poolConnectionsPerReplica": 2,
+            "fixedConnectionsPerReplica": 0,
+            "maxPinnedTransactionsPerReplica": 1,
+            "rolloutOverlapReplicas": 0,
+            "connectionBudget": "controlPlaneRuntime"
+        }
+    }
+}