@bjoernrochel/sevro 0.1.0-rc.1

package/src/results.ts

@@ -0,0 +1,160 @@
+export type ExecutionStatus = "completed" | "failed" | "cancelled" | "not_run";
+export type GradingStatus =
+  "completed" | "error" | "unavailable" | "not_requested";
+export type TaskVerdict = "passed" | "failed" | "not_assessed";
+
+export interface CheckOutcome {
+  id: string;
+  grader: string;
+  status: "passed" | "failed" | "unavailable";
+  detail?: string;
+  evidenceRefs?: string[];
+}
+
+export interface Assessment {
+  execution: { status: ExecutionStatus };
+  grading: { status: GradingStatus };
+  task: { verdict: TaskVerdict };
+}
+
+export interface TrialInput {
+  execution: ExecutionStatus;
+  declaredChecks: string[];
+  checks: CheckOutcome[];
+  graderError?: boolean;
+  requiredEvidenceUnavailable?: boolean;
+}
+
+/** Reduce one trial without treating process completion as task success. */
+export function assessTrial(input: TrialInput): Assessment {
+  const declared = new Set(input.declaredChecks);
+  if (declared.size !== input.declaredChecks.length || declared.has(""))
+    throw new Error("check declarations must have unique nonempty IDs");
+  const seen = new Set<string>();
+  for (const check of input.checks) {
+    if (!declared.has(check.id) || seen.has(check.id))
+      throw new Error(`unexpected or duplicate check result: ${check.id}`);
+    seen.add(check.id);
+  }
+
+  const grading: GradingStatus = input.graderError
+    ? "error"
+    : input.execution !== "completed"
+      ? "not_requested"
+      : input.requiredEvidenceUnavailable ||
+          input.checks.some((check) => check.status === "unavailable") ||
+          seen.size !== declared.size
+        ? "unavailable"
+        : declared.size === 0
+          ? "not_requested"
+          : "completed";
+  const task: TaskVerdict =
+    input.execution === "completed" &&
+    input.checks.some((check) => check.status === "failed")
+      ? "failed"
+      : input.execution === "completed" && grading === "completed"
+        ? "passed"
+        : "not_assessed";
+  return {
+    execution: { status: input.execution },
+    grading: { status: grading },
+    task: { verdict: task },
+  };
+}
+
+/** Apply an explicitly selected policy only to a fully assessed trial. */
+export function applyTaskVerdictPolicy(
+  assessment: Assessment,
+  recommendation: TaskVerdict | null,
+  selected: boolean,
+): Assessment {
+  if (!selected) return assessment;
+  if (
+    recommendation === null ||
+    assessment.execution.status !== "completed" ||
+    assessment.grading.status !== "completed"
+  )
+    return { ...assessment, task: { verdict: "not_assessed" } };
+  return { ...assessment, task: { verdict: recommendation } };
+}
+
+/** Apply a case's pass threshold after every required trial has an assessment. */
+export function summarizeAssessments(
+  assessments: Assessment[],
+  passThreshold = 1,
+): Assessment {
+  if (!assessments.length)
+    throw new Error("at least one assessment is required");
+  if (
+    !Number.isFinite(passThreshold) ||
+    passThreshold <= 0 ||
+    passThreshold > 1
+  )
+    throw new Error("pass threshold must be greater than zero and at most one");
+  const execution: ExecutionStatus = assessments.some(
+    (item) => item.execution.status === "failed",
+  )
+    ? "failed"
+    : assessments.some((item) => item.execution.status === "cancelled")
+      ? "cancelled"
+      : assessments.some((item) => item.execution.status === "not_run")
+        ? "not_run"
+        : "completed";
+  const grading: GradingStatus = assessments.some(
+    (item) => item.grading.status === "error",
+  )
+    ? "error"
+    : assessments.some((item) => item.grading.status === "unavailable")
+      ? "unavailable"
+      : assessments.some((item) => item.grading.status === "completed")
+        ? "completed"
+        : "not_requested";
+  const task: TaskVerdict = assessments.some(
+    (item) => item.task.verdict === "not_assessed",
+  )
+    ? "not_assessed"
+    : assessments.filter((item) => item.task.verdict === "passed").length /
+          assessments.length >=
+        passThreshold
+      ? "passed"
+      : "failed";
+  return {
+    execution: { status: execution },
+    grading: { status: grading },
+    task: { verdict: task },
+  };
+}
+
+/** Combine case verdicts after each case has applied its own threshold. */
+export function summarizeCases(cases: Assessment[]): Assessment {
+  const summary = summarizeAssessments(cases);
+  if (cases.some((item) => item.task.verdict === "failed"))
+    return { ...summary, task: { verdict: "failed" } };
+  return summary;
+}
+
+export interface ExitContext {
+  signal?: "SIGINT" | "SIGTERM";
+  internalFailure?: boolean;
+  dryRun?: boolean;
+}
+
+/** Resolve the documented CLI exit category without discarding detailed states. */
+export function exitCodeFor(
+  assessment: Assessment,
+  context: ExitContext = {},
+): number {
+  if (context.signal === "SIGINT") return 130;
+  if (context.signal === "SIGTERM") return 143;
+  if (context.internalFailure) return 70;
+  if (
+    assessment.execution.status === "failed" ||
+    assessment.execution.status === "cancelled" ||
+    (assessment.execution.status === "not_run" && !context.dryRun)
+  )
+    return 2;
+  if (assessment.grading.status === "error") return 3;
+  if (assessment.grading.status === "unavailable") return 4;
+  if (assessment.task.verdict === "failed") return 1;
+  return 0;
+}

