@elench/testkit 0.1.65 → 0.1.66

package/lib/runner/run-finalization.mjs

@@ -0,0 +1,132 @@
+import { buildRunArtifact, buildStatusArtifact } from "./reporting.mjs";
+import { applyKnownFailureIssueValidationToArtifacts, applyKnownFailuresToArtifacts } from "./triage.mjs";
+import { writeRunArtifact, writeStatusArtifact } from "./artifacts.mjs";
+import { summarizeDbBackend } from "./results.mjs";
+import { formatError } from "./formatting.mjs";
+import { uploadTelemetryArtifact } from "../telemetry/index.mjs";
+import { loadHistory, saveHistory, updateHistoryFromRunArtifact } from "../history/index.mjs";
+import { shouldFailKnownFailureIssueValidation, validateKnownFailureIssues } from "../known-failures/github.mjs";
+
+export async function finalizeRunArtifacts({
+  productDir,
+  results,
+  startedAt,
+  finishedAt,
+  execution,
+  workerCount,
+  runtimeInstanceCount,
+  runtimeStats,
+  selection,
+  metadata,
+  logRegistry,
+  setupRegistry,
+  knownFailures,
+  issueValidationConfig,
+  telemetry,
+  reporter,
+  writeStatus,
+}) {
+  const runArtifact = buildRunArtifact({
+    productDir,
+    results,
+    startedAt,
+    finishedAt,
+    execution,
+    workerCount,
+    runtimeInstanceCount,
+    runtimeStats,
+    typeValues: selection.typeValues,
+    suiteSelectors: selection.suiteSelectors,
+    fileNames: selection.fileNames,
+    shard: selection.shard,
+    serviceFilter: selection.serviceFilter,
+    scenarioSeed: selection.scenarioSeed,
+    metadata,
+    summarizeDbBackend,
+    serviceLogs: logRegistry.listServiceLogs(),
+    setupLogs: logRegistry.listSetupLogs(),
+    setupOperations: setupRegistry.listOperations(),
+  });
+  const statusArtifact = writeStatus
+    ? buildStatusArtifact({
+        productDir,
+        results,
+        typeValues: selection.typeValues,
+        suiteSelectors: selection.suiteSelectors,
+        fileNames: selection.fileNames,
+        shard: selection.shard,
+        serviceFilter: selection.serviceFilter,
+        scenarioSeed: selection.scenarioSeed,
+        metadata,
+      })
+    : null;
+  const enrichedArtifacts = applyKnownFailuresToArtifacts(runArtifact, statusArtifact, knownFailures);
+  const knownFailureIssueValidation = await validateKnownFailureIssues({
+    productDir,
+    document: knownFailures,
+    runArtifact: enrichedArtifacts.runArtifact,
+    statusArtifact: enrichedArtifacts.statusArtifact,
+    config: issueValidationConfig,
+    gitMetadata: metadata.git,
+  });
+  applyKnownFailureIssueValidationToArtifacts(
+    enrichedArtifacts.runArtifact,
+    enrichedArtifacts.statusArtifact,
+    knownFailureIssueValidation
+  );
+  attachKnownFailureIssueValidation(
+    enrichedArtifacts.runArtifact,
+    enrichedArtifacts.statusArtifact,
+    knownFailureIssueValidation
+  );
+
+  writeRunArtifact(productDir, enrichedArtifacts.runArtifact);
+  if (writeStatus) {
+    writeStatusArtifact(productDir, enrichedArtifacts.statusArtifact);
+  }
+  const nextHistory = updateHistoryFromRunArtifact(
+    loadHistory(productDir),
+    enrichedArtifacts.runArtifact,
+    enrichedArtifacts.runArtifact.generatedAt
+  );
+  saveHistory(productDir, nextHistory);
+
+  reporter?.runSummary?.(results, finishedAt - startedAt, knownFailureIssueValidation);
+  await reportTelemetry(telemetry, enrichedArtifacts.runArtifact, reporter);
+
+  return {
+    runArtifact: enrichedArtifacts.runArtifact,
+    statusArtifact: enrichedArtifacts.statusArtifact,
+    knownFailureIssueValidation,
+    shouldFailIssueValidation: shouldFailKnownFailureIssueValidation(knownFailureIssueValidation),
+  };
+}
+
+async function reportTelemetry(telemetry, artifact, reporter = null) {
+  if (!telemetry?.enabled) return;
+
+  try {
+    const outcome = await uploadTelemetryArtifact(telemetry, artifact);
+    if (outcome?.ok) {
+      reporter?.telemetry?.("Telemetry: uploaded run artifact");
+      return;
+    }
+    if (outcome?.reason === "missing-token") {
+      reporter?.telemetry?.(
+        `Telemetry: skipped upload because ${telemetry.tokenEnv || "configured token env"} is not set`
+      );
+      return;
+    }
+    if (outcome?.reason && !outcome.skipped) return;
+  } catch (error) {
+    reporter?.telemetry?.(`Telemetry: upload failed (${formatError(error)})`);
+  }
+}
+
+function attachKnownFailureIssueValidation(runArtifact, statusArtifact, validation) {
+  if (!validation) return;
+  runArtifact.knownFailuresIssueValidation = validation;
+  if (statusArtifact) {
+    statusArtifact.knownFailuresIssueValidation = validation;
+  }
+}

