@bjoernrochel/sevro 0.1.0-rc.8 → 1.1.0

package/dist/src/schema-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=schema-types.js.map

package/dist/src/schema-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-types.js","sourceRoot":"","sources":["schema-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { AdvisoryAssessment } from \"./advisory\";\nimport type {\n  ArtifactReference,\n  Assessment,\n  CheckOutcome,\n  Diagnostic,\n  DomainOutcome,\n  EvidenceRoute,\n  ExecutionStatus,\n  ExitCode,\n  GradingStatus,\n  MetricEvidence,\n  ObservationCompleteness,\n  ObservationEvidence,\n  OutcomeStatus,\n  RawResultReference,\n  TaskVerdict,\n  UsageEvidence,\n} from \"./contract-types\";\nimport type { IdentityDimensions } from \"./identity\";\nimport type { InstrumentationRequest } from \"./instrumentation\";\n\n/** Wire assessments additionally allow optional serialized error codes. */\nexport type WireAssessment = {\n  execution: Assessment[\"execution\"] & { errorCode?: string };\n  grading: Assessment[\"grading\"] & { errorCode?: string };\n  task: Assessment[\"task\"];\n};\n\n/** Validated v1 wire data also represents failures before run allocation. */\nexport type CliResultData = WireAssessment & {\n  format: \"sevro.cli-result.v1\";\n  runId: string | null;\n  exitCode: ExitCode;\n  evidencePath: string | null;\n  cases: Array<CliResultDataCase>;\n  diagnostic?: Diagnostic;\n};\nexport type CliResultDataTrial = WireAssessment & {\n  trial: number;\n  checks: Array<CheckOutcome>;\n  domainOutcomes?: Array<DomainOutcome>;\n  artifactPath: string | null;\n};\nexport type CliResultDataCase = WireAssessment & {\n  caseId: string;\n  trials: Array<CliResultDataTrial>;\n};\n\n/** Structural contracts for data validated by the versioned JSON schemas. */\nexport type RunEvidenceData = {\n  format: \"sevro.run-evidence.v1\";\n  runId: string;\n  evaluationIdentity: {\n    algorithm: \"sevro.identity.v1\";\n    digest: RunEvidenceDataDigest;\n    dimensions: IdentityDimensions;\n  };\n  configuration: {\n    digest: RunEvidenceDataDigest;\n    redacted: Record<string, unknown>;\n    resolved?: Record<string, unknown>;\n  };\n  runner: RunEvidenceDataRunner;\n  project: {\n    root: RunEvidenceDataFileUrl;\n    revision: string | null;\n    dirtyPatchDigest: RunEvidenceDataDigest | null;\n  };\n  extension: null | RunEvidenceDataExtension;\n  condition: {\n    requested: \"passive\" | \"enforced\";\n    actual: \"passive\" | \"enforced\" | \"unknown\";\n    requestedInstrumentation: InstrumentationRequest[];\n    appliedInstrumentation: InstrumentationRequest[];\n  };\n  graders: {\n    active: Array<RunEvidenceDataGrader>;\n    replacedDefaults: Array<string>;\n  };\n  routes: Array<EvidenceRoute>;\n  result: CliResultData;\n  trials: Array<RunEvidenceDataTrialEvidence>;\n  diagnostic?: Diagnostic;\n};\ntype RunEvidenceDataDigest = string;\ntype RunEvidenceDataFileUrl = string;\ntype RunEvidenceDataRunner =\n  | {\n      source: \"package\";\n      packageName: string;\n      version: string;\n      buildDigest: RunEvidenceDataDigest;\n    }\n  | {\n      source: \"checkout\";\n      root: RunEvidenceDataFileUrl;\n      revision: string;\n      dirtyPatchDigest: RunEvidenceDataDigest | null;\n      buildDigest: RunEvidenceDataDigest;\n    };\ntype RunEvidenceDataExtension = {\n  id: string;\n  version: string;\n  sourceDigest: RunEvidenceDataDigest;\n  configurationDigest: RunEvidenceDataDigest;\n  protocol: \"sevro.extension.v1\";\n  capabilities: Array<string>;\n  replacements: { graders: Array<string>; taskVerdictPolicy: string | null };\n};\ntype RunEvidenceDataGrader = {\n  id: string;\n  source: \"builtin\" | \"extension\";\n  version: string;\n};\nexport type AdvisoryReviewData = {\n  status: \"completed\" | \"failed\" | \"not_run\";\n  assessment: AdvisoryAssessment | null;\n  usage: UsageEvidence;\n  rawResult: RawResultReference;\n};\nexport type RunEvidenceDataTrialEvidence = {\n  caseId: string;\n  trial: number;\n  executionMode: \"executed\" | \"dry\" | \"unknown\";\n  candidateDurationMs?: number | null;\n  condition: {\n    requested: \"passive\" | \"enforced\";\n    actual: \"passive\" | \"enforced\" | \"unknown\";\n    appliedInstrumentation: InstrumentationRequest[];\n  };\n  observationCompleteness: ObservationCompleteness;\n  observations: Array<ObservationEvidence>;\n  metrics: Array<MetricEvidence>;\n  domainOutcomes?: Array<DomainOutcome>;\n  taskVerdictPolicy: null | {\n    id: string;\n    recommendation: TaskVerdict | null;\n  };\n  advisoryReview?: AdvisoryReviewData | null;\n  routes: Array<EvidenceRoute>;\n  usage: UsageEvidence;\n  rawResult: RawResultReference;\n  artifactRefs: Array<ArtifactReference>;\n};\nexport type ReportData = {\n  format: \"sevro.report.v1\";\n  inputs: Array<ReportDataInput>;\n  rows: Array<ReportDataRow>;\n  summary: {\n    cases: number;\n    passed: number;\n    failed: number;\n    notAssessed: number;\n  };\n};\ntype ReportDataPath = string;\ntype ReportDataDigest = string;\n/** The report wire schema deliberately allows either state family in rows. */\ntype ReportDataState = ExecutionStatus | GradingStatus;\ntype ReportDataInput = {\n  resultFile: ReportDataPath;\n  execution: ExecutionStatus;\n  grading: GradingStatus;\n  task: TaskVerdict;\n  exitCode: ExitCode;\n  caseCount: number;\n};\ntype ReportDataRoute = Omit<EvidenceRoute, \"role\">;\ntype ReportDataOutcome = {\n  trial: number;\n  id: string;\n  status: OutcomeStatus;\n};\ntype ReportDataRow = {\n  nativeTranscripts?: { retained: number; pruned: number };\n  resultFile: ReportDataPath;\n  evidencePath: string | null;\n  runId: string | null;\n  caseId: string;\n  execution: ReportDataState;\n  grading: ReportDataState;\n  task: TaskVerdict;\n  exitCode: ExitCode;\n  trialCount: number;\n  taskPassRate: number | null;\n  candidateDurationMs: number | null;\n  inputTokens: number | null;\n  outputTokens: number | null;\n  costUsd: number | null;\n  runnerBuildDigest: ReportDataDigest | null;\n  evaluationDigest: ReportDataDigest | null;\n  requestedCondition: \"passive\" | \"enforced\" | null;\n  actualCondition: \"passive\" | \"enforced\" | \"unknown\" | null;\n  candidateRoute: ReportDataRoute | null;\n  routes: Array<EvidenceRoute>;\n  domainOutcomes: Array<ReportDataOutcome>;\n};\n"]}