package/src/run-owner.ts

@@ -0,0 +1,276 @@
+import { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import {
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+interface ProcessIdentity {
+  pid: number;
+  startedAt: string;
+  host: string;
+}
+
+interface Claim {
+  format: "sevro.run-owner.v1";
+  evaluationDigest: string;
+  attemptId: string;
+  status: "active" | "complete" | "diagnostic" | "interrupted";
+  owner: ProcessIdentity;
+  activeRunPath: string;
+  evidenceDirectory: string;
+  artifactPath: string;
+  startedAt: string;
+  finalizedAt?: string;
+}
+
+export interface RunOwner {
+  claimPath: string;
+  checkpointPath: string;
+  claim: Claim;
+}
+
+function atomicJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const temporary = join(
+    dirname(path),
+    `.${basename(path)}.${randomUUID()}.tmp`,
+  );
+  try {
+    writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    renameSync(temporary, path);
+  } catch (error) {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // The temporary file may not have been created.
+    }
+    throw error;
+  }
+}
+
+function withClaimLock<T>(claimPath: string, action: () => T): T {
+  const locks = join(dirname(dirname(claimPath)), "locks");
+  mkdirSync(locks, { recursive: true, mode: 0o700 });
+  const database = new Database(join(locks, `${basename(claimPath)}.sqlite`));
+  try {
+    database.exec("PRAGMA busy_timeout = 5000");
+    database.exec("CREATE TABLE IF NOT EXISTS mutex (id INTEGER PRIMARY KEY)");
+    return database.transaction(action).immediate();
+  } finally {
+    database.close();
+  }
+}
+
+function readClaim(path: string): Claim | null {
+  let bytes: string;
+  try {
+    bytes = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  const value = JSON.parse(bytes) as Claim;
+  if (
+    value?.format !== "sevro.run-owner.v1" ||
+    !/^[a-f0-9]{64}$/.test(value.evaluationDigest) ||
+    !value.attemptId ||
+    !["active", "complete", "diagnostic", "interrupted"].includes(
+      value.status,
+    ) ||
+    !value.activeRunPath ||
+    !value.evidenceDirectory ||
+    !value.artifactPath
+  )
+    throw new Error(`unrecognized Sevro ownership record: ${path}`);
+  return value;
+}
+
+function processIdentity(pid: number): ProcessIdentity | null {
+  const windows = process.platform === "win32";
+  const argv = windows
+    ? [
+        "powershell.exe",
+        "-NoProfile",
+        "-NonInteractive",
+        "-Command",
+        `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
+      ]
+    : ["/bin/ps", "-p", String(pid), "-o", "lstart="];
+  let result: ReturnType<typeof Bun.spawnSync>;
+  try {
+    result = Bun.spawnSync(argv, {
+      env: windows
+        ? {
+            PATH: process.env.PATH ?? "",
+            SystemRoot: process.env.SystemRoot ?? "C:\\Windows",
+          }
+        : { PATH: "/usr/bin:/bin", LC_ALL: "C" },
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+  } catch {
+    return null;
+  }
+  const startedAt = result.stdout?.toString().trim() ?? "";
+  return result.exitCode === 0 && startedAt
+    ? { pid, startedAt, host: hostname() }
+    : null;
+}
+
+function ownerStatus(owner: ProcessIdentity): "live" | "dead" | "unknown" {
+  if (
+    !owner ||
+    owner.host !== hostname() ||
+    !Number.isSafeInteger(owner.pid) ||
+    owner.pid <= 0 ||
+    !owner.startedAt
+  )
+    return "unknown";
+  try {
+    process.kill(owner.pid, 0);
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ESRCH"
+      ? "dead"
+      : "unknown";
+  }
+  const current = processIdentity(owner.pid);
+  if (!current) return "unknown";
+  return current.startedAt === owner.startedAt ? "live" : "dead";
+}
+
+function preserveAbandoned(claim: Claim): void {
+  const interrupted = {
+    ...claim,
+    status: "interrupted" as const,
+    finalizedAt: new Date().toISOString(),
+  };
+  atomicJson(join(claim.evidenceDirectory, "run-owner.json"), interrupted);
+  let active: Record<string, unknown>;
+  try {
+    active = JSON.parse(readFileSync(claim.activeRunPath, "utf8"));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    active = {
+      format: "sevro.active-run.v1",
+      runId: claim.attemptId,
+      artifactPath: claim.artifactPath,
+      evidenceDirectory: claim.evidenceDirectory,
+      completedTrials: [],
+    };
+  }
+  atomicJson(claim.activeRunPath, {
+    ...active,
+    status: "interrupted",
+    finalizedAt: interrupted.finalizedAt,
+  });
+}
+
+/** Claim one evaluation identity before candidate execution. */
+export function startRunOwner(options: {
+  stateRoot: string;
+  evaluationDigest: string;
+  attemptId: string;
+  activeRunPath: string;
+  checkpointPath: string;
+  evidenceDirectory: string;
+  artifactPath: string;
+}): RunOwner {
+  if (!/^[a-f0-9]{64}$/.test(options.evaluationDigest))
+    throw new Error("invalid evaluation identity for run ownership");
+  const claimPath = join(
+    options.stateRoot,
+    "owners",
+    `${options.evaluationDigest}.json`,
+  );
+  return withClaimLock(claimPath, () => {
+    const prior = readClaim(claimPath);
+    if (prior && prior.evaluationDigest !== options.evaluationDigest)
+      throw new Error("Sevro ownership record has a different identity");
+    if (prior?.status === "active") {
+      const status = ownerStatus(prior.owner);
+      if (status === "live")
+        throw new Error(`equivalent Sevro run is active: ${claimPath}`);
+      if (status === "unknown")
+        throw new Error(`Sevro run ownership is unverifiable: ${claimPath}`);
+      preserveAbandoned(prior);
+    }
+    const owner = processIdentity(process.pid);
+    if (!owner) throw new Error("cannot verify Sevro runner process identity");
+    const claim: Claim = {
+      format: "sevro.run-owner.v1",
+      evaluationDigest: options.evaluationDigest,
+      attemptId: options.attemptId,
+      status: "active",
+      owner,
+      activeRunPath: options.activeRunPath,
+      evidenceDirectory: options.evidenceDirectory,
+      artifactPath: options.artifactPath,
+      startedAt: new Date().toISOString(),
+    };
+    const context = {
+      claimPath,
+      checkpointPath: options.checkpointPath,
+      claim,
+    };
+    checkpointRunOwner(context, [], "active", true);
+    return context;
+  });
+}
+
+/** Persist a checkpoint only while this attempt owns the identity. */
+export function checkpointRunOwner(
+  context: RunOwner,
+  completedTrials: { trial: number; artifactPath: string }[],
+  status: "active" | "complete" | "diagnostic" | "interrupted",
+  alreadyLocked = false,
+): void {
+  const write = () => {
+    if (!alreadyLocked) {
+      const current = readClaim(context.claimPath);
+      if (!current || current.attemptId !== context.claim.attemptId)
+        throw new Error("Sevro run ownership changed before checkpoint");
+      if (current.status !== "active")
+        throw new Error("Sevro run owner is already finalized");
+      if (ownerStatus(current.owner) !== "live")
+        throw new Error("Sevro run owner identity is no longer verifiable");
+    }
+    const finalizedAt =
+      status === "active" ? undefined : new Date().toISOString();
+    const updatedClaim = {
+      ...context.claim,
+      status,
+      ...(finalizedAt ? { finalizedAt } : {}),
+    };
+    atomicJson(context.checkpointPath, {
+      format: "sevro.run-checkpoint.v1",
+      runId: context.claim.attemptId,
+      completedTrials,
+    });
+    atomicJson(context.claim.activeRunPath, {
+      format: "sevro.active-run.v1",
+      runId: context.claim.attemptId,
+      evaluationDigest: context.claim.evaluationDigest,
+      attemptId: context.claim.attemptId,
+      status,
+      owner: context.claim.owner,
+      artifactPath: context.claim.artifactPath,
+      evidenceDirectory: context.claim.evidenceDirectory,
+      checkpointPath: context.checkpointPath,
+      completedTrials,
+      ...(finalizedAt ? { finalizedAt } : {}),
+    });
+    atomicJson(context.claimPath, updatedClaim);
+    context.claim = updatedClaim;
+  };
+  if (alreadyLocked) write();
+  else withClaimLock(context.claimPath, write);
+}

package/src/schema.ts

@@ -0,0 +1,28 @@
+import Ajv2020 from "ajv/dist/2020.js";
+import cliSchema from "../schemas/cli-result-v1.schema.json";
+import runSchema from "../schemas/run-evidence-v1.schema.json";
+import reportSchema from "../schemas/report-v1.schema.json";
+
+const ajv = new Ajv2020({
+  strict: true,
+  strictRequired: false,
+  strictTypes: false,
+});
+ajv.addSchema(cliSchema);
+ajv.addSchema(runSchema);
+ajv.addSchema(reportSchema);
+const cliValidator = ajv.getSchema("urn:sevro:schema:cli-result:v1")!;
+const runValidator = ajv.getSchema("urn:sevro:schema:run-evidence:v1")!;
+const reportValidator = ajv.getSchema("urn:sevro:schema:report:v1")!;
+
+export function assertCliResult(value: unknown): void {
+  if (!cliValidator(value)) throw new Error("invalid Sevro CLI result");
+}
+
+export function assertRunEvidence(value: unknown): void {
+  if (!runValidator(value)) throw new Error("invalid Sevro retained evidence");
+}
+
+export function assertReport(value: unknown): void {
+  if (!reportValidator(value)) throw new Error("invalid Sevro report");
+}

package/src/storage.ts

@@ -0,0 +1,23 @@
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** Write a private JSON artifact and publish it with one atomic rename. */
+export async function atomicWriteJson(
+  path: string,
+  value: unknown,
+): Promise<void> {
+  const parent = dirname(path);
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporary, path);
+  } catch (error) {
+    await unlink(temporary).catch(() => {});
+    throw error;
+  }
+}

package/src/trial-scheduler.ts

@@ -0,0 +1,27 @@
+/** Bound trial admission, stop on errors/cancellation, and drain active work. */
+export async function scheduleTrials(
+  options: { count: number; jobs: number; signal?: AbortSignal },
+  run: (trial: number, stopAdmission: () => void) => Promise<boolean>,
+): Promise<void> {
+  let nextTrial = 1;
+  let stopped = false;
+  const stopAdmission = () => {
+    stopped = true;
+  };
+  let failure: { error: unknown } | undefined;
+  const worker = async () => {
+    while (!stopped && !options.signal?.aborted && nextTrial <= options.count) {
+      const trial = nextTrial++;
+      try {
+        if (!(await run(trial, stopAdmission))) stopAdmission();
+      } catch (error) {
+        stopped = true;
+        failure ??= { error };
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: Math.min(options.jobs, options.count) }, worker),
+  );
+  if (failure) throw failure.error;
+}