package/lib/runner/run-guards.mjs

@@ -0,0 +1,45 @@
+import { collectSuites } from "./planning.mjs";
+import { findUnmatchedRequestedFiles, isFullRunSelection } from "./selection.mjs";
+
+export function ensureRequestedFilesMatch(configs, typeValues, suiteSelectors, requestedFiles = []) {
+  if (requestedFiles.length === 0) return;
+  const unmatchedFiles = findUnmatchedRequestedFiles(
+    configs,
+    typeValues,
+    suiteSelectors,
+    requestedFiles,
+    collectSuites,
+    normalizePathSeparators
+  );
+  if (unmatchedFiles.length === 0) return;
+
+  throw new Error(
+    `Requested file${unmatchedFiles.length === 1 ? "" : "s"} did not match any selected suites:\n` +
+      unmatchedFiles.map((file) => `- ${file}`).join("\n")
+  );
+}
+
+export function ensureStatusWriteAllowed(opts, typeValues, suiteSelectors, requestedFiles = []) {
+  if (
+    !opts.writeStatus ||
+    opts.allowPartialStatus ||
+    isFullRunSelection(
+      typeValues,
+      suiteSelectors,
+      requestedFiles,
+      opts.shard || null,
+      opts.serviceFilter || null
+    )
+  ) {
+    return;
+  }
+
+  throw new Error(
+    "Refusing to overwrite testkit.status.json from a filtered run. " +
+      "Run the full suite with --write-status, or pass --allow-partial-status to opt in."
+  );
+}
+
+function normalizePathSeparators(filePath) {
+  return filePath.split("\\").join("/");
+}

package/lib/runner/runtime-preparation.mjs

@@ -1,7 +1,7 @@
 import crypto from "crypto";
 import fs from "fs";
 import path from "path";
-import { resolveServiceCwd } from "../config/index.mjs";
+import { resolveServiceCwd } from "../config/paths.mjs";
 import { appendFileToHash, appendInputToHash } from "../database/fingerprint.mjs";
 import { announceResolvedToolchain, resolveConfiguredToolchain } from "../toolchains/index.mjs";
 import { readDatabaseUrl } from "./state-io.mjs";

package/lib/runner/services.mjs

@@ -1,9 +1,10 @@
-import { resolveServiceCwd } from "../config/index.mjs";
+import { resolveServiceCwd } from "../config/paths.mjs";
 import {
   announceResolvedToolchain,
   applyToolchainEnv,
   resolveConfiguredToolchain,
 } from "../toolchains/index.mjs";
+import { registerManagedService } from "./managed-processes.mjs";
 import { buildExecutionEnv, numericPortFromUrl } from "./template.mjs";
 import { DEFAULT_READY_TIMEOUT_MS, assertLocalServicePortsAvailable, isPortInUse, waitForReady } from "./readiness.mjs";
 import { captureOutput, killChildProcess, startDetachedCommand, stopChildProcess, sleep } from "./processes.mjs";
@@ -70,9 +71,7 @@ export async function startLocalService(config, lifecycle, options = {}) {
       },
     }),
   ];
-  lifecycle.registerService(config, child, cwd, () => {
-    killChildProcess(child, "SIGTERM");
-  });
+  registerManagedService(lifecycle, config, child, cwd, "SIGTERM");
 
   const readyTimeoutMs = config.testkit.local.readyTimeoutMs || DEFAULT_READY_TIMEOUT_MS;
 

package/lib/runner/template-steps.mjs

@@ -4,7 +4,14 @@ import path from "path";
 import { build } from "esbuild";
 import { execa, execaCommand } from "execa";
 import { fileURLToPath } from "url";
