@elench/testkit 0.1.116 → 0.1.118

package/README.md

@@ -325,13 +325,24 @@ stable build-and-start flows.
 
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
-source database as the schema source of truth. A normal `testkit run` refreshes
-`.testkit/db/<service>/source-schema.sql` from the source database when needed,
-applies that cached schema to the local template DB, runs local template setup,
-and verifies that the replayed local schema still matches the source dump. If
-local replay differs, Testkit refreshes from the source once and retries. If it
-still differs, the run fails with schema diagnostics under
-`.testkit/results/schema`.
+source database as the schema source of truth. A normal `testkit run` resolves a
+commit-aware source schema cache under
+`.testkit/db/<service>/source-schemas/`, applies that cached schema to the local
+template DB, runs local template setup, and verifies that the replayed local
+schema still matches the source dump. If local replay differs, Testkit refreshes
+from the source once for the current cache key and retries. If it still differs,
+the run fails with schema diagnostics under `.testkit/results/schema`.
+
+Source schema cache keys are derived automatically from repo state:
+
+- clean git worktrees use `commits/<sha>`
+- dirty git worktrees use `dirty/<sha>-<fingerprint>`
+- non-git directories use `nogit/<fingerprint>`
+
+Branch names and worktree paths are recorded as metadata but do not affect clean
+commit cache keys, so branch renames and clean worktrees at the same commit
+reuse the same source schema. Dirty worktrees are isolated by content
+fingerprint so local experiments cannot overwrite a clean commit baseline.
 
 Template setup executes in three explicit phases:
 
@@ -346,6 +357,16 @@ is never written into the baseline. Keep schema-changing setup in its own step
 where possible; a single command that changes schema and then fails before
 exiting cannot be refreshed at the midpoint.
 
+Source schema refreshes are intentionally single-connection and pooler-safe.
+If a Neon pooled source URL is configured, Testkit rewrites it to the matching
+direct Neon endpoint before running `pg_dump` and records the original/resolved
+host classifications beside the resolved cache entry. Unknown PgBouncer/pooler
+URLs fail closed; configure a direct source URL for those providers. Concurrent
+refreshes for the same service and cache key are serialized with a cache-local
+lock so multiple Testkit processes do not stampede the source database. Testkit
+also maintains `.testkit/db/<service>/source-schemas/index.json` and prunes old
+inactive cache entries automatically.
+
 For most repos, prefer declarative step objects directly inside
 `database.postgres({ template: ... })` and `runtime.prepare.steps`.
 The supported shapes are:
@@ -686,6 +707,8 @@ services that define `database: database.postgres(...)`.
 - runtime databases are cloned from templates when binding is `per-runtime`
 - shared databases are reused when binding is `shared`
 - source schema caches are refreshed only from the configured source database
+- clean commits, dirty worktrees, and non-git directories get separate source
+  schema cache entries automatically
 - template fingerprints are derived automatically from env files, source schema
   cache, migrate/seed config, and repo contents
 
@@ -702,6 +725,7 @@ npm test
 npm run test:unit
 npm run test:integration
 npm run test:system
+npm run test:live:github
 npm run test:live:neon
 npm run test:database-version:compat
 ```

package/lib/cli/assistant/context-pack.mjs

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath } from "url";
 import { readContextContent, buildContextSelection } from "../../results/context.mjs";
 import { assistantSessionPaths, createAssistantSessionId } from "./session-paths.mjs";
 import {
@@ -88,7 +88,6 @@ export function prepareAssistantContextPack({
     );
     if (!fs.existsSync(wrapperPath)) fs.writeFileSync(wrapperPath, buildWrapperScript({
       cliPath: resolveCliPath(),
-      classifierUrl: resolveClassifierUrl(),
       sessionId,
       resultDir,
       commandLogPath,
@@ -165,16 +164,11 @@ function resolveCliPath() {
   return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "bin", "testkit.mjs");
 }
 
-function resolveClassifierUrl() {
-  return pathToFileURL(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "command-classifier.mjs")).href;
-}
-
-function buildWrapperScript({ cliPath, classifierUrl, sessionId, resultDir, commandLogPath } = {}) {
+function buildWrapperScript({ cliPath, sessionId, resultDir, commandLogPath } = {}) {
   return `#!/usr/bin/env node