package/dist/src/schema.js

@@ -0,0 +1,16 @@
+import cliValidator from "./generated/cli-result.cjs";
+import runValidator from "./generated/run-evidence.cjs";
+import reportValidator from "./generated/report.cjs";
+export function assertCliResult(value) {
+    if (!cliValidator(value))
+        throw new Error("invalid Sevro CLI result");
+}
+export function assertRunEvidence(value) {
+    if (!runValidator(value))
+        throw new Error("invalid Sevro retained evidence");
+}
+export function assertReport(value) {
+    if (!reportValidator(value))
+        throw new Error("invalid Sevro report");
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["schema.ts"],"names":[],"mappings":"AAKA,OAAO,YAAY,mCAAmC;AACtD,OAAO,YAAY,qCAAqC;AACxD,OAAO,eAAe,+BAA+B;AAErD,MAAM,UAAU,eAAe,CAC7B,KAAc;IAEd,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,KAAc;IAEd,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;AAC/E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;AACvE,CAAC","sourcesContent":["import type {\n  CliResultData,\n  RunEvidenceData,\n  ReportData,\n} from \"./schema-types\";\nimport cliValidator from \"./generated/cli-result.cjs\";\nimport runValidator from \"./generated/run-evidence.cjs\";\nimport reportValidator from \"./generated/report.cjs\";\n\nexport function assertCliResult(\n  value: unknown,\n): asserts value is CliResultData {\n  if (!cliValidator(value)) throw new Error(\"invalid Sevro CLI result\");\n}\n\nexport function assertRunEvidence(\n  value: unknown,\n): asserts value is RunEvidenceData {\n  if (!runValidator(value)) throw new Error(\"invalid Sevro retained evidence\");\n}\n\nexport function assertReport(value: unknown): asserts value is ReportData {\n  if (!reportValidator(value)) throw new Error(\"invalid Sevro report\");\n}\n"]}

package/dist/src/shell.js

@@ -0,0 +1,5 @@
+/** Encode one literal argument for a POSIX shell, including empty strings. */
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+//# sourceMappingURL=shell.js.map

package/dist/src/shell.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["shell.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAO,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC;AAC/C,CAAC","sourcesContent":["/** Encode one literal argument for a POSIX shell, including empty strings. */\nexport function shellQuote(value: string): string {\n  return `'${value.replaceAll(\"'\", `'\"'\"'`)}'`;\n}\n"]}

