@podosoft/podokit 1.6.0 → 1.6.2

package/dist/deploy-checks.d.ts

@@ -24,7 +24,10 @@ export interface ConnectionBudget {
     perProcessTerms: string[];
     steadyProcesses: number;
     steady: number;
-    /** Processes and connections while a rollout runs old and new pods side by side. */
+    /**
+     * Processes and connections while a rollout runs old and new pods side by side,
+     * counting replaced pods that still hold their pools while they terminate.
+     */
     rolloutProcesses: number;
     rollout: number;
     migration: number;
@@ -32,10 +35,18 @@ export interface ConnectionBudget {
 }
 /**
  * The most PostgreSQL connections the deployment can open: every API and worker
- * process with each pool full, the Kubernetes rollout's surge pod per workload
- * (the rendered strategy allows one), and the migration that runs beside the
- * release still serving. Compose replaces containers without a surge. Null when
- * the deployment uses no PostgreSQL.
+ * process with each pool full, a Kubernetes rollout's old and new pods together,
+ * and the migration that runs beside the release still serving. Null when the
+ * deployment uses no PostgreSQL.
+ *
+ * A replaced pod keeps its pools until its process exits, up to its grace period
+ * after the scale-down (the preStop sleep plus the drain for API pods), and the
+ * Deployment controller does not count terminating pods against maxSurge: it
+ * starts the next surge pod as soon as the previous replacement is ready. When
+ * replacements become ready faster than replaced pods exit, every old pod of a
+ * workload can still hold its pools while all of its new pods run, twice its
+ * replicas whatever the surge. Compose stops a container before it starts the
+ * replacement, so it never runs both.
  */
 export declare function connectionBudget(profile: AnyDeployProfile, modules: Set<string>): ConnectionBudget | null;
 /** The plan warning for a budget over the limit, or null. */

package/dist/deploy-checks.js

@@ -104,10 +104,18 @@ function poolSize(runtimeConfig, key, fallback) {
 }
 /**
  * The most PostgreSQL connections the deployment can open: every API and worker
- * process with each pool full, the Kubernetes rollout's surge pod per workload
- * (the rendered strategy allows one), and the migration that runs beside the
- * release still serving. Compose replaces containers without a surge. Null when
- * the deployment uses no PostgreSQL.
+ * process with each pool full, a Kubernetes rollout's old and new pods together,
+ * and the migration that runs beside the release still serving. Null when the
+ * deployment uses no PostgreSQL.
+ *
+ * A replaced pod keeps its pools until its process exits, up to its grace period
+ * after the scale-down (the preStop sleep plus the drain for API pods), and the
+ * Deployment controller does not count terminating pods against maxSurge: it
+ * starts the next surge pod as soon as the previous replacement is ready. When
+ * replacements become ready faster than replaced pods exit, every old pod of a
+ * workload can still hold its pools while all of its new pods run, twice its
+ * replicas whatever the surge. Compose stops a container before it starts the
+ * replacement, so it never runs both.
  */
 function connectionBudget(profile, modules) {
     const postgres = profile.dependencies.postgres;
@@ -123,14 +131,14 @@ function connectionBudget(profile, modules) {
         perProcessTerms.push(`DB_AUTH_POOL_MAX ${authPool}`);
         perProcess += authPool;
     }
-    for (const pool of postgres.appPools ?? []) {
-        const size = poolSize(config, pool.sizeKey, 0);
-        perProcessTerms.push(`${pool.sizeKey} ${size}${pool.extraConnections ? ` + ${pool.extraConnections}` : ""}`);
+    for (const [index, pool] of (postgres.appPools ?? []).entries()) {
+        const [label, size] = "sizeKey" in pool ? [pool.sizeKey, poolSize(config, pool.sizeKey, 0)] : [`appPools[${index}]`, pool.size];
+        perProcessTerms.push(`${label} ${size}${pool.extraConnections ? ` + ${pool.extraConnections}` : ""}`);
         perProcess += size + pool.extraConnections;
     }
     const worker = profile.workloads.worker;
     const steadyProcesses = profile.workloads.api.replicas + (worker?.replicas ?? 0);
-    const rolloutProcesses = steadyProcesses + (profile.driver === "kubernetes-helm" ? 1 + (worker ? 1 : 0) : 0);
+    const rolloutProcesses = profile.driver === "kubernetes-helm" ? 2 * steadyProcesses : steadyProcesses;
     const maxConnections = postgres.maxConnections ?? exports.DEFAULT_MAX_CONNECTIONS;
     const steady = steadyProcesses * perProcess;
     const rollout = rolloutProcesses * perProcess;
@@ -151,7 +159,7 @@ function budgetSummary(budget) {
     return (`each API or worker process holds up to ${budget.perProcess} (${budget.perProcessTerms.join(" + ")}); ` +
         `${budget.steadyProcesses} process(es) hold ${budget.steady}` +
         (budget.rolloutProcesses > budget.steadyProcesses
-            ? `, ${budget.rolloutProcesses} during a rollout hold ${budget.rollout}`
+            ? `, ${budget.rolloutProcesses} during a rollout, counting replaced pods that have not exited, hold ${budget.rollout}`
             : "") +
         `, and the migration adds ${budget.migration} to the ${budget.steady}`);
 }

package/dist/deploy-render.js

@@ -396,7 +396,27 @@ ${entries.length ? `data:\n${entries.map(([key, value]) => `  ${key}: ${quote(va
 // of 1 s: above the API's 800 ms per-check readiness bound, and enough for a busy
 // web server.
 const PROBE_TIMEOUT_SECONDS = 2;
-function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest) {
+// A terminating pod still receives new connections until every node and the
+// ingress controller drop it from the Service's endpoints, while the API and web
+// servers stop accepting them on SIGTERM. The kubelet runs this sleep before it
+// sends SIGTERM, so the pod keeps serving meanwhile. PodoKit's API and web images
+// are Alpine-based and ship /bin/sleep; an exec hook works on every Kubernetes
+// version, unlike the sleep action.
+const PRE_STOP_SLEEP_SECONDS = 5;
+// The web server drains for SHUTDOWN_TIMEOUT seconds (30 unless set) and then
+// force-closes for up to one more. The API's stop waits for in-flight requests
+// without a bound of its own, so it gets the same window, which covers the /api
+// proxy's default 30 s wait. The grace period also counts the preStop sleep.
+const DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 30;
+const SHUTDOWN_MARGIN_SECONDS = 5;
+function terminationGracePeriodSeconds(runtimeConfig) {
+    const configured = runtimeConfig.SHUTDOWN_TIMEOUT;
+    const drain = configured !== undefined && /^\d+$/.test(configured)
+        ? Number(configured)
+        : DEFAULT_SHUTDOWN_TIMEOUT_SECONDS;
+    return PRE_STOP_SLEEP_SECONDS + drain + SHUTDOWN_MARGIN_SECONDS;
+}
+function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds) {
     const name = `${profile.target.release}-${kind}`;
     const workloadSecret = kind === "api" ? profile.secrets.api : profile.secrets.web;
     const secretEnvFrom = workloadSecret
@@ -456,6 +476,7 @@ ${labels(name, 8)}    spec:
         runAsUser: 100
         runAsGroup: 101
         seccompProfile: { type: RuntimeDefault }
+      terminationGracePeriodSeconds: ${gracePeriodSeconds}
       containers:
         - name: ${kind}
           image: ${quote(image)}
@@ -467,6 +488,9 @@ ${labels(name, 8)}    spec:
             - configMapRef: { name: ${profile.target.release}-runtime }
 ${secretEnvFrom}          ports:
             - { name: http, containerPort: 3000 }
+          lifecycle:
+            preStop:
+              exec: { command: [sleep, "${PRE_STOP_SLEEP_SECONDS}"] }
 ${probe}${resources(workload.resources)}---
 apiVersion: v1
 kind: Service
@@ -634,10 +658,11 @@ ${apiPathIngress(profile, tls)}`;
 }
 function applicationManifest(profile, images, rolloutStateDigest, workerCommand, runtimeConfig) {
     const runtimeConfigDigest = digest(["runtime-config", JSON.stringify(sortedRuntimeConfig(runtimeConfig))]);
+    const gracePeriodSeconds = terminationGracePeriodSeconds(runtimeConfig);
     return [
         configMap(profile, runtimeConfig),
-        deployment(profile, "api", profile.workloads.api, images.api, rolloutStateDigest, runtimeConfigDigest),
-        deployment(profile, "web", profile.workloads.web, images.web, rolloutStateDigest, runtimeConfigDigest),
+        deployment(profile, "api", profile.workloads.api, images.api, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds),
+        deployment(profile, "web", profile.workloads.web, images.web, rolloutStateDigest, runtimeConfigDigest, gracePeriodSeconds),
         workerDeployment(profile, images.api, rolloutStateDigest, runtimeConfigDigest, workerCommand),
         disruptionBudget(profile, "api"),
         disruptionBudget(profile, "web"),

package/dist/deploy-schema.d.ts

@@ -70,14 +70,18 @@ export declare function parseReleaseProfile(release: Record<string, unknown>): R
 export declare function parseRuntimeConfig(runtimeConfig: Record<string, unknown>): Record<string, string>;
 /**
  * An application-owned PostgreSQL pool each API or worker process opens beside
- * PodoKit's own: `sizeKey` names the runtimeConfig key that caps it, and
+ * PodoKit's own. Either `sizeKey` names the runtimeConfig key that caps it, or
+ * `size` is the cap the application's code sets, such as a driver's default.
  * `extraConnections` counts connections it opens beyond that cap, such as one to
  * check a server that stopped answering.
  */
-export interface AppConnectionPool {
+export type AppConnectionPool = {
     sizeKey: string;
     extraConnections: number;
-}
+} | {
+    size: number;
+    extraConnections: number;
+};
 /** What the connection budget needs to know about the database, beyond its mode. */
 export interface PostgresBudgetProfile {
     /** The server's max_connections; PodoKit sets it on a database it runs. */

package/dist/deploy-schema.js

@@ -270,7 +270,22 @@ function parsePostgresBudget(value, field, runtimeConfig) {
             const entryField = `${field}.appPools[${index}]`;
             if (!isRecord(entry))
                 throw new Error(`Deployment profile field "${entryField}" must be an object.`);
-            assertOnlyKeys(entry, ["sizeKey", "extraConnections"], entryField);
+            assertOnlyKeys(entry, ["sizeKey", "size", "extraConnections"], entryField);
+            if ((entry.sizeKey === undefined) === (entry.size === undefined)) {
+                throw new Error(`Deployment profile field "${entryField}" must set either sizeKey, the runtimeConfig key that caps the pool, ` +
+                    "or size, the cap the application sets itself.");
+            }
+            const extraConnections = entry.extraConnections ?? 0;
+            if (typeof extraConnections !== "number" || !Number.isInteger(extraConnections) || extraConnections < 0) {
+                throw new Error(`Deployment profile field "${entryField}.extraConnections" must be a non-negative integer.`);
+            }
+            if (entry.size !== undefined) {
+                const size = entry.size;
+                if (typeof size !== "number" || !Number.isInteger(size) || size < 1 || size > MAX_POSTGRES_CONNECTIONS) {
+                    throw new Error(`Deployment profile field "${entryField}.size" must be an integer from 1 to ${MAX_POSTGRES_CONNECTIONS}.`);
+                }
+                return { size, extraConnections };
+            }
             const sizeKey = requiredString(entry, "sizeKey");
             if (!/^[A-Z][A-Z0-9_]*$/.test(sizeKey) || PODOKIT_POOL_KEYS.includes(sizeKey) || seen.has(sizeKey)) {
                 throw new Error(`Deployment profile field "${entryField}.sizeKey" must name another pool's runtimeConfig key, once; ` +
@@ -280,10 +295,6 @@ function parsePostgresBudget(value, field, runtimeConfig) {
             if (!/^[1-9][0-9]*$/.test(runtimeConfig[sizeKey] ?? "")) {
                 throw new Error(`Deployment profile field "${entryField}.sizeKey" names ${sizeKey}, which runtimeConfig must set to a positive integer.`);
             }
-            const extraConnections = entry.extraConnections ?? 0;
-            if (typeof extraConnections !== "number" || !Number.isInteger(extraConnections) || extraConnections < 0) {
-                throw new Error(`Deployment profile field "${entryField}.extraConnections" must be a non-negative integer.`);
-            }
             return { sizeKey, extraConnections };
         });
     }

package/dist/deploy.d.ts

@@ -38,7 +38,16 @@ export interface DeploymentStatus {
         readyReplicas: number;
         replicas: number;
         images: string[];
+        /** Container restarts of the running pods of the Deployment's current revision. */
         restartCount: number;
+        /**
+         * Pods still listed that are not current: from an earlier revision, or
+         * terminating. They linger for the termination grace period after a rollout.
+         */
+        previousPods: {
+            count: number;
+            restartCount: number;
+        };
     }>;
 }
 export interface VerificationResult {

package/dist/deploy.js

@@ -423,15 +423,86 @@ function parseDeployment(output, workloadName) {
     }
     return deployment;
 }
-function restartCount(output, workloadName) {
-    const values = output
-        .split(/\s+/)
-        .map((value) => value.trim())
-        .filter(Boolean);
-    if (values.some((value) => !/^(0|[1-9][0-9]*)$/.test(value))) {
-        throw new Error(`Kubernetes pod restart counts for ${workloadName} are invalid.`);
+const REVISION_ANNOTATION = "deployment.kubernetes.io/revision";
+const POD_TEMPLATE_HASH_LABEL = "pod-template-hash";
+function deploymentRevision(deployment, workloadName) {
+    const revision = deployment.metadata?.annotations?.[REVISION_ANNOTATION];
+    if (typeof revision !== "string" || !/^[1-9][0-9]*$/.test(revision)) {
+        throw new Error(`Kubernetes Deployment ${workloadName} has no valid ${REVISION_ANNOTATION} annotation.`);
     }
-    return values.reduce((sum, value) => sum + Number(value), 0);
+    return revision;
+}
+function kubernetesListItems(output, description) {
+    const list = parseJson(output, description);
+    if (!isRecord(list) || !Array.isArray(list.items)) {
+        throw new Error(`${description} returned an invalid list.`);
+    }
+    return list.items;
+}
+function optionalRecord(value) {
+    return value === undefined || isRecord(value);
+}
+/** The pod-template-hash of the ReplicaSet that carries the Deployment's revision. */
+function currentPodTemplateHash(output, workloadName, revision) {
+    const description = `Kubernetes ReplicaSets of ${workloadName}`;
+    const matching = kubernetesListItems(output, description).map((item) => {
+        if (!isRecord(item) ||
+            !isRecord(item.metadata) ||
+            !optionalRecord(item.metadata.annotations) ||
+            !optionalRecord(item.metadata.labels)) {
+            throw new Error(`${description} have an invalid schema.`);
+        }
+        return {
+            revision: item.metadata.annotations?.[REVISION_ANNOTATION],
+            hash: item.metadata.labels?.[POD_TEMPLATE_HASH_LABEL],
+        };
+    }).filter((replicaSet) => replicaSet.revision === revision);
+    if (matching.length !== 1) {
+        throw new Error(`Kubernetes Deployment ${workloadName} has ${matching.length} ReplicaSets for revision ${revision}; expected one.`);
+    }
+    const hash = matching[0].hash;
+    if (typeof hash !== "string" || hash.length === 0) {
+        throw new Error(`${description}: revision ${revision} has no ${POD_TEMPLATE_HASH_LABEL} label.`);
+    }
+    return hash;
+}
+/**
+ * Restarts of the current revision's running pods, and of the rest separately.
+ * Pods of every revision share the workload label, and an earlier ReplicaSet's
+ * pods stay listed with a deletionTimestamp until they finish terminating.
+ */
+function podRestarts(output, workloadName, currentHash) {
+    const description = `Kubernetes pods of ${workloadName}`;
+    const result = { restartCount: 0, previousPods: { count: 0, restartCount: 0 } };
+    for (const pod of kubernetesListItems(output, description)) {
+        if (!isRecord(pod) ||
+            !isRecord(pod.metadata) ||
+            !optionalRecord(pod.metadata.labels) ||
+            (pod.status !== undefined && !isRecord(pod.status))) {
+            throw new Error(`${description} have an invalid schema.`);
+        }
+        // A pod that has not started a container yet reports no statuses.
+        const statuses = pod.status?.containerStatuses ?? [];
+        if (!Array.isArray(statuses))
+            throw new Error(`${description} have an invalid schema.`);
+        let restarts = 0;
+        for (const status of statuses) {
+            const count = isRecord(status) ? status.restartCount : undefined;
+            if (typeof count !== "number" || !Number.isInteger(count) || count < 0) {
+                throw new Error(`Kubernetes pod restart counts for ${workloadName} are invalid.`);
+            }
+            restarts += count;
+        }
+        const terminating = pod.metadata.deletionTimestamp !== undefined && pod.metadata.deletionTimestamp !== null;
+        if (!terminating && pod.metadata.labels?.[POD_TEMPLATE_HASH_LABEL] === currentHash) {
+            result.restartCount += restarts;
+        }
+        else {
+            result.previousPods.count += 1;
+            result.previousPods.restartCount += restarts;
+        }
+    }
+    return result;
 }
 function planDigest(input, runtime) {
     return (0, node_crypto_1.createHash)("sha256")
@@ -867,14 +938,9 @@ function getDeploymentStatus(projectRoot, profileName, runner = defaultRunner) {
     });
     const deployments = items.map((item) => {
         const name = item.metadata.name;
-        const observedRestartCount = restartCount(checked(runner, "kubectl", kubectlArgs(profile, [
-            "get",
-            "pods",
-            "-l",
-            `app.kubernetes.io/name=${name}`,
-            "-o",
-            "jsonpath={range .items[*].status.containerStatuses[*]}{.restartCount}{\"\\n\"}{end}",
-        ])), name);
+        const selector = `app.kubernetes.io/name=${name}`;
+        const currentHash = currentPodTemplateHash(checked(runner, "kubectl", kubectlArgs(profile, ["get", "replicasets", "-l", selector, "-o", "json"])), name, deploymentRevision(item, name));
+        const restarts = podRestarts(checked(runner, "kubectl", kubectlArgs(profile, ["get", "pods", "-l", selector, "-o", "json"])), name, currentHash);
         return {
             name,
             readyReplicas: item.status?.readyReplicas ?? 0,
@@ -882,7 +948,7 @@ function getDeploymentStatus(projectRoot, profileName, runner = defaultRunner) {
             images: (item.spec?.template?.spec?.containers ?? [])
                 .map((container) => container.image)
                 .filter((image) => typeof image === "string"),
-            restartCount: observedRestartCount,
+            ...restarts,
         };
     });
     return {

package/dist/index.js

@@ -716,7 +716,8 @@ async function main(argv) {
                 }
                 process.stdout.write(`Applied: ${result.written.length} written, ${result.moved.length} moved, ` +
                     `${result.removed.length} removed, ` +
-                    `${result.merged.length} merged, ${result.conflicts.length} conflict.\n`);
+                    `${result.merged.length} merged, ${result.conflicts.length} conflict, ` +
+                    `${result.skipped.length} skipped.\n`);
                 writeApiPaths("Direct API paths:", result.apiPaths, "add");
                 if (result.conflicts.length) {
                     process.stdout.write("\nResolve the following, then commit:\n" +
@@ -729,6 +730,11 @@ async function main(argv) {
                         result.review.map((f) => `  ${f}`).join("\n") +
                         "\n");
                 }
+                if (result.skipped.length) {
+                    process.stdout.write("\nSkipped edited files, left as they are:\n" +
+                        result.skipped.map((file) => `  ${file.path}  (${file.reason})`).join("\n") +
+                        "\n");
+                }
                 return;
             }
             const plan = (0, update_1.planUpdate)(process.cwd(), templatesDir);
@@ -759,7 +765,8 @@ async function main(argv) {
                 }
                 process.stdout.write(`${shown.length ? "\n" : ""}${counts.update} update, ${counts.add} add, ${counts.move} move, ` +
                     `${counts.remove} remove, ${counts.conflict} conflict, ${counts.review} review. ` +
-                    `Dry-run — nothing was written. Re-run with --apply to write (use --from <dir> for a 3-way merge).\n`);
+                    `Dry-run — nothing was written. Re-run with --apply to write; it 3-way merges each conflict ` +
+                    `against the ${plan.fromVersion} templates, fetched from npm unless --from <dir> gives them.\n`);
             }
             writeOwnedTemplateNotes(plan, templatesDir, args.from);
         }

package/dist/templates/fullstack/AGENTS.md

@@ -105,7 +105,9 @@ Merge added module settings from `.env.example` into an existing `.env`.
 - e2e (Playwright, ships in `tests/`): `{{rootRun}} test:e2e`. Run the whole suite on more
   workers with `E2E_WORKERS=2`, never `--workers`. Tag a test `{ tag: "@exclusive" }` when
   it changes state other tests rely on (a server-wide setting, a seeded account's profile);
-  tagged tests run alone after the rest. Give each test its own mail and SMS recipients and
+  tagged tests run alone after the rest, in a second Playwright run that `test:e2e` starts
+  even when the first one failed, so run the suite through `test:e2e`, not
+  `bunx playwright test`, on more workers. Give each test its own mail and SMS recipients and
   never empty the shared Mailpit inbox or SMS sink. See `tests/README.md`. The managed specs
   read the app's first screen, public pages, and seeded accounts from the owned
   `tests/helpers/app-paths.ts` (and `app-accounts.ts` with admin-dashboard): change those

package/dist/templates/fullstack/apps/api/package.json

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@podosoft/podokit-contracts": "^0.6.0",
-    "@podosoft/podokit-runtime": "^0.5.0",
+    "@podosoft/podokit-runtime": "^0.5.1",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/scripts/verify-api-contract.ts

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createApp } from "../src/app";
 import { validateEnv } from "../src/config/env.validation";
+import { PROVIDERS } from "../src/config/providers";
 import {
   assertApiContract,
   assertApplicationRoutes,
@@ -30,7 +31,7 @@ try {
   }
   const document: unknown = await response.json();
   const modules = manifest.modules.map((module) => module.name);
-  assertApiContract(document, manifest.template, modules);
+  assertApiContract(document, manifest.template, modules, PROVIDERS);
   assertApplicationRoutes(document, app.routes, APP_DOCUMENTED_ROUTES);
   process.stdout.write(
     `Verified ${documentedApiRoutes(document).size} documented API operations for ${manifest.template}, ` +

package/dist/templates/fullstack/apps/api/src/build.spec.ts

@@ -4,14 +4,17 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 
 const BUILD = join(__dirname, "../scripts/build.mjs");
-const EXTENSIONS = join(__dirname, "../scripts/build.extensions.mjs");
+// The application's own build.extensions.mjs names entry points this temporary
+// layout does not contain, so each build starts without application targets. A
+// test that needs some passes its own scripts/build.extensions.mjs.
+const NO_APP_TARGETS = "export const appBuildTargets = [];\n";
 
 /** Builds an API layout made of `files` with the app's build script. */
 async function build(files: Record<string, string>): Promise<{ root: string; code: number; stderr: string }> {
   const root = mkdtempSync(join(tmpdir(), "api-build-"));
   mkdirSync(join(root, "scripts"));
   cpSync(BUILD, join(root, "scripts/build.mjs"));
-  cpSync(EXTENSIONS, join(root, "scripts/build.extensions.mjs"));
+  writeFileSync(join(root, "scripts/build.extensions.mjs"), NO_APP_TARGETS);
   for (const [path, content] of Object.entries(files)) {
     mkdirSync(dirname(join(root, path)), { recursive: true });
     writeFileSync(join(root, path), content);

package/dist/templates/fullstack/apps/api/src/core/api-contract.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "bun:test";
+import { LOCAL_PROVIDER_SELECTIONS, SERVER_PROVIDER_SELECTIONS } from "@podosoft/podokit-runtime";
 import {
   assertApiContract,
   assertApplicationRoutes,
@@ -12,7 +13,7 @@ import {
 
 describe("API contract inventory", () => {
   it("covers the core, Todo, module, and Better Auth routes", () => {
-    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"]);
+    const expected = expectedApiRoutes("todo", ["auth", "redis", "file-upload"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /health/ready");
     expect(expected).toContain("PATCH /todos/{id}");
@@ -23,7 +24,7 @@ describe("API contract inventory", () => {
   });
 
   it("uses one structural parameter name for every public blog post route", () => {
-    const expected = expectedApiRoutes("fullstack", ["blog"]);
+    const expected = expectedApiRoutes("fullstack", ["blog"], SERVER_PROVIDER_SELECTIONS);
 
     expect(expected).toContain("GET /blog/{postRef}");
     expect(expected).toContain("PATCH /blog/{postRef}");
@@ -32,15 +33,53 @@ describe("API contract inventory", () => {
     expect(expected).not.toContain("PATCH /blog/{id}");
   });
 
+  it("expects a provider module's routes only while its provider is selected", () => {
+    const modules = [
+      "object-storage-s3",
+      "object-storage-local",
+      "redis",
+      "cache-memory",
+      "bullmq",
+      "jobs-local",
+    ];
+    const server = expectedApiRoutes("fullstack", modules, SERVER_PROVIDER_SELECTIONS);
+    const local = expectedApiRoutes("fullstack", modules, LOCAL_PROVIDER_SELECTIONS);
+
+    expect(server).toContain("PUT /storage/{key}");
+    expect(server).not.toContain("GET /files/content/*");
+    expect(server).toContain("PUT /cache/{key}");
+    expect(server).toContain("POST /jobs");
+    expect(local).toContain("PUT /storage/{key}");
+    expect(local).toContain("GET /files/content/*");
+    expect(local).not.toContain("PUT /cache/{key}");
+    expect(local).not.toContain("GET /cache/{key}");
+    expect(local).toContain("GET /jobs/{id}");
+
+    const s3Document = {
+      paths: {
+        "/health": { get: {} },
+        "/health/ready": { get: {} },
+        "/storage/{key}": { get: {}, put: {} },
+        "/storage/{key}/presigned": { get: {} },
+      },
+    };
+    const storage = ["object-storage-s3", "object-storage-local"];
+    expect(() => assertApiContract(s3Document, "fullstack", storage, SERVER_PROVIDER_SELECTIONS)).not.toThrow();
+    expect(() => assertApiContract(s3Document, "fullstack", storage, {
+      ...SERVER_PROVIDER_SELECTIONS,
+      "object-storage": "local",
+    })).toThrow("GET /files/content/*");
+  });
+
   it("normalizes OpenAPI operations and reports an exact missing route", () => {
     const document = { paths: { "/health": { get: {} }, "/health/ready": { get: {} } } };
 
     expect(documentedApiRoutes(document)).toEqual(new Set(["GET /health", "GET /health/ready"]));
-    expect(missingApiRoutes(document, "fullstack", ["redis"])).toEqual([
+    expect(missingApiRoutes(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toEqual([
       "GET /cache/{key}",
       "PUT /cache/{key}",
     ]);
-    expect(() => assertApiContract(document, "fullstack", ["redis"])).toThrow(
+    expect(() => assertApiContract(document, "fullstack", ["redis"], SERVER_PROVIDER_SELECTIONS)).toThrow(
       "OpenAPI contract is missing routes",
     );
   });

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -1,3 +1,5 @@
+import type { ProviderCapability, ProviderSelections } from "@podosoft/podokit-runtime";
+
 const OPERATIONS = new Set(["get", "post", "put", "patch", "delete", "options", "head"]);
 
 const CORE_ROUTES = [
@@ -81,6 +83,7 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "DELETE /files/uploads/{id}",
   ],
   "job-progress": ["POST /progress"],
+  "jobs-local": ["POST /jobs", "GET /jobs/{id}"],
   "object-storage-local": [
     "GET /files/content/*",
     "PUT /storage/{key}",
@@ -96,6 +99,22 @@ const MODULE_ROUTES: Record<string, string[]> = {
   sse: ["GET /events/stream", "POST /events"],
 };
 
+/**
+ * The provider each provider module implements. Such a module registers its
+ * routes only while its provider is selected, so an app may keep, say, both
+ * object-storage modules installed and serve the routes of one.
+ */
+export const MODULE_PROVIDERS: Readonly<Record<string, readonly [ProviderCapability, string]>> = {
+  bullmq: ["jobs", "bullmq"],
+  "cache-memory": ["cache", "memory"],
+  "events-memory": ["events", "memory"],
+  "events-redis": ["events", "redis"],
+  "jobs-local": ["jobs", "local"],
+  "object-storage-local": ["object-storage", "local"],
+  "object-storage-s3": ["object-storage", "s3"],
+  redis: ["cache", "redis"],
+};
+
 interface RuntimeRoute {
   method?: string;
   path: string;
@@ -195,10 +214,20 @@ export function documentedApiRoutes(document: unknown): Set<string> {
   return routes;
 }
 
-export function expectedApiRoutes(template: string, modules: string[]): Set<string> {
+/**
+ * The routes the template and the installed modules serve. A provider module
+ * counts only when `providers`, the app's PROVIDERS, selects its provider.
+ */
+export function expectedApiRoutes(
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): Set<string> {
   const routes = new Set(CORE_ROUTES);
   for (const route of TEMPLATE_ROUTES[template] ?? []) routes.add(route);
   for (const module of modules) {
+    const provider = MODULE_PROVIDERS[module];
+    if (provider && providers[provider[0]] !== provider[1]) continue;
     for (const route of MODULE_ROUTES[module] ?? []) routes.add(route);
   }
   return routes;
@@ -208,15 +237,21 @@ export function missingApiRoutes(
   document: unknown,
   template: string,
   modules: string[],
+  providers: Readonly<ProviderSelections>,
 ): string[] {
   const documented = documentedApiRoutes(document);
-  return [...expectedApiRoutes(template, modules)]
+  return [...expectedApiRoutes(template, modules, providers)]
     .filter((route) => !documented.has(route))
     .sort();
 }
 
-export function assertApiContract(document: unknown, template: string, modules: string[]): void {
-  const missing = missingApiRoutes(document, template, modules);
+export function assertApiContract(
+  document: unknown,
+  template: string,
+  modules: string[],
+  providers: Readonly<ProviderSelections>,
+): void {
+  const missing = missingApiRoutes(document, template, modules, providers);
   if (missing.length > 0) {
     throw new Error(`OpenAPI contract is missing routes:\n${missing.join("\n")}`);
   }

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/SKILL.md

@@ -22,7 +22,7 @@ Read the profile's `driver` first and say which one you are operating.
 7. Do not apply until the user explicitly approves that exact plan.
 8. Apply with `{{packageExecutor}} @podosoft/podokit deploy apply --profile <name> --release <stable-semver> --confirm <plan-hash>`.
 9. Run `{{packageExecutor}} @podosoft/podokit deploy status --profile <name> --json` and `{{packageExecutor}} @podosoft/podokit deploy verify --profile <name> --json`.
-10. Report the exact images, the revision, running replicas, restart totals, and the verification result. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
+10. Report the exact images, the revision, running replicas, restart counts, and the verification result. On Kubernetes, each Deployment's `restartCount` covers only the running pods of its current revision, and `previousPods` gives the `count` and `restartCount` of the pods still listed from an earlier revision or terminating. Right after `apply` or `rollback` these are usually the replaced pods finishing their grace period: report them separately and never attribute their restarts to the new release. Report `syncDrift` too: a non-empty value means containers are running locally synced artifacts and the release tag does not describe what is serving.
 
 ## Iterating against a deployment is a different command
 

package/dist/templates/fullstack/dot-agents/skills/podokit-deploy/references/profile.md

@@ -32,8 +32,11 @@ Review these fields before planning:
 - `workloads`: API/web replicas and resources plus an optional worker
 - `dependencies`: PostgreSQL, Redis, and object storage mode, image, Secret name, and storage.
   PostgreSQL also takes `maxConnections` (default 100) and `appPools` for pools the
-  application opens itself; the doctor and the plan check the connection budget
-  against them, so lower `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
+  application opens itself, each sized by a `runtimeConfig` key (`sizeKey`) or a
+  fixed `size` when the code sets it; the doctor and the plan check the connection budget
+  against them, counting every API and worker replica twice during a Kubernetes rollout
+  because replaced pods keep their pools until they exit, so lower
+  `DB_POOL_MAX`/`DB_AUTH_POOL_MAX` or replicas when they warn.
 - `secrets`: API/optional web Secret names and required key names, plus image-pull Secret
 - `runtimeConfig`: non-sensitive environment values only
 - `verification`: HTTPS origin and checks with exact statuses and optional JSON fields