@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/src/runtime/shared-cache.ts

@@ -0,0 +1,130 @@
+import { access, lstat, realpath, symlink } from "node:fs/promises";
+import { constants } from "node:fs";
+import { userInfo } from "node:os";
+import { isAbsolute, join } from "node:path";
+import type { RuntimePolicy, RuntimeRole } from "./config";
+import { declaredRuntimeRoots, requireRuntimeReadRoots } from "./paths";
+
+export interface SharedCacheDirectory {
+  source: string;
+  target: string;
+  roles: RuntimeRole[];
+}
+
+export async function resolveSharedCaches(
+  caches: SharedCacheDirectory[],
+  environment: Record<string, string>,
+  base: string,
+  protectedRoots: string[],
+): Promise<SharedCacheDirectory[]> {
+  return Promise.all(
+    caches.map(async (cache) => {
+      const roots = await declaredRuntimeRoots(
+        [cache.source],
+        environment,
+        base,
+      );
+      requireRuntimeReadRoots(roots, protectedRoots);
+      const [declared] = roots;
+      if (!declared) throw new Error("runtime shared cache source is missing");
+      const source = await realpath(declared);
+      await requireSharedCache(source);
+      return { ...cache, source };
+    }),
+  );
+}
+
+export function selectedSharedCaches(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+): SharedCacheDirectory[] {
+  return (policy?.sharedCacheDirectories ?? []).filter((cache) =>
+    cache.roles.includes(role),
+  );
+}
+
+export async function sharedCacheRoots(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+  protectedRoots: string[],
+): Promise<string[]> {
+  const roots = selectedSharedCaches(policy, role).map((cache) => cache.source);
+  return requireWritableCacheRoots(roots, protectedRoots);
+}
+
+export function requireSharedCachePolicy(
+  policy: RuntimePolicy | undefined,
+): void {
+  if (!policy) return;
+  const caches = policy.sharedCacheDirectories ?? [];
+  const protectedRoots = [
+    ...policy.readOnlyRoots,
+    ...(policy.seeds ?? []).map((seed) => seed.source),
+  ];
+  for (const cache of caches) {
+    requireRuntimeReadRoots(
+      [cache.source],
+      [
+        ...protectedRoots,
+        ...caches
+          .filter((other) => other !== cache)
+          .map((other) => other.source),
+      ],
+    );
+  }
+}
+
+export function sharedCacheDenyRoots(
+  policy: RuntimePolicy | undefined,
+  role: RuntimeRole = "candidate",
+): string[] {
+  return (policy?.sharedCacheDirectories ?? [])
+    .filter((cache) => !cache.roles.includes(role))
+    .map((cache) => cache.source);
+}
+
+export async function requireWritableCacheRoots(
+  roots: string[],
+  protectedRoots: string[],
+): Promise<string[]> {
+  requireRuntimeReadRoots(roots, protectedRoots);
+  for (const root of roots) await requireSharedCache(root);
+  return roots;
+}
+
+async function requireSharedCache(source: string): Promise<void> {
+  if (!isAbsolute(source) || (await realpath(source)) !== source)
+    throw new Error("runtime shared cache must be a canonical directory");
+  const info = await lstat(source);
+  if (!info.isDirectory() || info.uid !== userInfo().uid)
+    throw new Error("runtime shared cache must be an owned directory");
+  await access(source, constants.R_OK | constants.W_OK | constants.X_OK);
+}
+
+/** A slot aliases the operator-selected cache; its contents are never copied. */
+export async function linkSharedCaches(
+  policy: RuntimePolicy,
+  role: RuntimeRole,
+  root: string,
+): Promise<void> {
+  for (const cache of selectedSharedCaches(policy, role)) {
+    const target = join(root, cache.target);
+    try {
+      await symlink(cache.source, target, "dir");
+    } catch (cause) {
+      if ((cause as NodeJS.ErrnoException).code !== "EEXIST") throw cause;
+      await requireCacheSlot(target, cache.source, cause);
+    }
+  }
+}
+
+async function requireCacheSlot(
+  target: string,
+  source: string,
+  cause: unknown,
+): Promise<void> {
+  if (!(await lstat(target)).isSymbolicLink())
+    throw new Error("runtime shared cache slot was replaced", { cause });
+  if ((await realpath(target)) !== source)
+    throw new Error("runtime shared cache slot changed its source", { cause });
+}

package/src/{runtime-state.ts → runtime/state.ts}

@@ -1,17 +1,21 @@
 import { mkdir, realpath, stat } from "node:fs/promises";
 import { join } from "node:path";
 import {
-  requireRuntimeEnvironment,
+  requireRuntimePolicy,
   runtimeRoleSeeds,
   type RuntimeRole,
-  requireRuntimeSeedTargets,
   type RuntimePolicy,
-} from "./runtime-config";
-import { materializeRuntimeSeed } from "./runtime-seeds";
-import { requireRuntimeReadRoots } from "./runtime-paths";
-import { hashJson } from "./identity";
+} from "./config";
+import { materializeRuntimeSeed } from "./seeds";
+import { requireRuntimeReadRoots } from "./paths";
+import { hashJson } from "../identity";
+import {
+  linkSharedCaches,
+  sharedCacheRoots,
+  selectedSharedCaches,
+} from "./shared-cache";
 
-export type { RuntimeRole } from "./runtime-config";
+export type { RuntimeRole } from "./config";
 
 export function runtimeObservations(
   policy: RuntimePolicy | undefined,
@@ -29,6 +33,9 @@ export function runtimeObservations(
         environmentNames: Object.keys(policy.environment).sort(),
         readOnlyRoots: policy.readOnlyRoots,
         ...discoveryObservations(policy),
+        ...(policy.sharedCacheDirectories?.length
+          ? { sharedCacheDirectories: selectedSharedCaches(policy, role) }
+          : {}),
         seeds: runtimeRoleSeeds(policy, role).map((seed) => ({
           target: seed.target,
           sha256: seed.sha256,
@@ -57,16 +64,19 @@ function runtimeDigest(policy: RuntimePolicy): string {
   });
 }
 
-/** Each role gets private writable copies while the host inputs stay protected. */
+/** Private role state contains copied seeds and aliases to explicitly shared caches. */
 export async function prepareRuntimeState(
   workspace: string,
   policy: RuntimePolicy,
   role: RuntimeRole,
   privateRoot?: string,
 ) {
-  requireRuntimeEnvironment(policy.environment);
-  requireRuntimeSeedTargets(policy.seeds ?? []);
+  requireRuntimePolicy(policy);
   const root = await runtimeRoot(workspace, role, privateRoot);
+  const writableCacheRoots = await sharedCacheRoots(policy, role, [
+    workspace,
+    root,
+  ]);
   const home = join(root, "home"),
     temp = join(root, "tmp");
   await Promise.all(
@@ -74,6 +84,7 @@ export async function prepareRuntimeState(
   );
   for (const seed of runtimeRoleSeeds(policy, role))
     await copyRuntimeSeed(seed, join(root, seed.target));
+  await linkSharedCaches(policy, role, root);
   const environment = Object.fromEntries(
     Object.entries(policy.environment).map(([name, value]) => [
       name,
@@ -87,7 +98,13 @@ export async function prepareRuntimeState(
     UV_OFFLINE: "1",
     PYTHONDONTWRITEBYTECODE: "1",
   };
-  return { root, home, temp, environment: isolatedEnvironment };
+  return {
+    root,
+    home,
+    temp,
+    environment: isolatedEnvironment,
+    writableCacheRoots,
+  };
 }
 
 async function runtimeRoot(

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/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;
+}