package/dist/src/sqlite-lock.js

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

package/dist/src/sqlite-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-lock.js","sourceRoot":"","sources":["sqlite-lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,oBAAoB;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAO/C,iFAAiF;AACjF,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,YAAY,CAAgC,CAAC;QAC1E,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,OAAO;YACL,IAAI,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;YAChC,KAAK;gBACH,QAAQ,CAAC,KAAK,EAAE,CAAC;YACnB,CAAC;SACF,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,YAAY,EAAE,GACpB,OAAO,CAAC,aAAa,CAAiC,CAAC;IACzD,OAAO,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;AAChC,CAAC","sourcesContent":["import { createRequire } from \"node:module\";\n\nconst require = createRequire(import.meta.url);\n\ninterface LockDatabase {\n  exec(sql: string): unknown;\n  close(): void;\n}\n\n/** Both drivers use SQLite file locks, including across Node and Bun runners. */\nexport function openLockDatabase(path: string): LockDatabase {\n  if (process.versions.bun) {\n    const { Database } = require(\"bun:sqlite\") as typeof import(\"bun:sqlite\");\n    const database = new Database(path);\n    return {\n      exec: (sql) => database.run(sql),\n      close() {\n        database.close();\n      },\n    };\n  }\n  const { DatabaseSync } =\n    require(\"node:sqlite\") as typeof import(\"node:sqlite\");\n  return new DatabaseSync(path);\n}\n"]}

package/dist/src/storage.js