-import { resolveServiceCwd } from "../config/index.mjs";
+import {
+  collectConfiguredInputs,
+  parseModuleSpecifier,
+  resolveConfiguredCwd,
+  resolveConfiguredPath,
+  summarizeConfiguredStep,
+} from "../shared/configured-steps.mjs";
+export { collectConfiguredInputs, parseModuleSpecifier, resolveConfiguredCwd, resolveConfiguredPath } from "../shared/configured-steps.mjs";
 import {
   announceResolvedToolchain,
   applyToolchainEnv,
@@ -72,35 +79,6 @@ export async function runConfiguredSteps({
   }
 }
 
-export function collectConfiguredInputs(productDir, { inputs = [], steps = [] } = {}) {
-  const collected = new Set();
-  for (const input of inputs) {
-    collected.add(resolveConfiguredPath(productDir, null, input));
-  }
-  for (const step of steps) {
-    if (step.kind === "sql-file") {
-      collected.add(resolveConfiguredPath(productDir, step.cwd, step.path));
-    }
-    if (step.kind === "module") {
-      collected.add(
-        resolveConfiguredPath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath)
-      );
-    }
-    for (const input of step.inputs || []) {
-      collected.add(resolveConfiguredPath(productDir, step.cwd, input));
-    }
-  }
-  return [...collected].sort();
-}
-
-export function resolveConfiguredCwd(productDir, stepCwd) {
-  return resolveServiceCwd(productDir, stepCwd || ".");
-}
-
-export function resolveConfiguredPath(productDir, stepCwd, targetPath) {
-  return path.resolve(resolveConfiguredCwd(productDir, stepCwd), targetPath);
-}
-
 async function runConfiguredStep(config, step, env, resolvedToolchain, options = {}) {
   const runtimeEnv = applyToolchainEnv(env, resolvedToolchain);
   const cwd = resolveConfiguredCwd(config.productDir, step.cwd);
@@ -253,21 +231,6 @@ function resolvePackageSubpath(specifier) {
   throw new Error(`Unsupported @elench/testkit import "${specifier}" while loading template step`);
 }
 
-function parseModuleSpecifier(specifier) {
-  const [modulePath, exportName] = String(specifier).split("#", 2);
-  return {
-    modulePath,
-    exportName: exportName || "default",
-  };
-}
-
-function summarizeConfiguredStep(step) {
-  if (step.kind === "command") return `command: ${String(step.cmd).trim()}`;
-  if (step.kind === "sql-file") return `sql: ${step.path}`;
-  if (step.kind === "module") return `module: ${step.specifier}`;
-  return step.kind;
-}
-
 async function awaitCapturedProcess(child, { livePrefix = "", liveWriter = null, logRecord = null } = {}) {
   const drains = [
     captureProcessOutput(child.stdout, "stdout", livePrefix, liveWriter, logRecord),

package/lib/runner/template.mjs

@@ -1,4 +1,5 @@
 import path from "path";
+import { finalizeConfiguredInputs, finalizeConfiguredSteps } from "../shared/configured-steps.mjs";
 import { readDatabaseInfo } from "./state-io.mjs";
 
 const PORT_STRIDE = 100;
@@ -183,22 +184,11 @@ function finalizeDatabaseTemplate(template, context) {
     };
   }
 
-  const finalizeStep = (step) => ({
-    ...step,
-    ...(typeof step.cmd === "string" ? { cmd: finalizeString(step.cmd, context) } : {}),
-    ...(typeof step.cwd === "string" ? { cwd: finalizeString(step.cwd, context) } : {}),
-    ...(typeof step.path === "string" ? { path: finalizeString(step.path, context) } : {}),
-    ...(typeof step.specifier === "string"
-      ? { specifier: finalizeString(step.specifier, context) }
-      : {}),
-    inputs: (step.inputs || []).map((input) => finalizeString(input, context)),
-  });
-
   return {
-    inputs: (template.inputs || []).map((input) => finalizeString(input, context)),
-    migrate: (template.migrate || []).map(finalizeStep),
-    seed: (template.seed || []).map(finalizeStep),
-    verify: (template.verify || []).map(finalizeStep),
+    inputs: finalizeConfiguredInputs(template.inputs || [], (value) => finalizeString(value, context)),
+    migrate: finalizeConfiguredSteps(template.migrate || [], (value) => finalizeString(value, context)),
+    seed: finalizeConfiguredSteps(template.seed || [], (value) => finalizeString(value, context)),
+    verify: finalizeConfiguredSteps(template.verify || [], (value) => finalizeString(value, context)),
   };
 }
 
@@ -356,20 +346,9 @@ function finalizeRuntimePrepare(prepare, context) {
     };
   }
 
