@bjoernrochel/sevro 0.1.0-rc.8 → 1.1.0

package/src/schema-types.ts

@@ -1,83 +1,65 @@
-/** Structural contracts for data validated by the versioned JSON schemas. */
-export type CliResultData = {
+import type { AdvisoryAssessment } from "./advisory";
+import type {
+  ArtifactReference,
+  Assessment,
+  CheckOutcome,
+  Diagnostic,
+  DomainOutcome,
+  EvidenceRoute,
+  ExecutionStatus,
+  ExitCode,
+  GradingStatus,
+  MetricEvidence,
+  ObservationCompleteness,
+  ObservationEvidence,
+  OutcomeStatus,
+  RawResultReference,
+  TaskVerdict,
+  UsageEvidence,
+} from "./contract-types";
+import type { IdentityDimensions } from "./identity";
+import type { InstrumentationRequest } from "./instrumentation";
+
+/** Wire assessments additionally allow optional serialized error codes. */
+export type WireAssessment = {
+  execution: Assessment["execution"] & { errorCode?: string };
+  grading: Assessment["grading"] & { errorCode?: string };
+  task: Assessment["task"];
+};
+
+/** Validated v1 wire data also represents failures before run allocation. */
+export type CliResultData = WireAssessment & {
   format: "sevro.cli-result.v1";
   runId: string | null;
-  execution: CliResultDataExecution;
-  grading: CliResultDataGrading;
-  task: CliResultDataTask;
-  exitCode: 0 | 1 | 2 | 3 | 4 | 64 | 70 | 130 | 143;
+  exitCode: ExitCode;
   evidencePath: string | null;
   cases: Array<CliResultDataCase>;
-  diagnostic?: CliResultDataDiagnostic;
-};
-type CliResultDataExecution = {
-  status: "completed" | "failed" | "cancelled" | "not_run";
-  errorCode?: string;
-};
-type CliResultDataGrading = {
-  status: "completed" | "error" | "unavailable" | "not_requested";
-  errorCode?: string;
-};
-type CliResultDataTask = { verdict: "passed" | "failed" | "not_assessed" };
-type CliResultDataCheck = {
-  id: string;
-  grader: string;
-  status: "passed" | "failed" | "unavailable";
-  detail?: string;
-  evidenceRefs?: Array<string>;
+  diagnostic?: Diagnostic;
 };
-type CliResultDataDomainOutcome = {
-  id: string;
-  status: "passed" | "failed" | "unavailable";
-  detail?: string;
-  evidenceRefs: Array<string>;
-  data?: Record<string, unknown>;
-};
-type CliResultDataTrial = {
+export type CliResultDataTrial = WireAssessment & {
   trial: number;
-  execution: CliResultDataExecution;
-  grading: CliResultDataGrading;
-  task: CliResultDataTask;
-  checks: Array<CliResultDataCheck>;
-  domainOutcomes?: Array<CliResultDataDomainOutcome>;
+  checks: Array<CheckOutcome>;
+  domainOutcomes?: Array<DomainOutcome>;
   artifactPath: string | null;
 };
-type CliResultDataCase = {
+export type CliResultDataCase = WireAssessment & {
   caseId: string;
-  execution: CliResultDataExecution;
-  grading: CliResultDataGrading;
-  task: CliResultDataTask;
   trials: Array<CliResultDataTrial>;
 };
-type CliResultDataDiagnostic = { code: string; message: string };
+
+/** Structural contracts for data validated by the versioned JSON schemas. */
 export type RunEvidenceData = {
   format: "sevro.run-evidence.v1";
   runId: string;
   evaluationIdentity: {
     algorithm: "sevro.identity.v1";
     digest: RunEvidenceDataDigest;
-    dimensions: {
-      runnerBuildDigest: RunEvidenceDataDigest;
-      projectDigest: RunEvidenceDataDigest;
-      configurationDigest: RunEvidenceDataDigest;
-      extensionDigest: RunEvidenceDataDigest | null;
-      extensionProtocol: "sevro.extension.v1" | null;
-      caseDigest: RunEvidenceDataDigest;
-      fixtureDigest: RunEvidenceDataDigest;
-      checksDigest: RunEvidenceDataDigest;
-      requiredEvidenceDigest: RunEvidenceDataDigest;
-      evaluatorDigest: RunEvidenceDataDigest;
-      graderDigest: RunEvidenceDataDigest;
-      instrumentationDigest: RunEvidenceDataDigest;
-      routeDigest: RunEvidenceDataDigest;
-      condition: "passive" | "enforced";
-      trialCount: number;
-      passThreshold: number;
-    };
+    dimensions: IdentityDimensions;
   };
   configuration: {
     digest: RunEvidenceDataDigest;
     redacted: Record<string, unknown>;
+    resolved?: Record<string, unknown>;
   };
   runner: RunEvidenceDataRunner;
   project: {
@@ -89,17 +71,17 @@ export type RunEvidenceData = {
   condition: {
     requested: "passive" | "enforced";
     actual: "passive" | "enforced" | "unknown";
-    requestedInstrumentation: RunEvidenceDataInstrumentationList;
-    appliedInstrumentation: RunEvidenceDataInstrumentationList;
+    requestedInstrumentation: InstrumentationRequest[];
+    appliedInstrumentation: InstrumentationRequest[];
   };
   graders: {
     active: Array<RunEvidenceDataGrader>;
     replacedDefaults: Array<string>;
   };
-  routes: Array<RunEvidenceDataRoute>;
+  routes: Array<EvidenceRoute>;
   result: CliResultData;
   trials: Array<RunEvidenceDataTrialEvidence>;
-  diagnostic?: RunEvidenceDataDiagnostic;
+  diagnostic?: Diagnostic;
 };
 type RunEvidenceDataDigest = string;
 type RunEvidenceDataFileUrl = string;
@@ -126,49 +108,18 @@ type RunEvidenceDataExtension = {
   capabilities: Array<string>;
   replacements: { graders: Array<string>; taskVerdictPolicy: string | null };
 };
-type RunEvidenceDataInstrumentationList = Array<{
-  id: string;
-  configuration: Record<string, unknown>;
-}>;
 type RunEvidenceDataGrader = {
   id: string;
   source: "builtin" | "extension";
   version: string;
 };
-type RunEvidenceDataRoute = {
-  role: "candidate" | "semantic" | "advisory";
-  host: string;
-  model: string;
-  effort: string;
-};
-type RunEvidenceDataAdvisoryReview = null | {
+export type AdvisoryReviewData = {
   status: "completed" | "failed" | "not_run";
-  assessment: null | {
-    verdict: "pass" | "fail";
-    overallScore: number;
-    dimensions: {
-      correctness: number;
-      maintainability: number;
-      testQuality: number;
-      scopeDiscipline: number;
-    };
-    strengths: Array<string>;
-    weaknesses: Array<string>;
-    summary: string;
-  };
-  usage: {
-    inputTokens: number | null;
-    outputTokens: number | null;
-    costUsd: number | null;
-    complete: boolean;
-  };
-  rawResult: {
-    source: string;
-    path: RunEvidenceDataFileUrl | null;
-    sha256: RunEvidenceDataDigest | null;
-  };
+  assessment: AdvisoryAssessment | null;
+  usage: UsageEvidence;
+  rawResult: RawResultReference;
 };
-type RunEvidenceDataTrialEvidence = {
+export type RunEvidenceDataTrialEvidence = {
   caseId: string;
   trial: number;
   executionMode: "executed" | "dry" | "unknown";
@@ -176,50 +127,22 @@ type RunEvidenceDataTrialEvidence = {
   condition: {
     requested: "passive" | "enforced";
     actual: "passive" | "enforced" | "unknown";
-    appliedInstrumentation: RunEvidenceDataInstrumentationList;
+    appliedInstrumentation: InstrumentationRequest[];
   };
-  observationCompleteness: "complete" | "partial" | "unavailable";
-  observations: Array<{
-    id: string;
-    source: string;
-    completeness: "complete" | "partial" | "unavailable";
-    data: Record<string, unknown>;
-  }>;
-  metrics: Array<RunEvidenceDataMetric>;
-  domainOutcomes?: Array<{
-    id: string;
-    status: "passed" | "failed" | "unavailable";
-    detail?: string;
-    evidenceRefs: Array<string>;
-    data?: Record<string, unknown>;
-  }>;
+  observationCompleteness: ObservationCompleteness;
+  observations: Array<ObservationEvidence>;
+  metrics: Array<MetricEvidence>;
+  domainOutcomes?: Array<DomainOutcome>;
   taskVerdictPolicy: null | {
     id: string;
-    recommendation: "passed" | "failed" | "not_assessed" | null;
-  };
-  advisoryReview?: RunEvidenceDataAdvisoryReview;
-  routes: Array<RunEvidenceDataRoute>;
-  usage: {
-    inputTokens: number | null;
-    outputTokens: number | null;
-    costUsd: number | null;
-    complete: boolean;
+    recommendation: TaskVerdict | null;
   };
-  rawResult: {
-    source: string;
-    path: RunEvidenceDataFileUrl | null;
-    sha256: RunEvidenceDataDigest | null;
-  };
-  artifactRefs: Array<{
-    id: string;
-    path: RunEvidenceDataFileUrl;
-    sha256: RunEvidenceDataDigest;
-    gitExclude?: boolean;
-    executable?: boolean;
-  }>;
+  advisoryReview?: AdvisoryReviewData | null;
+  routes: Array<EvidenceRoute>;
+  usage: UsageEvidence;
+  rawResult: RawResultReference;
+  artifactRefs: Array<ArtifactReference>;
 };
-type RunEvidenceDataDiagnostic = { code: string; message: string };
-type RunEvidenceDataMetric = { id: string; value: number | null; unit: string };
 export type ReportData = {
   format: "sevro.report.v1";
   inputs: Array<ReportDataInput>;
@@ -233,38 +156,32 @@ export type ReportData = {
 };
 type ReportDataPath = string;
 type ReportDataDigest = string;
-type ReportDataState =
-  | "completed"
-  | "failed"
-  | "cancelled"
-  | "not_run"
-  | "error"
-  | "unavailable"
-  | "not_requested";
-type ReportDataVerdict = "passed" | "failed" | "not_assessed";
+/** The report wire schema deliberately allows either state family in rows. */
+type ReportDataState = ExecutionStatus | GradingStatus;
 type ReportDataInput = {
   resultFile: ReportDataPath;
-  execution: "completed" | "failed" | "cancelled" | "not_run";
-  grading: "completed" | "error" | "unavailable" | "not_requested";
-  task: ReportDataVerdict;
-  exitCode: 0 | 1 | 2 | 3 | 4 | 64 | 70 | 130 | 143;
+  execution: ExecutionStatus;
+  grading: GradingStatus;
+  task: TaskVerdict;
+  exitCode: ExitCode;
   caseCount: number;
 };
-type ReportDataRoute = { host: string; model: string; effort: string };
+type ReportDataRoute = Omit<EvidenceRoute, "role">;
 type ReportDataOutcome = {
   trial: number;
   id: string;
-  status: "passed" | "failed" | "unavailable";
+  status: OutcomeStatus;
 };
 type ReportDataRow = {
+  nativeTranscripts?: { retained: number; pruned: number };
   resultFile: ReportDataPath;
   evidencePath: string | null;
   runId: string | null;
   caseId: string;
   execution: ReportDataState;
   grading: ReportDataState;
-  task: ReportDataVerdict;
-  exitCode: 0 | 1 | 2 | 3 | 4 | 64 | 70 | 130 | 143;
+  task: TaskVerdict;
+  exitCode: ExitCode;
   trialCount: number;
   taskPassRate: number | null;
   candidateDurationMs: number | null;
@@ -276,11 +193,6 @@ type ReportDataRow = {
   requestedCondition: "passive" | "enforced" | null;
   actualCondition: "passive" | "enforced" | "unknown" | null;
   candidateRoute: ReportDataRoute | null;
-  routes: Array<{
-    role: "candidate" | "semantic" | "advisory";
-    host: string;
-    model: string;
-    effort: string;
-  }>;
+  routes: Array<EvidenceRoute>;
   domainOutcomes: Array<ReportDataOutcome>;
 };

package/src/shell.ts

@@ -0,0 +1,4 @@
+/** Encode one literal argument for a POSIX shell, including empty strings. */
+export function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}

package/src/sqlite-lock.ts

@@ -0,0 +1,25 @@
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+interface LockDatabase {
+  exec(sql: string): unknown;
+  close(): void;
+}
+
+/** Both drivers use SQLite file locks, including across Node and Bun runners. */
+export function openLockDatabase(path: string): LockDatabase {
+  if (process.versions.bun) {
+    const { Database } = require("bun:sqlite") as typeof import("bun:sqlite");
+    const database = new Database(path);
+    return {
+      exec: (sql) => database.run(sql),
+      close() {
+        database.close();
+      },
+    };
+  }
+  const { DatabaseSync } =
+    require("node:sqlite") as typeof import("node:sqlite");
+  return new DatabaseSync(path);
+}

package/src/transcript-retention.ts

@@ -0,0 +1,146 @@
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { RunEvidenceData } from "./schema-types";
+import { canonicalJson, sha256 } from "./identity";
+import type { ArtifactReference } from "./contract-types";
+import { retainedFile } from "./results-lock";
+import { atomicWriteJson } from "./storage";
+
+function isNativeTranscript(artifact: ArtifactReference) {
+  return /^(?:sevro\.(?:semantic(?:\.[a-f0-9]{64})?|advisory)\.)?sevro\.native-transcripts\.bundle$/.test(
+    artifact.id,
+  );
+}
+
+function transcriptArtifacts(evidence: RunEvidenceData) {
+  return evidence.trials.flatMap((trial) =>
+    trial.artifactRefs.filter(isNativeTranscript).map((artifact) => ({
+      caseId: trial.caseId,
+      trial: trial.trial,
+      ...artifact,
+    })),
+  );
+}
+
+function pruningRecord(evidence: RunEvidenceData) {
+  return {
+    format: "sevro.pruned-native-transcripts.v1",
+    runId: evidence.runId,
+    artifacts: transcriptArtifacts(evidence),
+  };
+}
+
+function pruningPath(evidence: RunEvidenceData) {
+  if (evidence.result.evidencePath === null)
+    throw new Error(
+      "native transcript retention requires a retained evidence path",
+    );
+  return join(
+    dirname(evidence.result.evidencePath),
+    "native-transcripts-pruned.json",
+  );
+}
+
+function transcriptPath(
+  evidence: RunEvidenceData,
+  artifact: ArtifactReference,
+) {
+  const path = fileURLToPath(artifact.path);
+  if (dirname(path) !== dirname(pruningPath(evidence)))
+    throw new Error(
+      "native transcript artifact is outside its retained result directory",
+    );
+  if (metadataPaths(evidence).includes(path))
+    throw new Error(
+      "native transcript artifact aliases retained result metadata",
+    );
+  if (otherArtifactPaths(evidence).includes(path))
+    throw new Error(
+      "native transcript artifact aliases other retained evidence",
+    );
+  return path;
+}
+
+function otherArtifactPaths(evidence: RunEvidenceData) {
+  return evidence.trials
+    .flatMap((trial) => [
+      trial.rawResult.path,
+      trial.advisoryReview?.rawResult.path,
+      ...trial.artifactRefs
+        .filter((ref) => !isNativeTranscript(ref))
+        .map((ref) => ref.path),
+    ])
+    .filter((path): path is string => path != null)
+    .map((path) => fileURLToPath(path));
+}
+
+function metadataPaths(evidence: RunEvidenceData) {
+  const receipt = pruningPath(evidence);
+  return [
+    receipt,
+    evidence.result.evidencePath,
+    join(dirname(receipt), "result.json"),
+    join(dirname(receipt), "latest.json"),
+    ...evidence.result.cases.flatMap((selected) =>
+      selected.trials.map((trial) => trial.artifactPath),
+    ),
+  ];
+}
+
+async function transcriptPresent(
+  evidence: RunEvidenceData,
+  artifact: ArtifactReference,
+) {
+  const path = transcriptPath(evidence, artifact);
+  if (!(await retainedFile(path))) return false;
+  if (sha256(await readFile(path)) !== artifact.sha256)
+    throw new Error("retained native transcript evidence hash differs");
+  return true;
+}
+
+/** Keep capture evidence immutable; a separate receipt records intentional removal. */
+export async function pruneNativeTranscripts(evidence: RunEvidenceData) {
+  const artifacts = transcriptArtifacts(evidence);
+  if (!artifacts.length) return 0;
+  await atomicWriteJson(pruningPath(evidence), pruningRecord(evidence));
+  let removed = 0;
+  for (const artifact of artifacts) {
+    const path = transcriptPath(evidence, artifact);
+    if (!(await retainedFile(path))) continue;
+    await rm(path);
+    removed++;
+  }
+  return removed;
+}
+
+/** Missing native bytes require an exact receipt bound to their original references. */
+async function hasPruningRecord(evidence: RunEvidenceData) {
+  const path = pruningPath(evidence);
+  const marked = await retainedFile(path);
+  if (marked) {
+    const receipt: unknown = JSON.parse(await readFile(path, "utf8"));
+    if (canonicalJson(receipt) !== canonicalJson(pruningRecord(evidence)))
+      throw new Error(
+        "native transcript pruning record differs from retained evidence",
+      );
+  }
+  return marked !== null;
+}
+
+export async function nativeTranscriptRetention(
+  evidence: RunEvidenceData | null,
+) {
+  if (!evidence) return [];
+  const marked = await hasPruningRecord(evidence);
+  const states = [];
+  for (const artifact of transcriptArtifacts(evidence)) {
+    const present = await transcriptPresent(evidence, artifact);
+    if (!present && !marked)
+      throw new Error(
+        "retained native transcript evidence is missing without a pruning record",
+      );
+    states.push({ caseId: artifact.caseId, pruned: !present });
+  }
+  return states;
+}

package/src/value-guards.ts

@@ -3,6 +3,28 @@ export function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
+export function requireRecord(
+  value: unknown,
+  message: string,
+): Record<string, unknown> {
+  if (!isRecord(value)) throw new Error(message);
+  return value;
+}
+
+export function validQualifiedId(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/.test(value)
+  );
+}
+
+export function containsControl(value: string): boolean {
+  return Array.from(value).some(
+    (character) =>
+      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,
+  );
+}
+
 export function isUnknownArray(value: unknown): value is unknown[] {
   return Array.isArray(value);
 }