-import { spawnSync } from "child_process";
-import fs from "fs";
-import path from "path";
-import { classifyAssistantCommandKind } from ${JSON.stringify(classifierUrl)};
+const { spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
 
 const commandId = process.env.${ASSISTANT_COMMAND_ID_ENV} || \`cmd-\${Date.now()}-\${Math.random().toString(36).slice(2, 10)}\`;
 const commandLogPath = process.env.${ASSISTANT_COMMAND_LOG_ENV} || ${JSON.stringify(commandLogPath)};
@@ -231,6 +225,32 @@ function appendCommandLog(event) {
     // Command observation must not affect command execution.
   }
 }
+
+function classifyAssistantCommandKind(argv = []) {
+  const runShortcuts = new Set(["ui", "e2e", "scenario", "int", "dal", "load", "all"]);
+  const valueFlags = new Set([
+    "--dir",
+    "--service",
+    "--type",
+    "--suite",
+    "--file",
+    "--workers",
+    "--file-timeout-seconds",
+    "--seed",
+    "--output-mode",
+  ]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = String(argv[index] || "");
+    if (valueFlags.has(value)) {
+      index += 1;
+      continue;
+    }
+    if (!value.startsWith("-")) {
+      return runShortcuts.has(value) ? "run" : value;
+    }
+  }
+  return "run";
+}
 `;
 }
 

package/lib/cli/operations/db/schema/refresh/operation.mjs

@@ -4,7 +4,7 @@ import path from "path";
 import { loadManagedConfigs, resolveTargetConfig, collectRequiredConfigs, topologicallySortConfigs } from "../../../../../app/configs.mjs";
 import { resolveProductDir } from "../../../../../config/index.mjs";
 import { prepareDatabaseRuntime } from "../../../../../database/index.mjs";
-import { forceRefreshSourceSchemaCache, getSourceSchemaCachePath } from "../../../../../database/schema-source.mjs";
+import { forceRefreshSourceSchemaCache } from "../../../../../database/schema-source.mjs";
 import { createRunReporter } from "../../../../renderers/run/text-reporter.mjs";
 import { createRunLogRegistry } from "../../../../../runner/logs.mjs";
 import { createSetupOperationRegistry } from "../../../../../runner/setup-operations.mjs";
@@ -40,14 +40,18 @@ export async function executeDatabaseSchemaRefreshOperation(options = {}) {
       logRegistry,
       setupRegistry,
     });