-  const finalizeStep = (step) => ({
-    ...step,
-    ...(typeof step.cmd === "string" ? { cmd: finalizeString(step.cmd, context) } : {}),
-    ...(typeof step.cwd === "string" ? { cwd: finalizeString(step.cwd, context) } : {}),
-    ...(typeof step.path === "string" ? { path: finalizeString(step.path, context) } : {}),
-    ...(typeof step.specifier === "string"
-      ? { specifier: finalizeString(step.specifier, context) }
-      : {}),
-    inputs: (step.inputs || []).map((input) => finalizeString(input, context)),
-  });
-
   return {
-    inputs: (prepare.inputs || []).map((input) => finalizeString(input, context)),
-    steps: (prepare.steps || []).map(finalizeStep),
+    inputs: finalizeConfiguredInputs(prepare.inputs || [], (value) => finalizeString(value, context)),
+    steps: finalizeConfiguredSteps(prepare.steps || [], (value) => finalizeString(value, context)),
   };
 }
 

package/lib/shared/configured-steps.mjs

@@ -0,0 +1,178 @@
+import fs from "fs";
+import path from "path";
+
+export function normalizeOptionalString(value) {
+  if (typeof value !== "string") return null;
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+}
+
+export function normalizeConfiguredInputs(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label}.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(`${label}.inputs[${index}] must be a non-empty string`);
+    }
+    return normalized;
+  });
+}
+
+export function normalizeConfiguredStepInputs(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label}.inputs must be an array`);
+  }
+
+  return value.map((entry, index) => {
+    const normalized = normalizeOptionalString(entry);
+    if (!normalized) {
+      throw new Error(`${label}.inputs[${index}] must be a non-empty string`);
+    }
+    return normalized;
+  });
+}
+
+export function normalizeConfiguredSteps(value, label) {
+  if (value == null) return [];
+  if (!Array.isArray(value)) {
+    throw new Error(`${label} must be an array`);
+  }
+
+  return value.map((step, index) => normalizeConfiguredStep(step, `${label}[${index}]`));
+}
+
+export function normalizeConfiguredStep(step, label) {
+  if (!step || typeof step !== "object") {
+    throw new Error(`${label} must be an object`);
+  }
+
+  const kind = normalizeOptionalString(step.kind);
+  if (kind === "command") {
+    const cmd = normalizeOptionalString(step.cmd);
+    if (!cmd) throw new Error(`${label}.cmd must be a non-empty string`);
+    return {
+      kind,
+      cmd,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeConfiguredStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "sql-file") {
+    const filePath = normalizeOptionalString(step.path);
+    if (!filePath) throw new Error(`${label}.path must be a non-empty string`);
+    return {
+      kind,
+      path: filePath,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeConfiguredStepInputs(step.inputs, label),
+    };
+  }
+  if (kind === "module") {
+    const specifier = normalizeOptionalString(step.specifier);
+    if (!specifier) throw new Error(`${label}.specifier must be a non-empty string`);
+    return {
+      kind,
+      specifier,
+      cwd: normalizeOptionalString(step.cwd),
+      inputs: normalizeConfiguredStepInputs(step.inputs, label),
+    };
+  }
+
+  throw new Error(`${label}.kind must be one of: command, sql-file, module`);
+}
+
+export function parseModuleSpecifier(specifier) {
+  const [modulePath, exportName] = String(specifier).split("#", 2);
+  return {
+    modulePath,
+    exportName: exportName || "default",
+  };
+}
+
+export function resolveConfiguredCwd(productDir, stepCwd) {
+  return path.resolve(productDir, stepCwd || ".");
+}
+
+export function resolveConfiguredPath(productDir, stepCwd, targetPath) {
+  return path.resolve(resolveConfiguredCwd(productDir, stepCwd), targetPath);
+}
+
+export function collectConfiguredInputs(productDir, { inputs = [], steps = [] } = {}) {
+  const collected = new Set();
+  for (const input of inputs) {
+    collected.add(resolveConfiguredPath(productDir, null, input));
+  }
+  for (const step of steps) {
+    if (step.kind === "sql-file") {
+      collected.add(resolveConfiguredPath(productDir, step.cwd, step.path));
+    }
+    if (step.kind === "module") {
+      collected.add(resolveConfiguredPath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath));
+    }
+    for (const input of step.inputs || []) {
+      collected.add(resolveConfiguredPath(productDir, step.cwd, input));
+    }
+  }
+  return [...collected].sort();
+}
+
+export function summarizeConfiguredStep(step) {
+  if (step.kind === "command") return `command: ${String(step.cmd).trim()}`;
+  if (step.kind === "sql-file") return `sql: ${step.path}`;
+  if (step.kind === "module") return `module: ${step.specifier}`;
+  return step.kind;
+}
+
+export function finalizeConfiguredInputs(inputs = [], transform) {
+  return inputs.map((input) => transform(input));
+}
+
+export function finalizeConfiguredStep(step, transform) {
+  return {
+    ...step,
+    ...(typeof step.cmd === "string" ? { cmd: transform(step.cmd) } : {}),
+    ...(typeof step.cwd === "string" ? { cwd: transform(step.cwd) } : {}),
+    ...(typeof step.path === "string" ? { path: transform(step.path) } : {}),
+    ...(typeof step.specifier === "string" ? { specifier: transform(step.specifier) } : {}),
+    inputs: finalizeConfiguredInputs(step.inputs || [], transform),
+  };
+}
+
+export function finalizeConfiguredSteps(steps = [], transform) {
+  return steps.map((step) => finalizeConfiguredStep(step, transform));
+}
+
+export function validateConfiguredCollection({ productDir, label, inputs = [], steps = [] }) {
+  for (const input of inputs) {
+    ensureExistingPath(resolveConfiguredPath(productDir, null, input), `${label} input`);
+  }
+
+  for (const step of steps) {
+    if (step.cwd) {
+      ensureExistingPath(resolveConfiguredCwd(productDir, step.cwd), `${label} step cwd`);
+    }
+    if (step.kind === "sql-file") {
+      ensureExistingPath(resolveConfiguredPath(productDir, step.cwd, step.path), `${label} sql file`);
+    }
+    if (step.kind === "module") {
+      ensureExistingPath(
+        resolveConfiguredPath(productDir, step.cwd, parseModuleSpecifier(step.specifier).modulePath),
+        `${label} module`
+      );
+    }
+    for (const input of step.inputs || []) {
+      ensureExistingPath(resolveConfiguredPath(productDir, step.cwd, input), `${label} step input`);
+    }
+  }
+}
+
+function ensureExistingPath(absolutePath, label) {
+  if (!fs.existsSync(absolutePath)) {
+    throw new Error(`${label} does not exist: ${absolutePath}`);
+  }
+}

package/lib/shared/configured-steps.test.mjs

@@ -0,0 +1,73 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  collectConfiguredInputs,
+  finalizeConfiguredStep,
+  normalizeConfiguredStep,
+  parseModuleSpecifier,
+  validateConfiguredCollection,
+} from "./configured-steps.mjs";
+
+const tempDirs = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("shared configured steps", () => {
+  it("normalizes and finalizes configured steps", () => {
+    const normalized = normalizeConfiguredStep(
+      { kind: "module", specifier: "./seed.mjs#run", cwd: "db", inputs: ["schema.sql"] },
+      'Service "api" database.template.seed[0]'
+    );
+
+    expect(normalized).toEqual({
+      kind: "module",
+      specifier: "./seed.mjs#run",
+      cwd: "db",
+      inputs: ["schema.sql"],
+    });
+    expect(parseModuleSpecifier(normalized.specifier)).toEqual({
+      modulePath: "./seed.mjs",
+      exportName: "run",
+    });
+    expect(finalizeConfiguredStep(normalized, (value) => value.toUpperCase())).toEqual({
+      kind: "module",
+      specifier: "./SEED.MJS#RUN",
+      cwd: "DB",
+      inputs: ["SCHEMA.SQL"],
+    });
+  });
+
+  it("collects and validates configured input paths", () => {
+    const productDir = fs.mkdtempSync(path.join(os.tmpdir(), "testkit-configured-steps-"));
+    tempDirs.push(productDir);
+    fs.mkdirSync(path.join(productDir, "db"), { recursive: true });
+    fs.writeFileSync(path.join(productDir, "db", "schema.sql"), "-- schema\n");
+    fs.writeFileSync(path.join(productDir, "db", "seed.mjs"), "export default async function run() {}\n");
+
+    const collection = {
+      inputs: ["db/schema.sql"],
+      steps: [
+        { kind: "sql-file", path: "schema.sql", cwd: "db", inputs: [] },
+        { kind: "module", specifier: "./seed.mjs#run", cwd: "db", inputs: [] },
+      ],
+    };
+
+    expect(collectConfiguredInputs(productDir, collection)).toEqual([
+      path.join(productDir, "db", "schema.sql"),
+      path.join(productDir, "db", "seed.mjs"),
+    ]);
+    expect(() =>
+      validateConfiguredCollection({
+        productDir,
+        label: 'Service "api" runtime.prepare',
+        ...collection,
+      })
+    ).not.toThrow();
+  });
+});

package/lib/shared/execution-schema.mjs

@@ -0,0 +1,74 @@
+import {
+  DEFAULT_FILE_TIMEOUT_SECONDS,
+  normalizeFileTimeoutSeconds,
+  parseFileTimeoutOption,
+} from "./file-timeout.mjs";
+
+export const DATABASE_BINDINGS = new Set(["shared", "per-runtime"]);
+
+export { DEFAULT_FILE_TIMEOUT_SECONDS, parseFileTimeoutOption };
+
+export function parseWorkersOption(value) {
+  return parsePositiveInteger(value, "--workers");
+}
+
+export function parseRuntimeInstancesOption(value, label = "runtime.instances") {
+  return parsePositiveInteger(value, label);
+}
+
+export function normalizeRuntimeInstances(value, label = "runtime.instances") {
+  return normalizePositiveInteger(value, label);
+}
+
+export function parseRuntimeMaxConcurrentTasksOption(value, label = "runtime.maxConcurrentTasks") {
+  return parsePositiveInteger(value, label);
+}
+
+export function normalizeRuntimeMaxConcurrentTasks(value, label = "runtime.maxConcurrentTasks") {
+  if (value === undefined || value === null) {
+    return Number.POSITIVE_INFINITY;
+  }
+  return normalizePositiveInteger(value, label);
+}
+
+export function normalizeDatabaseBinding(value, label = "database.binding") {
+  const normalized = String(value || "").trim();
+  if (!DATABASE_BINDINGS.has(normalized)) {
+    throw new Error(`Invalid ${label} value "${value}". Expected one of: shared, per-runtime.`);
+  }
+  return normalized;
+}
+
+export function resolveExecutionConfig({ cli = {}, repo = {} } = {}) {
+  return normalizeExecutionConfig({
+    workers: cli.workers ?? repo.workers ?? 1,
+    fileTimeoutSeconds: cli.fileTimeoutSeconds ?? repo.fileTimeoutSeconds ?? DEFAULT_FILE_TIMEOUT_SECONDS,
+  });
+}
+
+export function normalizeExecutionConfig(input = {}) {
+  return {
+    workers: normalizePositiveInteger(input.workers ?? 1, "execution.workers"),
+    fileTimeoutSeconds: normalizeFileTimeoutSeconds(input.fileTimeoutSeconds ?? DEFAULT_FILE_TIMEOUT_SECONDS),
+  };
+}
+
+export function buildRuntimeIds(count) {
+  return Array.from({ length: count }, (_unused, index) => `runtime-${index + 1}`);
+}
+
+function parsePositiveInteger(value, label) {
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid ${label} value "${value}". Expected a positive integer.`);
+  }
+  return parsed;
+}
+
+function normalizePositiveInteger(value, label) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return parsed;
+}

package/lib/shared/execution-schema.test.mjs

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import {
+  normalizeDatabaseBinding,
+  normalizeExecutionConfig,
+  normalizeRuntimeMaxConcurrentTasks,
+  resolveExecutionConfig,
+} from "./execution-schema.mjs";
+
+describe("shared execution schema", () => {
+  it("normalizes execution config and repo/cli overrides", () => {
+    expect(normalizeExecutionConfig({ workers: 2, fileTimeoutSeconds: 30 })).toEqual({
+      workers: 2,
+      fileTimeoutSeconds: 30,
+    });
+    expect(resolveExecutionConfig({ cli: { workers: 3 }, repo: { workers: 2, fileTimeoutSeconds: 45 } })).toEqual({
+      workers: 3,
+      fileTimeoutSeconds: 45,
+    });
+  });
+
+  it("validates runtime concurrency and database binding", () => {
+    expect(normalizeRuntimeMaxConcurrentTasks(undefined)).toBe(Number.POSITIVE_INFINITY);
+    expect(normalizeDatabaseBinding("shared")).toBe("shared");
+    expect(() => normalizeDatabaseBinding("legacy")).toThrow('Invalid database.binding value "legacy"');
+  });
+});