@bjoernrochel/sevro 0.1.0-rc.2 → 0.1.0-rc.21

package/src/results.ts

@@ -1,21 +1,17 @@
-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 };
-}
+import type {
+  Assessment,
+  CheckOutcome,
+  ExecutionStatus,
+  GradingStatus,
+  TaskVerdict,
+} from "./contract-types";
+export type {
+  Assessment,
+  CheckOutcome,
+  ExecutionStatus,
+  GradingStatus,
+  TaskVerdict,
+} from "./contract-types";
 
 export interface TrialInput {
   execution: ExecutionStatus;
@@ -27,9 +23,19 @@ export interface TrialInput {
 
 /** Reduce one trial without treating process completion as task success. */
 export function assessTrial(input: TrialInput): Assessment {
+  const { declared, seen } = validateCheckResults(input);
+  const grading = trialGrading(input, declared.size, seen.size);
+  const task = trialVerdict(input, grading);
+  return {
+    execution: { status: input.execution },
+    grading: { status: grading },
+    task: { verdict: task },
+  };
+}
+
+function validateCheckResults(input: TrialInput) {
   const declared = new Set(input.declaredChecks);
-  if (declared.size !== input.declaredChecks.length || declared.has(""))
-    throw new Error("check declarations must have unique nonempty IDs");
+  validateCheckDeclarations(input.declaredChecks, declared);
   const seen = new Set<string>();
   for (const check of input.checks) {
     if (!declared.has(check.id) || seen.has(check.id))
@@ -37,29 +43,36 @@ export function assessTrial(input: TrialInput): Assessment {
     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 },
-  };
+  return { declared, seen };
+}
+
+function trialGrading(
+  input: TrialInput,
+  declared: number,
+  seen: number,
+): GradingStatus {
+  if (input.graderError) return "error";
+  if (input.execution !== "completed") return "not_requested";
+  if (evidenceUnavailable(input, declared, seen)) return "unavailable";
+  return declared === 0 ? "not_requested" : "completed";
+}
+
+function evidenceUnavailable(
+  input: TrialInput,
+  declared: number,
+  seen: number,
+): boolean {
+  return (
+    Boolean(input.requiredEvidenceUnavailable) ||
+    input.checks.some((check) => check.status === "unavailable") ||
+    seen !== declared
+  );
+}
+
+function trialVerdict(input: TrialInput, grading: GradingStatus): TaskVerdict {
+  if (input.execution !== "completed") return "not_assessed";
+  if (input.checks.some((check) => check.status === "failed")) return "failed";
+  return grading === "completed" ? "passed" : "not_assessed";
 }
 
 /** Apply an explicitly selected policy only to a fully assessed trial. */
@@ -83,6 +96,21 @@ export function summarizeAssessments(
   assessments: Assessment[],
   passThreshold = 1,
 ): Assessment {
+  validateSummaryInputs(assessments, passThreshold);
+  const execution = summaryExecution(assessments);
+  const grading = summaryGrading(assessments);
+  const task = summaryVerdict(assessments, passThreshold);
+  return {
+    execution: { status: execution },
+    grading: { status: grading },
+    task: { verdict: task },
+  };
+}
+
+function validateSummaryInputs(
+  assessments: Assessment[],
+  passThreshold: number,
+): void {
   if (!assessments.length)
     throw new Error("at least one assessment is required");
   if (
@@ -91,38 +119,36 @@ export function summarizeAssessments(
     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 },
-  };
+}
+
+function summaryExecution(assessments: Assessment[]): ExecutionStatus {
+  const priority: ExecutionStatus[] = ["failed", "cancelled", "not_run"];
+  return (
+    priority.find((status) =>
+      assessments.some((item) => item.execution.status === status),
+    ) ?? "completed"
+  );
+}
+
+function summaryGrading(assessments: Assessment[]): GradingStatus {
+  const priority: GradingStatus[] = ["error", "unavailable", "completed"];
+  return (
+    priority.find((status) =>
+      assessments.some((item) => item.grading.status === status),
+    ) ?? "not_requested"
+  );
+}
+
+function summaryVerdict(
+  assessments: Assessment[],
+  passThreshold: number,
+): TaskVerdict {
+  if (assessments.some((item) => item.task.verdict === "not_assessed"))
+    return "not_assessed";
+  const passed = assessments.filter(
+    (item) => item.task.verdict === "passed",
+  ).length;
+  return passed / assessments.length >= passThreshold ? "passed" : "failed";
 }
 
 /** Combine case verdicts after each case has applied its own threshold. */
@@ -144,17 +170,38 @@ export function exitCodeFor(
   assessment: Assessment,
   context: ExitContext = {},
 ): number {
+  const interruption = interruptionExit(context);
+  if (interruption !== null) return interruption;
+  if (executionFailed(assessment.execution.status, context)) return 2;
+  const gradingCodes: Partial<Record<GradingStatus, number>> = {
+    error: 3,
+    unavailable: 4,
+  };
+  return gradingCodes[assessment.grading.status] ?? taskExitCode(assessment);
+}
+
+function interruptionExit(context: ExitContext): number | null {
   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;
+  return context.internalFailure ? 70 : null;
+}
+
+function executionFailed(
+  status: ExecutionStatus,
+  context: ExitContext,
+): boolean {
+  return (
+    status === "failed" ||
+    status === "cancelled" ||
+    (status === "not_run" && !context.dryRun)
+  );
+}
+
+function taskExitCode(assessment: Assessment): number {
+  return assessment.task.verdict === "failed" ? 1 : 0;
+}
+
+function validateCheckDeclarations(ids: string[], declared: Set<string>): void {
+  if (declared.size !== ids.length || declared.has(""))
+    throw new Error("check declarations must have unique nonempty IDs");
 }

package/src/run-owner.ts

@@ -1,3 +1,4 @@
+import { isRecord } from "./value-guards";
 import { Database } from "bun:sqlite";
 import { randomUUID } from "node:crypto";
 import {
@@ -10,7 +11,7 @@ import {
 import { hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
 
-interface ProcessIdentity {
+export interface ProcessIdentity {
   pid: number;
   startedAt: string;
   host: string;
@@ -29,6 +30,60 @@ interface Claim {
   finalizedAt?: string;
 }
 
+interface RetainedClaim {
+  format: "sevro.run-owner.v1";
+  evaluationDigest: unknown;
+  attemptId: unknown;
+  status: Claim["status"];
+  owner?: unknown;
+  activeRunPath: string;
+  evidenceDirectory: string;
+  artifactPath: string;
+  startedAt?: unknown;
+  finalizedAt?: unknown;
+}
+
+function errorCode(error: unknown): unknown {
+  return isRecord(error) ? error.code : undefined;
+}
+function nonemptyText(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function validClaimStatus(value: unknown): value is Claim["status"] {
+  return (
+    value === "active" ||
+    value === "complete" ||
+    value === "diagnostic" ||
+    value === "interrupted"
+  );
+}
+
+function validClaimIdentity(value: Record<string, unknown>): boolean {
+  return (
+    value.format === "sevro.run-owner.v1" &&
+    /^[a-f0-9]{64}$/.test(String(value.evaluationDigest)) &&
+    Boolean(value.attemptId) &&
+    validClaimStatus(value.status)
+  );
+}
+
+function validClaimPaths(value: Record<string, unknown>): boolean {
+  return (
+    nonemptyText(value.activeRunPath) &&
+    nonemptyText(value.evidenceDirectory) &&
+    nonemptyText(value.artifactPath)
+  );
+}
+
+function assertRetainedClaim(
+  value: unknown,
+  path: string,
+): asserts value is RetainedClaim {
+  if (!isRecord(value) || !validClaimIdentity(value) || !validClaimPaths(value))
+    throw new Error(`unrecognized Sevro ownership record: ${path}`);
+}
+
 export interface RunOwner {
   claimPath: string;
   checkpointPath: string;
@@ -62,41 +117,29 @@ function withClaimLock<T>(claimPath: string, action: () => T): T {
   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)");
+    database.run("PRAGMA busy_timeout = 5000");
+    database.run("CREATE TABLE IF NOT EXISTS mutex (id INTEGER PRIMARY KEY)");
     return database.transaction(action).immediate();
   } finally {
     database.close();
   }
 }
 
-function readClaim(path: string): Claim | null {
+function readClaim(path: string): RetainedClaim | null {
   let bytes: string;
   try {
     bytes = readFileSync(path, "utf8");
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    if (errorCode(error) === "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}`);
+  const value: unknown = JSON.parse(bytes);
+  assertRetainedClaim(value, path);
   return value;
 }
 
-function processIdentity(pid: number): ProcessIdentity | null {
-  const windows = process.platform === "win32";
-  const argv = windows
+function identityCommand(pid: number, windows: boolean): string[] {
+  return windows
     ? [
         "powershell.exe",
         "-NoProfile",
@@ -105,49 +148,79 @@ function processIdentity(pid: number): ProcessIdentity | null {
         `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks`,
       ]
     : ["/bin/ps", "-p", String(pid), "-o", "lstart="];
+}
+
+function identityEnvironment(windows: boolean) {
+  return windows
+    ? {
+        PATH: process.env.PATH ?? "",
+        SystemRoot: process.env.SystemRoot ?? "C:\\Windows",
+      }
+    : { PATH: "/usr/bin:/bin", LC_ALL: "C" };
+}
+
+function processStartTime(result: ReturnType<typeof Bun.spawnSync>): string {
+  return result.stdout?.toString().trim() ?? "";
+}
+
+export function processIdentity(pid: number): ProcessIdentity | null {
+  const windows = process.platform === "win32";
+  const argv = identityCommand(pid, windows);
   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" },
+      env: identityEnvironment(windows),
       stdout: "pipe",
       stderr: "ignore",
     });
   } catch {
     return null;
   }
-  const startedAt = result.stdout?.toString().trim() ?? "";
+  const startedAt = processStartTime(result);
   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";
+function validProcessId(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+
+export function validProcessIdentity(value: unknown): value is ProcessIdentity {
+  return (
+    isRecord(value) &&
+    value.host === hostname() &&
+    validProcessId(value.pid) &&
+    nonemptyText(value.startedAt)
+  );
+}
+
+function processLiveness(pid: number): "live" | "dead" | "unknown" {
   try {
-    process.kill(owner.pid, 0);
+    process.kill(pid, 0);
+    return "live";
   } catch (error) {
-    return (error as NodeJS.ErrnoException).code === "ESRCH"
-      ? "dead"
-      : "unknown";
+    return errorCode(error) === "ESRCH" ? "dead" : "unknown";
   }
+}
+
+export function ownerStatus(owner: unknown): "live" | "dead" | "unknown" {
+  if (!validProcessIdentity(owner)) return "unknown";
+  const liveness = processLiveness(owner.pid);
+  if (liveness !== "live") return liveness;
   const current = processIdentity(owner.pid);
   if (!current) return "unknown";
   return current.startedAt === owner.startedAt ? "live" : "dead";
 }
 
-function preserveAbandoned(claim: Claim): void {
+function activeRunFields(value: unknown): Record<string, unknown> {
+  if (value == null) return {};
+  // Preserve the existing object-spread representation of opaque active records.
+  const entries: [string, unknown][] = Object.entries(value);
+  return Object.fromEntries(entries);
+}
+
+function preserveAbandoned(claim: RetainedClaim): void {
   const interrupted = {
     ...claim,
     status: "interrupted" as const,
@@ -156,9 +229,12 @@ function preserveAbandoned(claim: Claim): void {
   atomicJson(join(claim.evidenceDirectory, "run-owner.json"), interrupted);
   let active: Record<string, unknown>;
   try {
-    active = JSON.parse(readFileSync(claim.activeRunPath, "utf8"));
+    const parsed: unknown = JSON.parse(
+      readFileSync(claim.activeRunPath, "utf8"),
+    );
+    active = activeRunFields(parsed);
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    if (errorCode(error) !== "ENOENT") throw error;
     active = {
       format: "sevro.active-run.v1",
       runId: claim.attemptId,
@@ -174,6 +250,37 @@ function preserveAbandoned(claim: Claim): void {
   });
 }
 
+function validateClaimIdentityMatch(
+  prior: RetainedClaim | null,
+  evaluationDigest: string,
+): void {
+  if (prior && prior.evaluationDigest !== evaluationDigest)
+    throw new Error("Sevro ownership record has a different identity");
+}
+
+function retainPreviousOwner(
+  prior: RetainedClaim | null,
+  claimPath: string,
+): void {
+  if (prior === null || prior.status !== "active") return;
+  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);
+}
+
+function validateCheckpointOwner(context: RunOwner): void {
+  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");
+}
+
 /** Claim one evaluation identity before candidate execution. */
 export function startRunOwner(options: {
   stateRoot: string;
@@ -193,16 +300,8 @@ export function startRunOwner(options: {
   );
   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);
-    }
+    validateClaimIdentityMatch(prior, options.evaluationDigest);
+    retainPreviousOwner(prior, claimPath);
     const owner = processIdentity(process.pid);
     if (!owner) throw new Error("cannot verify Sevro runner process identity");
     const claim: Claim = {
@@ -234,15 +333,7 @@ export function checkpointRunOwner(
   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");
-    }
+    if (!alreadyLocked) validateCheckpointOwner(context);
     const finalizedAt =
       status === "active" ? undefined : new Date().toISOString();
     const updatedClaim = {