@@ -0,0 +1,21 @@
+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, value) {
+    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;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/src/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["storage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,yBAAyB;AACpE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,kBAAkB;AACpD,OAAO,EAAE,UAAU,EAAE,oBAAoB;AAEzC,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAY,EACZ,KAAc;IAEd,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACtD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,MAAM,CAAC,CAAC;IACzE,IAAI,CAAC;QACH,MAAM,SAAS,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE;YAChE,IAAI,EAAE,IAAI;YACV,IAAI,EAAE,KAAK;SACZ,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACxC,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC","sourcesContent":["import { mkdir, rename, unlink, writeFile } from \"node:fs/promises\";\nimport { basename, dirname, join } from \"node:path\";\nimport { randomUUID } from \"node:crypto\";\n\n/** Write a private JSON artifact and publish it with one atomic rename. */\nexport async function atomicWriteJson(\n  path: string,\n  value: unknown,\n): Promise<void> {\n  const parent = dirname(path);\n  await mkdir(parent, { recursive: true, mode: 0o700 });\n  const temporary = join(parent, `.${basename(path)}.${randomUUID()}.tmp`);\n  try {\n    await writeFile(temporary, `${JSON.stringify(value, null, 2)}\\n`, {\n      flag: \"wx\",\n      mode: 0o600,\n    });\n    await rename(temporary, path);\n  } catch (error) {\n    await unlink(temporary).catch(() => {});\n    throw error;\n  }\n}\n"]}

package/dist/src/transcript-retention.js

@@ -0,0 +1,109 @@
+import { readFile, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { canonicalJson, sha256 } from "./identity.js";
+import { retainedFile } from "./results-lock.js";
+import { atomicWriteJson } from "./storage.js";
+function isNativeTranscript(artifact) {
+    return /^(?:sevro\.(?:semantic(?:\.[a-f0-9]{64})?|advisory)\.)?sevro\.native-transcripts\.bundle$/.test(artifact.id);
+}
+function transcriptArtifacts(evidence) {
+    return evidence.trials.flatMap((trial) => trial.artifactRefs.filter(isNativeTranscript).map((artifact) => ({
+        caseId: trial.caseId,
+        trial: trial.trial,
+        ...artifact,
+    })));
+}
+function pruningRecord(evidence) {
+    return {
+        format: "sevro.pruned-native-transcripts.v1",
+        runId: evidence.runId,
+        artifacts: transcriptArtifacts(evidence),
+    };
+}
+function pruningPath(evidence) {
+    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, artifact) {
+    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) {
+    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 != null)
+        .map((path) => fileURLToPath(path));
+}
+function metadataPaths(evidence) {
+    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, artifact) {
+    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) {
+    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) {
+    const path = pruningPath(evidence);
+    const marked = await retainedFile(path);
+    if (marked) {
+        const receipt = 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) {
+    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;
+}
+//# sourceMappingURL=transcript-retention.js.map

package/dist/src/transcript-retention.js.map

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

package/dist/src/value-guards.js

@@ -0,0 +1,26 @@
+/** Narrow JSON containers before accessing untrusted members. */
+export function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function requireRecord(value, message) {
+    if (!isRecord(value))
+        throw new Error(message);
+    return value;
+}
+export function validQualifiedId(value) {
+    return (typeof value === "string" &&
+        /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/.test(value));
+}
+export function containsControl(value) {
+    return Array.from(value).some((character) => character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f);
+}
+export function isUnknownArray(value) {
+    return Array.isArray(value);
+}
+export function isStringArray(value) {
+    return (isUnknownArray(value) && value.every((item) => typeof item === "string"));
+}
+export function isOptionalNonblankString(value) {
+    return (value === undefined || (typeof value === "string" && Boolean(value.trim())));
+}
+//# sourceMappingURL=value-guards.js.map

package/dist/src/value-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value-guards.js","sourceRoot":"","sources":["value-guards.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAc,EACd,OAAe;IAEf,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/C,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC7C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,oCAAoC,CAAC,IAAI,CAAC,KAAK,CAAC,CACjD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAC3B,CAAC,SAAS,EAAE,EAAE,CACZ,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,IAAI,CACrE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,CACL,cAAc,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CACzE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,KAAc;IACrD,OAAO,CACL,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAC5E,CAAC;AACJ,CAAC","sourcesContent":["/** Narrow JSON containers before accessing untrusted members. */\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nexport function requireRecord(\n  value: unknown,\n  message: string,\n): Record<string, unknown> {\n  if (!isRecord(value)) throw new Error(message);\n  return value;\n}\n\nexport function validQualifiedId(value: unknown): value is string {\n  return (\n    typeof value === \"string\" &&\n    /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/.test(value)\n  );\n}\n\nexport function containsControl(value: string): boolean {\n  return Array.from(value).some(\n    (character) =>\n      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,\n  );\n}\n\nexport function isUnknownArray(value: unknown): value is unknown[] {\n  return Array.isArray(value);\n}\n\nexport function isStringArray(value: unknown): value is string[] {\n  return (\n    isUnknownArray(value) && value.every((item) => typeof item === \"string\")\n  );\n}\n\nexport function isOptionalNonblankString(value: unknown): boolean {\n  return (\n    value === undefined || (typeof value === \"string\" && Boolean(value.trim()))\n  );\n}\n"]}

package/docs/README.md

@@ -1,22 +1,25 @@
 # Sevro documentation
 
-<img src="assets/sevro-wordmark.svg" alt="Sevro wordmark" width="220">
+<img src="https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-wordmark.svg" alt="Sevro wordmark" width="220">
 
 Start with the task you want to complete. These pages work without an agent.
 
-| I want to…                                    | Read                                                     |
-| --------------------------------------------- | -------------------------------------------------------- |
-| Get a result without a model account          | [Your first evaluation](getting-started.md)              |
-| Install, update, remove, or use a checkout    | [Installation](installing.md)                            |
-| Run evaluations and select a host             | [Running evaluations](running-evaluations.md)            |
-| Create cases and reusable policy              | [Cases and extensions](creating-cases.md)                |
-| Interpret verdicts, evidence, and comparisons | [Reading results](reading-results.md)                    |
-| Run Codex or Claude with isolation            | [Native hosts](native-hosts.md)                          |
-| Reuse host tools or enable goals and hooks    | [Runtime configuration](runtime-v1.md)                   |
-| Resolve a symptom                             | [Troubleshooting](troubleshooting.md)                    |
-| Understand runner responsibilities            | [Architecture](architecture.md)                          |
-| Change Sevro or its documentation             | [Contributing](../CONTRIBUTING.md)                       |
-| Understand licensing and branding             | [Licensing](licensing.md) and [assets](assets/README.md) |
+| I want to…                                     | Read                                                     |
+| ---------------------------------------------- | -------------------------------------------------------- |
+| Get a result without a model account           | [Your first evaluation](getting-started.md)              |
+| Initialize, prepare, run and iterate           | [Evaluation workflow](evaluation-workflow.md)            |
+| Install, update, remove, or use a checkout     | [Installation](installing.md)                            |
+| Run evaluations and select a host              | [Running evaluations](running-evaluations.md)            |
+| Create cases and reusable policy               | [Cases and extensions](creating-cases.md)                |
+| Copy a complete coding, skill or runtime setup | [Runnable recipes](recipes.md)                           |
+| Interpret verdicts, evidence, and comparisons  | [Reading results](reading-results.md)                    |
+| Run Codex or Claude with isolation             | [Native hosts](native-hosts.md)                          |
+| Reuse host tools or enable goals and hooks     | [Runtime configuration](runtime-v1.md)                   |
+| Save recurring evaluation selections           | [Run settings](run-settings-v1.md)                       |
+| Resolve a symptom                              | [Troubleshooting](troubleshooting.md)                    |
+| Trace runner lifecycle, ownership, and changes | [Architecture](architecture.md)                          |
+| Change Sevro or its documentation              | [Contributing](../CONTRIBUTING.md)                       |
+| Understand licensing and branding              | [Licensing](licensing.md) and [assets](assets/README.md) |
 
 ## Ask the guide
 
@@ -30,11 +33,12 @@ It belongs to this repository, not an npm installation.
 
 [Current contracts](contracts.md) define interfaces. The
 [guide specification](specs/repository-guide.md) defines the repository assistant.
-[Historical validation](evidence.md) records observations, not current guarantees.
+[Historical validation](https://github.com/BjRo/sevro/blob/main/docs/evidence.md) records observations, not current guarantees.
 There is no accepted Rust migration decision here;
 [issue #2](https://github.com/BjRo/sevro/issues/2) tracks research.
 
 Read [documentation quality](documentation-quality.md),
+[the usability study protocol](https://github.com/BjRo/sevro/blob/main/docs/usability-study.md),
 [guide evaluation](guide-evaluation.md), [releases](releases.md), and
 [acknowledgements](acknowledgements.md) for maintenance.
 Return to the [Sevro introduction](../README.md).

package/docs/architecture.md

@@ -4,22 +4,146 @@ Sevro owns generic execution/evidence contracts. Projects own cases and policy.
 This lets Darrow and other integrations use the same runner without importing
 their benchmark policy into it.
 
-| Responsibility                                    | Sources                                                                                                            |
-| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| Parse commands/select explicit routes             | [CLI](../src/cli.ts), [CLI reference](development-cli.md)                                                          |
-| Prepare, execute, grade, retain, clean up         | [Engine](../src/engine.ts), [engine slice](engine-slice.md)                                                        |
-| Negotiate trusted extension calls                 | [Client](../src/extension-client.ts), [session](../src/extension-session.ts), [protocol](extension-protocol-v1.md) |
-| Run native hosts and retain bounded observations  | [Codex](codex-host.md), [native controls](native-controls.md), [host sources](../src/hosts/)                       |
-| Reduce execution/grading/task states              | [Result source](../src/results.ts), [contract](results-v1.md)                                                      |
-| Bind comparison identities and release provenance | [Identity](identity-v1.md), [releases](releases.md)                                                                |
-| Summarize retained results                        | [Report](report-v1.md)                                                                                             |
-
-Completed evidence is retained before cleanup. Missing observations remain
-unavailable; unknown measurements do not become zero. Extensions cannot
-silently replace isolation/persistence or built-in policy. The
+This page explains Sevro's implementation and points to acceptance
+tests for changes. [Current contracts](contracts.md) define public behavior;
+[historical validation](https://github.com/BjRo/sevro/blob/main/docs/evidence.md) records bounded past observations. The
+[engine slice](https://github.com/BjRo/sevro/blob/main/docs/engine-slice.md) retains its earlier scope and detailed lifecycle
+explanation. Implementation paths and test scenarios here are navigation, not
+evidence that a particular candidate passed validation.
+
+[`engine.ts`](../src/engine.ts) remains the programmatic facade, and
+[`cli.ts`](../src/cli.ts) builds to the installed `dist/src/cli.js` entrypoint.
+The package runs on Node.js and Bun; contributor commands still use Bun.
+[Process adapters](../src/runtime-process.ts) normalize child processes and
+Web Streams. [SQLite locking](../src/sqlite-lock.ts) selects the runtime's native driver, preserving shared file-lock semantics. The CLI
+loads and assembles evaluation options; evaluation modules coordinate the run
+and its trials.
+
+## Evaluation lifecycle
+
+[`runEvaluation`](../src/evaluation/run.ts) prepares inputs before allocating
+run resources, retains preparation artifacts, and reserves candidate and
+semantic workspace roots as needed before calling the trial scheduler. The map
+follows the path of a retained trial; individual stages can be skipped or fail.
+
+```mermaid
+flowchart TD
+    P["Validate and prepare evaluation inputs"] --> R["Allocate run storage and owner; reserve workspace roots"]
+    R --> W["Admit trial and materialize its reserved fixture"]
+    subgraph Trial["Each admitted trial"]
+        W --> C["Initialize grading bases; execute candidate"]
+        C --> E["Retain candidate artifacts; observe output; prepare grading views"]
+        E --> G["Output, shell, Git, semantic, and extension grading"]
+        G --> A["Assess execution, grading, and task separately"]
+        A --> V["Optional independent advisory review"]
+        V --> T["Retain raw candidate response; atomically write trial evidence"]
+        T --> K["Collect completed trial and checkpoint its reference"]
+        K --> D["Release temporary views; clear or retain fixture contents"]
+    end
+    D --> J["All admitted trials drain"]
+    J --> F["Write final run evidence; finalize owner checkpoint"]
+    F --> X["Finalize retained workspaces; release other reservations"]
+```
+
+[`scheduleTrials`](../src/evaluation/scheduler.ts) bounds active work by the
+prepared job limit. It admits a trial before
+[`prepareTrialWorkspace`](../src/evaluation/resources.ts) materializes that
+trial's fixture. Each [`EvaluationTrial`](../src/evaluation/trial.ts) owns its
+mutable state and writer. Its `run()` method keeps candidate execution,
+artifact retention, grading, assessment, advisory review, persistence, and
+cleanup in one visible order. Grading helpers return checks, observations,
+and failures; the coordinator incorporates those results and stops new
+admission when an execution or required grading error is detected, before
+advisory work, persistence, or cleanup. The scheduler also stops admission on
+cancellation and waits for active workers. A failed task check alone does not
+close admission. Already admitted peers drain and retain their evidence, including
+when they finish out of order.
+
+[`runAdvisoryReview`](../src/evaluation/advisory.ts) handles its own host call,
+assessment, retained response, and auxiliary workspace cleanup. It depends on
+candidate completion, independently of the task assessment. The
 [advisory fixture](advisory-fixture.md) gives review a separate Git view with
-evaluator inputs withheld.
+evaluator inputs withheld. Its recommendation or host failure does not change
+task grading; a failure to retain its evidence remains a persistence error.
+
+Successful [semantic response parsing](../src/evaluation/semantic.ts) clears
+auxiliary fixture contents; successful advisory response parsing removes its
+auxiliary fixture. Both retain response evidence first, including valid failed
+check verdicts or advisory recommendations.
+
+The [trial writer](../src/evidence/trial-writer.ts) writes the trial artifact
+before the coordinator marks it persisted and hands it to the
+[result collector](../src/evaluation/collection.ts). The collector registers
+the completed record, orders records by trial number, and checkpoints retained
+artifact paths. After active work drains, the run coordinator validates and
+writes `run.json` before finalizing the owner as complete or interrupted.
+Persistence failures cannot produce a successful result; the run's failure
+path attempts a diagnostic checkpoint while preserving the original failure.
+
+Trial cleanup releases candidate artifact runtimes and transcript views even
+when the trial fails. Persisted successful fixture contents are cleared while
+their empty reserved roots remain until active work drains. Failed, cancelled,
+grading-error, unavailable-evidence, and failed-task fixtures are retained;
+[workspace ownership](../src/fixtures/workspace-state.ts) tracks their inactive
+retention and startup expiry after 24 hours. Saved evidence stays outside that
+cleanup. See the [results retention contract](results-v1.md#identity-and-provenance)
+for the public boundary, including ownership that cannot be verified.
+
+Dry preparation still validates and materializes fixtures, including declared
+fixture setup, and retains trial records. It skips candidate execution and
+grading, recording `not_run` / `not_requested` / `not_assessed`, as exercised by
+the [engine trial suite](../tests/src/engine-trials.test.ts). Missing observations
+remain unavailable; missing required evidence cannot become a pass. Optional
+unknown measurements remain unknown rather than becoming zero. Extensions
+cannot silently replace isolation, persistence,
+or built-in policy. The [results](results-v1.md) and
+[extension protocol](extension-protocol-v1.md) contracts define those semantics.
+
+## State ownership
+
+[`EvaluationContext`](../src/evaluation/context.ts) carries four explicit
+collaborators: prepared inputs, run resources, the result collector, and retained
+preparation-artifact references. It does not combine mutable trial fields with
+the preparation plan.
+
+| Data or state                  | Owner                                                                                                                                                           | Boundary                                                                                                                                                                                                                                                                          |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Prepared inputs                | [`PreparedEvaluation` in `plan.ts`](../src/evaluation/plan.ts)                                                                                                  | Named fixture, check, and invocation groups plus routes, provenance, redacted configuration, and comparison identity. Preparation completes before run allocation.                                                                                                                |
+| Run resources and reservations | [`RunResources` and `RunWorkspaceReservations` in `resources.ts`](../src/evaluation/resources.ts)                                                               | Run ID, evidence/state locations, process owner, and candidate/semantic reservations. Reservations outlive completed fixture contents; retained workspaces are tracked separately from completed roots.                                                                           |
+| Mutable trial state            | [`TrialRuntimeState` and `EvaluationTrial` in `trial.ts`](../src/evaluation/trial.ts)                                                                           | Candidate result, observations, checks, assessment, temporary views, advisory result, and persisted milestone belong to one admitted trial. Grading receives narrow inputs and explicit effects rather than this state object.                                                    |
+| Collected run results          | [`ResultCollector` in `collection.ts`](../src/evaluation/collection.ts)                                                                                         | Private completed summaries, evidence, and diagnostics; trial-number ordering, snapshots for aggregation, and checkpoint requests. [`run-owner.ts`](../src/run-owner.ts) verifies process ownership and writes owner/checkpoint state.                                            |
+| Evidence writes                | [`TrialEvidenceWriter`](../src/evidence/trial-writer.ts), [preparation retention](../src/evaluation/resources.ts), [run finalization](../src/evaluation/run.ts) | The trial writer owns filenames, private writes, hashes, artifact references, and typed trial-persistence failures. Resource helpers retain preparation bytes; run finalization writes aggregate evidence. [`storage.ts`](../src/storage.ts) supplies atomic private JSON writes. |
+
+Fixture modules own materialization and workspace preparation. Runtime modules
+own declared host runtime policy and private state. Evidence modules validate
+host observations and artifacts, verify retained bytes, and normalize optional
+usage without constructing fixtures. Native host implementations and graders
+remain in their own families.
+
+## Where to change behavior
+
+Start with the responsibility, then inspect its observable acceptance scenarios.
+These are useful starting suites, not an exhaustive validation list. The
+[contribution checks](../CONTRIBUTING.md#quality-contract-and-checks) still govern
+candidate acceptance.
+
+| Responsibility                                                    | Implementation and reference                                                                                                                                                                                                                                                             | Relevant acceptance tests                                                                                                                                                                                                         |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Parse commands/select explicit routes                             | [CLI entrypoint](../src/cli.ts), [invocation parsing](../src/cli/invocation.ts), [CLI reference](development-cli.md)                                                                                                                                                                     | [Invalid invocations](../tests/src/cli/invocation-validation.test.ts)                                                                                                                                                             |
+| Load and prepare a CLI evaluation                                 | [Input loading](../src/cli/loading.ts), [preparation](../src/cli/preparation.ts), [host construction](../src/cli/hosts.ts), [extension resolution](../src/cli/extension.ts), [evaluation assembly](../src/cli/evaluation.ts)                                                             | [Case/configuration validation](../tests/src/cli/case-validation.test.ts)                                                                                                                                                         |
+| Present CLI results and own cancellation                          | [Presentation](../src/cli/presentation.ts), [cancellation](../src/cli/cancellation.ts), [command lifecycle](../src/cli/command.ts)                                                                                                                                                       | [CLI states and exits](../tests/src/cli/results.test.ts), [signal retention](../tests/src/cli/trial-retention.test.ts)                                                                                                            |
+| Prepare evaluation inputs and grade trials                        | [Engine facade](../src/engine.ts), [plan](../src/evaluation/plan.ts), [grading](../src/evaluation/grading.ts), [semantic grading](../src/evaluation/semantic.ts), [evaluation modules](../src/evaluation/), [engine slice](https://github.com/BjRo/sevro/blob/main/docs/engine-slice.md) | [Preparation refusals](../tests/src/evaluation/preparation-validation.test.ts), [semantic grading failures](../tests/src/evaluation/semantic-grading-failures.test.ts), [engine lifecycle](../tests/src/engine-lifecycle.test.ts) |
+| Schedule trials, retain evidence, and finalize ownership          | [Scheduler](../src/evaluation/scheduler.ts), [trial coordinator](../src/evaluation/trial.ts), [reservations](../src/evaluation/resources.ts), [collection](../src/evaluation/collection.ts), [run owner](../src/run-owner.ts)                                                            | [Concurrent admission and ordering](../tests/src/cli/concurrency.test.ts), [trial failures and retention](../tests/src/evaluation/trial-retention.test.ts), [checkpoint refusals](../tests/src/run-owner-checkpoints.test.ts)     |
+| Prepare, construct, and clean up fixtures                         | [Fixture modules](../src/fixtures/), [construction](../src/fixtures/create.ts), [preparation artifacts](../src/fixtures/preparation.ts), [content cleanup](../src/fixtures/cleanup.ts), [workspace ownership](../src/fixtures/workspace-state.ts)                                        | [Artifact preparation](../tests/src/fixtures/artifact-preparation.test.ts), [workspace lifecycle](../tests/src/fixtures/workspace-lifecycle.test.ts)                                                                              |
+| Resolve runtime policy, discovery, and private state              | [Runtime modules](../src/runtime/), [configuration](../src/runtime/config.ts)                                                                                                                                                                                                            | [Runtime environment](../tests/src/runtime/environment.test.ts), [candidate artifact lifetime](../tests/src/candidate-artifacts.test.ts)                                                                                          |
+| Validate host results and retain bounded evidence                 | [Host results](../src/evidence/host-results.ts), [trial writer](../src/evidence/trial-writer.ts), [retained artifacts](../src/evidence/retained-artifacts.ts), [usage](../src/evidence/usage.ts)                                                                                         | [Host evidence refusals](../tests/src/evaluation/host-evidence.test.ts), [failed-host evidence retention](../tests/src/evaluation/trial-retention.test.ts)                                                                        |
+| Negotiate trusted extension calls                                 | [Client](../src/extension-client.ts), [session](../src/extension-session.ts), [extension grading](../src/evaluation/grading.ts), [protocol](extension-protocol-v1.md)                                                                                                                    | [Negotiated engine behavior](../tests/src/evaluation/extension-engine.test.ts), [extension grading outcomes](../tests/src/evaluation/extension-grading.test.ts)                                                                   |
+| Run independent advisory review                                   | [Advisory execution](../src/evaluation/advisory.ts), [blind fixture](../src/fixtures/advisory.ts), [advisory fixture explanation](advisory-fixture.md)                                                                                                                                   | [Advisory failures](../tests/src/evaluation/advisory-failures.test.ts), [blind change view](../tests/src/fixtures/advisory.test.ts)                                                                                               |
+| Run native hosts and retain bounded observations                  | [Codex](codex-host.md), [native controls](native-controls.md), [host sources](../src/hosts/), [shared process mechanics](../src/process-lifecycle.ts), [native waiting](../src/hosts/process-lifecycle.ts)                                                                               | [Native process admission and byte bounds](../tests/src/hosts/native-process-boundaries.test.ts)                                                                                                                                  |
+| Reduce execution/grading/task states and maintain contract shapes | [Result reduction](../src/results.ts), [shared semantic types](../src/contract-types.ts), [wire types](../src/schema-types.ts), [runtime schema boundary](../src/schema.ts), [results contract](results-v1.md)                                                                           | [State and exit precedence](../tests/src/results.test.ts), [evidence schema boundaries](../tests/src/schema/evidence-boundaries.test.ts)                                                                                          |
+| Bind comparison identities and release provenance                 | [Preparation identity inputs](../src/evaluation/plan.ts), [identity hashing](../src/identity.ts), [provenance](../src/provenance.ts), [identity contract](identity-v1.md), [releases](releases.md)                                                                                       | [CLI identity](../tests/src/cli/identity.test.ts), [package release provenance](../tests/scripts/release.test.ts)                                                                                                                 |
+| Summarize retained results                                        | [Report implementation](../src/report.ts), [report contract](report-v1.md)                                                                                                                                                                                                               | [Report states and CLI](../tests/src/report.test.ts)                                                                                                                                                                              |
 
-These paths describe this checkout. [Historical validation](evidence.md) records
-bounded past observations. [Rust research](https://github.com/BjRo/sevro/issues/2)
-does not establish a migration; public interfaces remain useful independently.
+[Rust research](https://github.com/BjRo/sevro/issues/2) does not establish a
+migration; public interfaces remain useful independently. Return to the
+[documentation hub](README.md).

package/docs/assets/README.md

@@ -1,11 +1,12 @@
 # Sevro brand assets
 
 Björn Rochel created the supplied logo in 2026. Its original artwork and white
-background are preserved in `sevro-logo.png`.
+background are preserved in `sevro-logo.png` in the repository. The npm package
+retains these permissions; download the artwork from the links below.
 
-- [Full logo](sevro-logo.png): supplied 1254 × 1254 PNG including the wordmark.
-- [Compact symbol](sevro-symbol.svg): the same artwork framed around the S track.
-- [Wordmark](sevro-wordmark.svg): the same artwork framed around the name.
+- [Full logo](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-logo.png): supplied 1254 × 1254 PNG including the wordmark.
+- [Compact symbol](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-symbol.svg): the same artwork framed around the S track.
+- [Wordmark](https://raw.githubusercontent.com/BjRo/sevro/main/docs/assets/sevro-wordmark.svg): the same artwork framed around the name.
 
 SVG variants embed the supplied PNG; they are not traced vector redrawings.
 Keep a white backing on dark pages; no transparent variant is claimed. Use the

package/docs/builtin-graders-v1.md

@@ -38,8 +38,10 @@ The shell-check process runner accepts a bounded evaluator-owned `run` string,
 optional `expectedExitCode` and `timeoutMs`, plus `expectExact`, `expectRegex`,
 `notRegex`, and regex `flags` for stdout. Exact matching removes one final
 newline; regex matching always uses multiline mode. The runner executes with
-`sh -e`. On macOS and Linux it runs through the outer sandbox with network access denied,
-a credential-free environment, and caller-declared protected roots. Without a
+`sh -e`. On macOS and Linux it runs through the outer sandbox with network access denied
+by default, a credential-free environment, and caller-declared protected roots.
+The runtime [local HTTP option](runtime-v1.md#local-http-test-servers) permits
+socket-using upstream tests while retaining outbound isolation. Without a
 stdout assertion, process output is discarded. With one, the runner captures
 at most 1 MiB in memory and retains only its digest and byte length. Oversized
 or invalid UTF-8 output is a grading error.
@@ -54,6 +56,11 @@ include any other source worktrees or private roots. A peer path already
 canonicalized by the engine remains in the deny profile if that peer is
 removed before the sandbox starts; unverified missing roots still fail.
 
+On macOS, validated runtime grants also permit limited
+[ancestor metadata reads](runtime-v1.md#macos-ancestor-metadata) so libc can
+canonicalize granted paths. Protected ancestor listings and ungranted sibling
+data remain inaccessible.
+
 `sevro.git-head` accepts `kind: "changed"`, `"unchanged"`, or
 `"base-ancestor"` for a generated or repository Git fixture. The engine
 captures the fixture's base HEAD before the candidate turn, then compares the