-    const outputPath = getSourceSchemaCachePath(resolvedTarget);
+    const outputPath = state.cachePath;
     return {
       ok: true,
       productDir,
       service: target.name,
       outputPath,
       outputLabel: path.relative(productDir, outputPath) || path.basename(outputPath),
+      cacheKey: state.cacheKey,
+      cacheKind: state.cacheKind,
       envName: state.envName || null,
+      sourceUrl: state.refreshInfo?.metadata?.sourceUrl || null,
+      reusedExistingRefresh: Boolean(state.refreshInfo?.reusedExistingRefresh),
     };
   } finally {
     logRegistry.closeAll();

package/lib/cli/renderers/db-schema/text.mjs

@@ -1,5 +1,15 @@
 export function renderDatabaseSchemaRefreshResult(result) {
-  return [`Refreshed ${result.outputLabel}`];
+  const lines = [`Refreshed ${result.outputLabel}`];
+  if (result.cacheKey) {
+    lines.push(`Cache key ${result.cacheKey}`);
+  }
+  if (result.sourceUrl?.rewritten && result.sourceUrl.originalClassification === "neon-pooler") {
+    lines.push("Source schema URL uses Neon pooler; Testkit used the direct endpoint for pg_dump.");
+  }
+  if (result.reusedExistingRefresh) {
+    lines.push("Another Testkit process refreshed this source schema cache first; reused that result.");
+  }
+  return lines;
 }
 
 export function renderDatabaseSchemaVerifyResult(result) {

package/lib/config/database.mjs

@@ -66,8 +66,7 @@ function normalizeSourceSchemaConfig(value, serviceName) {
   if (value === undefined) {
     return {
       kind: "auto",
-      cachePath: null,
-      refresh: { mode: "always" },
+      refresh: { mode: "auto" },
       unavailable: "auto",
       verify: true,
     };
@@ -79,13 +78,17 @@ function normalizeSourceSchemaConfig(value, serviceName) {
   if (kind !== "env") {
     throw new Error(`Service "${serviceName}" database.sourceSchema.kind must be "env"`);
   }
+  if (Object.prototype.hasOwnProperty.call(value, "cachePath")) {
+    throw new Error(
+      `Service "${serviceName}" database.sourceSchema.cachePath has been removed. Testkit now manages commit-scoped source schema caches automatically.`
+    );
+  }
   if (typeof value.env !== "string" || value.env.trim().length === 0) {
     throw new Error(`Service "${serviceName}" database.sourceSchema.env must be a non-empty string`);
   }
   return {
     kind,
     env: value.env.trim(),
-    cachePath: normalizeOptionalString(value.cachePath, `Service "${serviceName}" database.sourceSchema.cachePath`),
     refresh: normalizeSourceSchemaRefresh(value.refresh, serviceName),
     unavailable: normalizeSourceSchemaUnavailable(value.unavailable, serviceName),
     verify: value.verify !== false,
@@ -93,7 +96,8 @@ function normalizeSourceSchemaConfig(value, serviceName) {
 }
 
 function normalizeSourceSchemaRefresh(value, serviceName) {
-  if (value == null || value === "always") return { mode: "always" };
+  if (value == null || value === "auto") return { mode: "auto" };
+  if (value === "always") return { mode: "always" };
   if (typeof value === "object" && !Array.isArray(value)) {
     const ttlSeconds = value.ttlSeconds;
     if (!Number.isInteger(ttlSeconds) || ttlSeconds < 0) {
@@ -101,7 +105,7 @@ function normalizeSourceSchemaRefresh(value, serviceName) {
     }
     return { mode: "ttl", ttlSeconds };
   }
-  throw new Error(`Service "${serviceName}" database.sourceSchema.refresh must be "always" or { ttlSeconds }`);
+  throw new Error(`Service "${serviceName}" database.sourceSchema.refresh must be "auto", "always", or { ttlSeconds }`);
 }
 
 function normalizeSourceSchemaUnavailable(value, serviceName) {
@@ -110,11 +114,3 @@ function normalizeSourceSchemaUnavailable(value, serviceName) {
   }
   throw new Error(`Service "${serviceName}" database.sourceSchema.unavailable must be "auto", "fail", or "warn-cache"`);
 }
-
-function normalizeOptionalString(value, label) {
-  if (value == null) return null;
-  if (typeof value !== "string" || value.trim().length === 0) {
-    throw new Error(`${label} must be a non-empty string`);
-  }
-  return value.trim();
-}

package/lib/config-api/index.d.ts

@@ -15,8 +15,7 @@ export interface DatabaseTemplateOptions {
 }
 
 export interface DatabaseSourceSchemaOptions {
-  cachePath?: string;
-  refresh?: "always" | { ttlSeconds: number };
+  refresh?: "auto" | "always" | { ttlSeconds: number };
   unavailable?: "auto" | "fail" | "warn-cache";
   verify?: boolean;
 }

package/lib/config-api/index.mjs

@@ -57,6 +57,11 @@ function sourceSchemaFromEnv(envName, options = {}) {
   if (typeof envName !== "string" || envName.trim().length === 0) {
     throw new Error("database.schema.fromEnv(...) requires a non-empty env var name");
   }
+  if (Object.prototype.hasOwnProperty.call(options, "cachePath")) {
+    throw new Error(
+      "database.schema.fromEnv(...) no longer accepts cachePath. Testkit now manages commit-scoped source schema caches automatically."
+    );
+  }
   return {
     kind: "env",
     env: envName.trim(),

package/lib/database/fingerprint.mjs

@@ -8,7 +8,7 @@ import { appendSourceSchemaCacheToHash } from "./schema-source.mjs";
 const LOCAL_IMAGE = "pgvector/pgvector:pg16";
 const LOCAL_USER = "testkit";
 
-export async function computeTemplateFingerprint(config) {
+export async function computeTemplateFingerprint(config, options = {}) {
   const hash = crypto.createHash("sha256");
   const db = config.testkit.database;
   hash.update(JSON.stringify({
@@ -25,7 +25,7 @@ export async function computeTemplateFingerprint(config) {
   for (const input of collectTemplateInputs(config.productDir, db.template || {})) {
     appendResolvedInputToHash(hash, config.productDir, input);
   }
-  appendSourceSchemaCacheToHash(hash, config);
+  appendSourceSchemaCacheToHash(hash, config, options.sourceSchemaState || null);
 
   return hash.digest("hex");
 }

package/lib/database/index.mjs

@@ -147,7 +147,7 @@ async function prepareLocalDatabase(config, options = {}) {
 
   await withLock(path.join(lockDir, `template-${serviceName}.lock`), async () => {
     const sourceSchemaState = await prepareSourceSchemaCache(config, options);
-    templateFingerprint = await computeTemplateFingerprint(config);
+    templateFingerprint = await computeTemplateFingerprint(config, { sourceSchemaState });
     templateFingerprint = await ensureTemplateDatabase(
       config,
       infra,
@@ -209,7 +209,7 @@ async function ensureTemplateDatabase(config, infra, cacheDir, templateFingerpri
       await dropDatabaseIfExists(infra, desiredDbName);
       sourceSchemaState = await forceRefreshSourceSchemaCache(config, sourceSchemaState, options);
       refreshedSourceAfterMismatch = true;
-      activeFingerprint = await computeTemplateFingerprint(config);
+      activeFingerprint = await computeTemplateFingerprint(config, { sourceSchemaState });
       continue;
     }
 
@@ -638,8 +638,8 @@ function isUnsupportedForceDropError(error) {
   );
 }
 
-async function computeTemplateFingerprint(config) {
-  return computeTemplateFingerprintModel(config);
+async function computeTemplateFingerprint(config, options = {}) {
+  return computeTemplateFingerprintModel(config, options);
 }
 
 function appendInputToHash(hash, productDir, input) {

package/lib/database/schema-source.mjs

@@ -2,31 +2,54 @@ import fs from "fs";
 import os from "os";
 import path from "path";
 import { execa } from "execa";
-import { resolveServiceCwd } from "../config/paths.mjs";
+import { collectRepoState, summarizeRepoStateForMetadata } from "../repo/state.mjs";
 import { buildExecutionEnv } from "../runner/template.mjs";
 import { dumpPostgresSchemaToFile, captureTemplateSnapshotText, runTemplateStep, sanitizeSnapshotText } from "./template-steps.mjs";
+import { getSourceSchemaRefreshLockPath, withSourceSchemaRefreshLock } from "./source-refresh-lock.mjs";
+import { resolveSourceSchemaDumpUrl } from "./source-url.mjs";
 
 const SOURCE_SCHEMA_DIR = path.join(".testkit", "db");
+const SOURCE_SCHEMA_CACHE_DIR = "source-schemas";
 const SOURCE_SCHEMA_FILE = "source-schema.sql";
 const SOURCE_SCHEMA_META_FILE = "source-schema.meta.json";
+const SOURCE_SCHEMA_INDEX_FILE = "index.json";
+const SOURCE_SCHEMA_MAX_ENTRIES = 20;
 
-export function getSourceSchemaCachePath(config) {
-  const configured = config.testkit.database?.sourceSchema?.cachePath || null;
-  return configured
-    ? resolveServiceCwd(config.productDir, configured)
-    : path.join(config.productDir, SOURCE_SCHEMA_DIR, config.name, SOURCE_SCHEMA_FILE);
+export function getSourceSchemaRootDir(config) {
+  return path.join(config.productDir, SOURCE_SCHEMA_DIR, config.name, SOURCE_SCHEMA_CACHE_DIR);
 }
 
-export function getSourceSchemaMetadataPath(config) {
-  const cachePath = getSourceSchemaCachePath(config);
+export function getSourceSchemaCachePath(config, options = {}) {
+  return resolveSourceSchemaCacheLocation(config, options).cachePath;
+}
+
+export function getSourceSchemaMetadataPath(config, options = {}) {
+  const cachePath = getSourceSchemaCachePath(config, options);
   return path.join(path.dirname(cachePath), SOURCE_SCHEMA_META_FILE);
 }
 
+export function resolveSourceSchemaCacheLocation(config, options = {}) {
+  const repoState = options.repoState || collectRepoState(config.productDir);
+  const rootDir = getSourceSchemaRootDir(config);
+  const cacheDir = path.join(rootDir, ...repoState.cacheKey.split("/").map(sanitizePathSegment));
+  return {
+    rootDir,
+    cacheDir,
+    cachePath: path.join(cacheDir, SOURCE_SCHEMA_FILE),
+    metadataPath: path.join(cacheDir, SOURCE_SCHEMA_META_FILE),
+    indexPath: path.join(rootDir, SOURCE_SCHEMA_INDEX_FILE),
+    cacheKey: repoState.cacheKey,
+    cacheKind: repoState.kind,
+    repoState,
+  };
+}
+
 export function resolveSourceSchemaState(config, options = {}) {
   const sourceSchema = config.testkit.database?.sourceSchema || null;
   if (!sourceSchema) return { active: false };
 
-  const cachePath = getSourceSchemaCachePath(config);
+  const location = resolveSourceSchemaCacheLocation(config, options);
+  const cachePath = location.cachePath;
   const cacheExists = fs.existsSync(cachePath);
   const env = buildExecutionEnv(config, {}, options.env || process.env);
   const envNames = sourceSchema.kind === "env"
@@ -41,12 +64,19 @@ export function resolveSourceSchemaState(config, options = {}) {
   return {
     active: true,
     cachePath,
-    metadataPath: getSourceSchemaMetadataPath(config),
+    metadataPath: location.metadataPath,
+    indexPath: location.indexPath,
+    rootDir: location.rootDir,
+    cacheDir: location.cacheDir,
+    cacheKey: location.cacheKey,
+    cacheKind: location.cacheKind,
+    repoState: location.repoState,
     envName,
     sourceUrl,
     sourceSchema,
     cacheExists,
     refreshed: false,
+    ci: env.CI === "true",
     unavailableMode: resolveUnavailableMode(sourceSchema.unavailable, options.env || process.env),
   };
 }
@@ -57,9 +87,12 @@ export async function prepareSourceSchemaCache(config, options = {}) {
 
   if (state.sourceUrl) {
     if (shouldRefreshSourceSchema(state)) {
-      await refreshSourceSchemaCache(config, state, options);
-      return { ...state, refreshed: true, cacheExists: true };
+      const refreshInfo = await refreshSourceSchemaCache(config, state, options);
+      const refreshedState = { ...state, refreshed: true, cacheExists: true, refreshInfo };
+      updateSourceSchemaIndex(config, refreshedState, { refreshed: true });
+      return refreshedState;
     }
+    updateSourceSchemaIndex(config, state);
     options.setupRegistry?.recordCached({
       config,
       stage: "source-schema",
@@ -70,6 +103,7 @@ export async function prepareSourceSchemaCache(config, options = {}) {
   }
 
   if (state.cacheExists && state.unavailableMode === "warn-cache") {
+    updateSourceSchemaIndex(config, state);
     options.setupRegistry?.recordCached({
       config,
       stage: "source-schema",
@@ -93,8 +127,10 @@ export async function forceRefreshSourceSchemaCache(config, previousState, optio
     const envLabel = previousState?.envName || previousState?.sourceSchema?.env || "source schema env";
     throw new Error(`Cannot refresh source schema for service "${config.name}" because ${envLabel} is unavailable.`);
   }
-  await refreshSourceSchemaCache(config, state, options);
-  return { ...state, refreshed: true, cacheExists: true };
+  const refreshInfo = await refreshSourceSchemaCache(config, state, options);
+  const refreshedState = { ...state, refreshed: true, cacheExists: true, refreshInfo };
+  updateSourceSchemaIndex(config, refreshedState, { refreshed: true });
+  return refreshedState;
 }
 
 export async function applySourceSchemaCache(config, databaseUrl, state, options = {}) {
@@ -156,10 +192,12 @@ export function createSourceSchemaMismatchError(config, state, verification) {
   return new Error(parts.join("\n"));
 }
 
-export function appendSourceSchemaCacheToHash(hash, config) {
+export function appendSourceSchemaCacheToHash(hash, config, state = null) {
   const sourceSchema = config.testkit.database?.sourceSchema || null;
   if (!sourceSchema) return;
-  const cachePath = getSourceSchemaCachePath(config);
+  const cachePath = state?.cachePath || getSourceSchemaCachePath(config);
+  const cacheKey = state?.cacheKey || path.relative(getSourceSchemaRootDir(config), path.dirname(cachePath));
+  hash.update(`source-schema-key:${cacheKey}`);
   hash.update(`source-schema-cache:${path.relative(config.productDir, cachePath)}`);
   if (!fs.existsSync(cachePath)) {
     hash.update(":missing");
@@ -171,6 +209,7 @@ export function appendSourceSchemaCacheToHash(hash, config) {
 }
 
 async function refreshSourceSchemaCache(config, state, options = {}) {
+  let refreshInfo = null;
   const operation = options.setupRegistry?.start({
     config,
     stage: "source-schema:refresh",
@@ -178,16 +217,31 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
     summary: `source schema refresh: ${path.relative(config.productDir, state.cachePath)}`,
   });
   try {
-    await writeSourceSchemaCacheFromUrl(config, state.sourceUrl, state.cachePath, {
-      reporter: options.reporter || null,
-      logRecord: operation?._logRecord || null,
-    });
-    writeSourceSchemaMetadata(state.metadataPath, {
-      refreshedAt: new Date().toISOString(),
-      serviceName: config.name,
-      envName: state.envName,
-      cachePath: path.relative(config.productDir, state.cachePath),
-    });
+    refreshInfo = await withSourceSchemaRefreshLock(
+      getSourceSchemaRefreshLockPath(state.cachePath),
+      async ({ waited, requestedAt }) => {
+        const cachedAfterWaiting = readRecentSourceSchemaMetadata(state, requestedAt);
+        if (cachedAfterWaiting) {
+          return {
+            reusedExistingRefresh: true,
+            waitedForLock: waited,
+            metadata: cachedAfterWaiting,
+          };
+        }
+        const result = await writeSourceSchemaCacheFromUrl(config, state.sourceUrl, state.cachePath, {
+          reporter: options.reporter || null,
+          logRecord: operation?._logRecord || null,
+          env: options.env || process.env,
+        });
+        const metadata = buildSourceSchemaMetadata(config, state, result);
+        writeSourceSchemaMetadata(state.metadataPath, metadata);
+        return {
+          reusedExistingRefresh: false,
+          waitedForLock: waited,
+          metadata,
+        };
+      }
+    );
     const finished = operation
       ? options.setupRegistry.finish(operation, {
           status: "passed",
@@ -195,6 +249,7 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
         })
       : null;
     if (finished) options.reporter?.setupOperationFinished?.(finished);
+    return refreshInfo;
   } catch (error) {
     const finished = operation
       ? options.setupRegistry.finish(operation, {
@@ -209,23 +264,64 @@ async function refreshSourceSchemaCache(config, state, options = {}) {
 }
 
 async function writeSourceSchemaCacheFromUrl(config, sourceUrl, cachePath, options = {}) {
+  const resolution = resolveSourceSchemaDumpUrl(sourceUrl);
   fs.mkdirSync(path.dirname(cachePath), { recursive: true });
   const tempDir = fs.mkdtempSync(path.join(path.dirname(cachePath), ".source-schema-"));
   const tempPath = path.join(tempDir, path.basename(cachePath));
   try {
-    await dumpPostgresSchemaToFile(config, tempPath, sourceUrl, options);
+    await dumpPostgresSchemaToFile(config, tempPath, resolution.dumpUrl, {
+      ...options,
+      pgApplicationName: sourceSchemaPgApplicationName(config.name),
+    });
     fs.renameSync(tempPath, cachePath);
+    return {
+      resolution,
+      pgDump: {
+        args: ["--schema-only", "--no-owner", "--no-privileges"],
+        applicationName: sourceSchemaPgApplicationName(config.name),
+      },
+    };
   } finally {
     fs.rmSync(tempDir, { recursive: true, force: true });
   }
 }
 
+function buildSourceSchemaMetadata(config, state, result) {
+  return {
+    refreshedAt: new Date().toISOString(),
+    serviceName: config.name,
+    envName: state.envName,
+    cacheKey: state.cacheKey,
+    cacheKind: state.cacheKind,
+    cachePath: path.relative(config.productDir, state.cachePath),
+    repo: summarizeRepoStateForMetadata(state.repoState),
+    sourceUrl: result.resolution.metadata,
+    pgDump: result.pgDump,
+  };
+}
+
+function readRecentSourceSchemaMetadata(state, requestedAt) {
+  if (!fs.existsSync(state.cachePath)) return null;
+  const metadata = readJson(state.metadataPath);
+  const refreshedAt = metadata?.refreshedAt ? Date.parse(metadata.refreshedAt) : 0;
+  if (!Number.isFinite(refreshedAt) || refreshedAt < requestedAt) return null;
+  return metadata;
+}
+
+function sourceSchemaPgApplicationName(serviceName) {
+  const suffix = String(serviceName).replace(/[^a-zA-Z0-9._:-]+/g, "-").slice(0, 24) || "service";
+  return `testkit:schema-source:${suffix}`;
+}
+
 function readSourceSchemaCacheText(cachePath) {
   return sanitizeSnapshotText(fs.readFileSync(cachePath, "utf8"));
 }
 
 function shouldRefreshSourceSchema(state) {
   if (!state.cacheExists) return true;
+  if (state.sourceSchema.refresh?.mode === "auto") {
+    return state.ci;
+  }
   if (state.sourceSchema.refresh?.mode === "ttl") {
     const meta = readJson(state.metadataPath);
     const refreshedAt = meta?.refreshedAt ? Date.parse(meta.refreshedAt) : 0;
@@ -235,11 +331,62 @@ function shouldRefreshSourceSchema(state) {
   return true;
 }
 
+function updateSourceSchemaIndex(config, state, options = {}) {
+  if (!state?.active || !state.indexPath) return;
+  const now = new Date().toISOString();
+  const index = readJson(state.indexPath) || { version: 1, entries: [] };
+  const entries = Array.isArray(index.entries) ? index.entries.filter((entry) => entry?.cacheKey !== state.cacheKey) : [];
+  const existingMeta = readJson(state.metadataPath) || {};
+  entries.push({
+    cacheKey: state.cacheKey,
+    kind: state.cacheKind,
+    commitSha: state.repoState?.commitSha || null,
+    branch: state.repoState?.branch || null,
+    detached: Boolean(state.repoState?.detached),
+    dirty: Boolean(state.repoState?.dirty),
+    dirtyFingerprint: state.repoState?.dirtyFingerprint || null,
+    contentFingerprint: state.repoState?.contentFingerprint || null,
+    remoteUrl: state.repoState?.remoteUrl || null,
+    repoSlug: state.repoState?.repoSlug || null,
+    cachePath: path.relative(config.productDir, state.cachePath),
+    refreshedAt: options.refreshed ? now : existingMeta.refreshedAt || null,
+    lastUsedAt: now,
+  });
+  const prunedEntries = pruneSourceSchemaEntries(config, state, entries);
+  writeJson(state.indexPath, { version: 1, entries: prunedEntries });
+}
+
+function pruneSourceSchemaEntries(config, currentState, entries) {
+  if (entries.length <= SOURCE_SCHEMA_MAX_ENTRIES) return entries;
+  const sorted = [...entries].sort((a, b) => Date.parse(b.lastUsedAt || 0) - Date.parse(a.lastUsedAt || 0));
+  const keep = new Set(sorted.slice(0, SOURCE_SCHEMA_MAX_ENTRIES).map((entry) => entry.cacheKey));
+  keep.add(currentState.cacheKey);
+  for (const entry of entries) {
+    if (keep.has(entry.cacheKey)) continue;
+    const cachePath = entry.cachePath ? path.join(config.productDir, entry.cachePath) : null;
+    const resolvedCachePath = cachePath ? path.resolve(cachePath) : null;
+    const resolvedRoot = path.resolve(currentState.rootDir);
+    if (
+      !resolvedCachePath ||
+      (resolvedCachePath !== resolvedRoot && !resolvedCachePath.startsWith(`${resolvedRoot}${path.sep}`))
+    ) {
+      continue;
+    }
+    fs.rmSync(path.dirname(cachePath), { recursive: true, force: true });
+  }
+  return entries.filter((entry) => keep.has(entry.cacheKey));
+}
+
 function writeSourceSchemaMetadata(metadataPath, metadata) {
   fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
   fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
 }
 
+function writeJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+
 function readJson(filePath) {
   if (!filePath || !fs.existsSync(filePath)) return null;
   try {