gstack/lib/cso/contracts.ts

/** CSO's versioned, host-independent evidence contract. Runtime claims are helper-owned. */
import { createHash } from 'node:crypto';

export const ABI = 3;
export const MAX_OUTPUT = 1024 * 1024;
const UNSAFE_STRING_CONTROLS =
  /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/u;
const UNSAFE_PROPERTY_CONTROLS = /[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028-\u202e\u2066-\u2069]/u;
export type Completeness = 'complete' | 'partial' | 'not assessed';
export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'informational';
export type ErrorCode =
  | 'INVALID_ARGUMENT'
  | 'INVALID_SCHEMA'
  | 'MISSING_INPUT'
  | 'SNAPSHOT_RACE'
  | 'UNSAFE_PATH'
  | 'REDACTION_FAILED'
  | 'PERSISTENCE_FAILED'
  | 'TOOL_UNAVAILABLE'
  | 'TOOL_FAILED'
  | 'ISOLATION_FAILED'
  | 'INSUFFICIENT_CAPACITY'
  | 'DEADLINE'
  | 'CANCELLED'
  | 'PREREQUISITE'
  | 'INCOMPATIBLE_INPUT'
  | 'ASSERTION_FAILED';
export class CsoError extends Error {
  constructor(
    public code: ErrorCode,
    message: string,
  ) {
    super(message);
    this.name = 'CsoError';
  }
}
export const sha256 = (value: string | Buffer): string => createHash('sha256').update(value).digest('hex');
export const canonical = (value: unknown): string => {
  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
  if (value && typeof value === 'object')
    return `{${Object.keys(value)
      .sort()
      .map((k) => `${JSON.stringify(k)}:${canonical((value as any)[k])}`)
      .join(',')}}`;
  return JSON.stringify(value);
};
export interface CoverageRecord {
  domain: string;
  scope: string;
  status: 'assessed' | 'partial' | 'not_assessed' | 'not_applicable';
  method: string;
  gaps: string[];
  exclusions: string[];
  evidence: string[];
  tool?: { name: string; version: string; freshness: string; outcome: string };
}
export interface ApplicationModel {
  actors: string[];
  assets: string[];
  entrypoints: string[];
  tenantBoundaries: string[];
  sensitiveOperations: string[];
  invariants: string[];
}
export interface FindingV3 {
  id: string;
  fingerprint: string;
  title: string;
  rootCause: string;
  location: { path: string; line: number; symbol: string };
  advisoryIds: string[];
  severity: Severity;
  confidence: 'high' | 'medium' | 'low';
  confidenceRationale: string;
  evidence: 'supported' | 'hypothesis' | 'legacy_review';
  attackerControl: string;
  impact: string;
  scenario: string;
  trace: string[];
  references: string[];
  recommendation: string;
  challenge: {
    reviewer: string;
    independent: boolean;
    mode: 'independent_agent' | 'sequential_fallback';
    callers: string;
    controls: string;
    counterevidence: string;
    conclusion: string;
  };
  dependency?: {
    affectedVersion: string;
    reachability: 'reachable' | 'unreachable' | 'unknown';
    exposure: string;
    exploitation: string;
  };
  reproduction: 'not_attempted' | 'blocked' | 'inconclusive' | 'disproved' | 'reproduced';
  repair: 'not_attempted' | 'proposed' | 'failed' | 'runtime_tested' | 'tested';
  closure: 'open' | 'resolved' | 'unknown';
  verificationId?: string;
  reproductionAttemptId?: string;
  verificationAssurance?: {
    assertions: 'authenticated_out_of_process';
    testCompletion: 'self_reported' | 'authenticated_out_of_process';
    review: 'self_attested' | 'host_verified';
  };
}
export interface RunPolicy {
  mode: 'daily' | 'comprehensive';
  scope: string;
  diff: boolean;
  base: string;
  offline: boolean;
  budgetSeconds: number;
  maxWorkers: 3;
  maxRepairs: 3;
}
export interface RunReportV3 {
  schemaVersion: 3;
  runId: string;
  repoId: string;
  createdAt: string;
  deadline: string;
  status: 'running' | 'finished' | 'interrupted';
  completeness: Completeness;
  policy: RunPolicy;
  source: {
    root: string;
    snapshotHash: string;
    originalHash: string;
    baseCommit?: string;
    transformations?: Array<{ path: string; handling: string }>;
  };
  application: ApplicationModel;
  coverage: CoverageRecord[];
  findings: FindingV3[];
  gaps: string[];
  events: { at: string; kind: string; message: string }[];
  parent?: { runId: string; findingId: string; kind: 'recheck' };
  modelUsage?: { source: string; tokens: number; cost?: number };
}
export interface SnapshotEntry {
  path: string;
  pathId: string;
  originalHash: string;
  executionHash?: string;
  bytes: number;
  mode: number;
  transformation?: string;
}
export interface SnapshotPathIdentity {
  path: string;
  pathId: string;
}
export interface SnapshotManifest {
  version: 3;
  createdAt: string;
  expiresAt: string;
  root: string;
  originalHash: string;
  executionHash: string;
  entries: SnapshotEntry[];
  deletedPaths?: SnapshotPathIdentity[];
  headCommit?: string;
  baseCommit?: string;
  changedPaths?: string[];
}
export interface HttpAssertion {
  name: string;
  path: string;
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
  headers?: Record<string, string>;
  body?: string;
  expected: { status: number; includes?: string; excludes?: string };
  vulnerable?: { status: number; includes?: string; excludes?: string };
}
export interface Command {
  executable: string;
  args: string[];
}
export interface VerificationRequest {
  findingId: string;
  runtimeProfile: string;
  port: number;
  start: Command;
  legitimate: HttpAssertion[];
  security: HttpAssertion;
  existingTests: Command[];
  fixtures: Record<string, string>;
  boundaryFiles: string[];
  testFiles: string[];
  changes: {
    path: string;
    beforeSha256: string | null;
    after: string | null;
    effect: 'source' | 'configuration' | 'dependency';
  }[];
  review: {
    reviewer: string;
    independent: boolean;
    rootCauseRepaired: boolean;
    featurePreserved: boolean;
    boundaryMocks: boolean;
    rationale: string;
    reviewedPatchHash: string;
    artifactId?: string;
  };
}
export interface RepairReviewArtifact {
  schemaVersion: 3;
  id: string;
  runId: string;
  findingId: string;
  createdAt: string;
  producer: string;
  reviewer: string;
  assurance: 'self_attested' | 'host_verified';
  requestHash: string;
  patchHash: string;
  rootCauseRepaired: boolean;
  featurePreserved: boolean;
  boundaryMocks: boolean;
  rationale: string;
}
export interface RecheckEvidenceV3 {
  kind: 'caller' | 'security_boundary';
  path: string;
  line: number;
  observation: string;
}
export interface SubmissionV3 {
  application?: ApplicationModel;
  findings?: unknown[];
  coverage?: unknown[];
  gaps?: string[];
  modelUsage?: { source: string; tokens: number; cost?: number };
  recheck?: {
    findingId: string;
    outcome: 'open' | 'resolved' | 'unknown';
    evidence: RecheckEvidenceV3[];
    rootCause: string;
  };
}
export interface VerificationObservation {
  booted: boolean;
  legitimate: boolean;
  security: 'pass' | 'intended_failure' | 'inconclusive';
  existingTests: boolean;
  output: string;
  inputHash: string;
}
export interface AssertionWitnessBinding {
  schemaVersion: 1;
  protocol: 'gstack-cso-assertion-witness-v1';
  nonce: string;
  phase: 'before' | 'after';
  issuedAt: string;
  expiresAt: string;
  runId: string;
  findingId: string;
  policyHash: string;
  auditPolicyHash: string;
  runtime: { image: string; verifierImage: string; platform: string; profile: string };
  runner: {
    testToolchain: 'runtime' | 'project';
    startPlanHash: string;
    testPlanHash: string;
    commandsHash: string;
    minimumPassingTestsHash: string;
  };
  sourceHash: string;
  dependencyHash: string;
  configurationHash: string;
  requestHash: string;
  patchHash: string;
  harnessHash: string;
  assertionHash: string;
  fixturesHash: string;
}
export interface AssertionWitnessReceipt {
  schemaVersion: 1;
  binding: AssertionWitnessBinding;
  keyId: string;
  publicKey: string;
  observationHash: string;
  externalAssertionsPassed: boolean;
  diagnosticTestsPassed: boolean;
  executions: Array<{
    commandHash: string;
    exitCode: number;
    outputHash: string;
    minimumPassingTests: number;
    executedTests: number;
    passingTests: number;
    reportedPassed: boolean;
  }>;
  signature: string;
}
export interface PreparationProof {
  schemaVersion: 1;
  dependencyClosureHash: string;
  configurationHash: string;
  sourceProjectionHash: string;
  preparedManifestHash: string;
  preparedDependencyHash: string;
  receiptHash: string;
  executionEnvironmentHash: string;
  databaseHash: string;
  transformations: Array<{ path: string; sha256: string; mode: number; reason: string }>;
}
export interface VerificationManifest {
  version: 3;
  id: string;
  runId: string;
  findingId: string;
  createdAt: string;
  helperAbi: 3;
  runtime: { image: string; platform: string; profile: string };
  testToolchain: 'runtime' | 'project';
  policyHash: string;
  harnessHash: string;
  requestHash: string;
  startPlanHash: string;
  testPlanHash: string;
  fixturesHash: string;
  patchHash: string;
  auditPolicyHash: string;
  originalSourceHash: string;
  transformationsHash: string;
  archivesHash: string;
  preparationHash?: string;
  beforeSourceHash: string;
  afterSourceHash: string;
  beforeDependencies: string;
  afterDependencies: string;
  beforeConfiguration: string;
  afterConfiguration: string;
  before: VerificationObservation;
  after: VerificationObservation;
  review: VerificationRequest['review'];
  reviewAssurance: 'self_attested' | 'host_verified';
  assertionAssurance?: 'authenticated_out_of_process';
  testCompletionAssurance: 'self_reported' | 'authenticated_out_of_process';
  witnessHash?: string;
  result: 'runtime_tested' | 'tested' | 'failed' | 'inconclusive';
}
export interface RepairBundle {
  schemaVersion: 3;
  runId: string;
  id: string;
  createdAt: string;
  expiresAt: string;
  requiredInputs: {
    sourceHash: string;
    originalHash: string;
    runtimeImage: string;
    platform: string;
    archives: string[];
    dependencyClosures?: { before: unknown; after: unknown };
  };
  request: VerificationRequest;
  verification: VerificationManifest;
  transformations: SnapshotEntry[];
  preparation?: { before: PreparationProof; after: PreparationProof };
  reviewArtifact?: RepairReviewArtifact;
  witness?: { before: AssertionWitnessReceipt; after: AssertionWitnessReceipt };
}

export function object(value: unknown, name = 'input'): Record<string, any> {
  if (!value || typeof value !== 'object' || Array.isArray(value))
    throw new CsoError('INVALID_SCHEMA', `${name} must be an object`);
  return value as Record<string, any>;
}
function exact(value: Record<string, any>, allowed: readonly string[], name: string): void {
  for (const key of Object.keys(value))
    if (!allowed.includes(key)) throw new CsoError('INVALID_SCHEMA', `Unexpected ${name} field: ${key}`);
}
function boolean(value: unknown, name: string): boolean {
  if (typeof value !== 'boolean') throw new CsoError('INVALID_SCHEMA', `${name} must be a boolean`);
  return value;
}
export function string(value: unknown, name: string, max = 8192): string {
  if (typeof value !== 'string' || !value.trim() || value.length > max || UNSAFE_STRING_CONTROLS.test(value))
    throw new CsoError(
      'INVALID_SCHEMA',
      `${name} must be a nonempty string without unsafe control characters (maximum ${max})`,
    );
  return value;
}
export function strings(value: unknown, name: string): string[] {
  if (!Array.isArray(value) || value.length > 1000)
    throw new CsoError('INVALID_SCHEMA', `${name} must be an array`);
  return value.map((v, i) => string(v, `${name}[${i}]`));
}
export function oneOf<T extends string>(value: unknown, choices: readonly T[], name: string): T {
  if (!choices.includes(value as T))
    throw new CsoError('INVALID_SCHEMA', `${name} must be one of ${choices.join(', ')}`);
  return value as T;
}
export function relativePath(value: unknown): string {
  const p = string(value, 'relative path', 4096);
  if (
    p.startsWith('/') ||
    p.includes('\\') ||
    /^[A-Za-z]:/.test(p) ||
    p.split('/').some((x) => !x || x === '.' || x === '..') ||
    /[\x00-\x1f\x7f]/.test(p)
  )
    throw new CsoError('UNSAFE_PATH', 'Expected a contained relative path');
  return p;
}
const SNAPSHOT_PATH_HANDLE = /^@cso-path\/\/([a-f0-9]{32})$/;
export function snapshotPathId(root: string, path: string): string {
  // Validate the root for callers, but do not salt the opaque identity with its
  // absolute checkout path. Replay must resolve the same retained path after a
  // matching source tree is supplied from another checkout.
  string(root, 'snapshot root', 8192);
  const relative = relativePath(path);
  return sha256(canonical({ kind: 'cso-path-v3', path: relative })).slice(0, 32);
}
export function snapshotPathHandle(pathId: string): string {
  if (!/^[a-f0-9]{32}$/.test(pathId))
    throw new CsoError('INVALID_SCHEMA', 'Snapshot path ID must be 32 lowercase hexadecimal characters');
  return `@cso-path//${pathId}`;
}
export function snapshotPathHandleId(value: unknown): string | undefined {
  if (typeof value !== 'string') return;
  return SNAPSHOT_PATH_HANDLE.exec(value)?.[1];
}
export function snapshotReference(value: unknown): string {
  const reference = string(value, 'snapshot path or handle', 4096);
  return snapshotPathHandleId(reference) ? reference : relativePath(reference);
}
export function snapshotOriginalIdentity(
  entries: Array<Pick<SnapshotEntry, 'path' | 'originalHash' | 'mode'>>,
  deletedPaths: Array<Pick<SnapshotPathIdentity, 'path'>> = [],
): string {
  const present = entries.map((entry) => [entry.path, entry.originalHash, entry.mode]);
  // Preserve the original no-deletion identity for v3 artifacts already
  // retained by pre-release builds. Any deletion changes the identity and is
  // therefore impossible to strip from a manifest without detection.
  return sha256(
    canonical(
      deletedPaths.length
        ? { entries: present, deletedPaths: deletedPaths.map((item) => item.path).sort() }
        : present,
    ),
  );
}
export function rootCauseIdentity(value: string): string {
  return value.normalize('NFKC').trim().replace(/\s+/g, ' ').toLowerCase();
}
function advisoryIdentities(values: string[]): string[] {
  return [...new Set(values.map((value) => value.normalize('NFKC').trim().toUpperCase()))].sort();
}
export function fingerprint(f: Pick<FindingV3, 'rootCause' | 'location' | 'advisoryIds'>): string {
  // Titles, line shifts, severity, and generated descriptions are deliberately absent.
  return sha256(
    canonical({
      rootCause: rootCauseIdentity(f.rootCause),
      path: f.location.path,
      symbol: f.location.symbol,
      advisories: advisoryIdentities(f.advisoryIds),
    }),
  ).slice(0, 32);
}
export function validateFinding(input: unknown): FindingV3 {
  const v = object(input, 'finding'),
    loc = object(v.location, 'location'),
    c = object(v.challenge, 'challenge');
  for (const reserved of [
    'reproduction',
    'repair',
    'closure',
    'verificationId',
    'reproductionAttemptId',
    'verificationAssurance',
  ])
    if (reserved in v) throw new CsoError('INVALID_SCHEMA', `${reserved} is helper-owned`);
  exact(
    v,
    [
      'title',
      'rootCause',
      'location',
      'advisoryIds',
      'severity',
      'confidence',
      'confidenceRationale',
      'evidence',
      'attackerControl',
      'impact',
      'scenario',
      'trace',
      'references',
      'recommendation',
      'challenge',
      'dependency',
    ],
    'finding',
  );
  exact(loc, ['path', 'line', 'symbol'], 'location');
  exact(
    c,
    ['reviewer', 'independent', 'mode', 'callers', 'controls', 'counterevidence', 'conclusion'],
    'challenge',
  );
  const f: FindingV3 = {
    id: '',
    fingerprint: '',
    title: string(v.title, 'title'),
    rootCause: string(v.rootCause, 'rootCause'),
    location: { path: snapshotReference(loc.path), line: loc.line, symbol: string(loc.symbol, 'symbol') },
    advisoryIds: advisoryIdentities(strings(v.advisoryIds ?? [], 'advisoryIds')),
    severity: oneOf(v.severity, ['critical', 'high', 'medium', 'low', 'informational'], 'severity'),
    confidence: oneOf(v.confidence, ['high', 'medium', 'low'], 'confidence'),
    confidenceRationale: string(v.confidenceRationale, 'confidenceRationale'),
    evidence: oneOf(v.evidence, ['supported', 'hypothesis'], 'evidence'),
    attackerControl: string(v.attackerControl, 'attackerControl'),
    impact: string(v.impact, 'impact'),
    scenario: string(v.scenario, 'scenario'),
    trace: strings(v.trace, 'trace'),
    references: strings(v.references, 'references'),
    recommendation: string(v.recommendation, 'recommendation'),
    challenge: {
      reviewer: string(c.reviewer, 'reviewer'),
      independent: boolean(c.independent, 'challenge.independent'),
      mode: oneOf(c.mode, ['independent_agent', 'sequential_fallback'], 'challenge.mode'),
      callers: string(c.callers, 'callers'),
      controls: string(c.controls, 'controls'),
      counterevidence: string(c.counterevidence, 'counterevidence'),
      conclusion: string(c.conclusion, 'conclusion'),
    },
    reproduction: 'not_attempted',
    repair: 'not_attempted',
    closure: 'open',
  };
  if (!Number.isInteger(f.location.line) || f.location.line < 1)
    throw new CsoError('INVALID_SCHEMA', 'line must be a positive integer');
  const fallbackLabel = 'sequential challenge; independent agent unavailable';
  if (
    (f.challenge.independent &&
      (f.challenge.mode !== 'independent_agent' || f.challenge.reviewer === fallbackLabel)) ||
    (!f.challenge.independent &&
      (f.challenge.mode !== 'sequential_fallback' || f.challenge.reviewer !== fallbackLabel))
  )
    throw new CsoError(
      'INVALID_SCHEMA',
      `Challenge mode must bind either an independent agent or the exact fallback label: ${fallbackLabel}`,
    );
  if (f.evidence === 'supported' && (f.confidence === 'low' || !f.trace.length || !f.references.length))
    throw new CsoError(
      'INVALID_SCHEMA',
      'Supported findings require a challenge, a trace, supporting references, and medium/high confidence',
    );
  if (v.dependency) {
    const d = object(v.dependency);
    exact(d, ['affectedVersion', 'reachability', 'exposure', 'exploitation'], 'dependency');
    f.dependency = {
      affectedVersion: string(d.affectedVersion, 'affectedVersion'),
      reachability: oneOf(d.reachability, ['reachable', 'unreachable', 'unknown'], 'reachability'),
      exposure: string(d.exposure, 'exposure'),
      exploitation: string(d.exploitation, 'exploitation'),
    };
  }
  f.fingerprint = fingerprint(f);
  f.id = f.fingerprint;
  return f;
}
export function validateCoverage(input: unknown): CoverageRecord {
  const v = object(input, 'coverage');
  exact(v, ['domain', 'scope', 'status', 'method', 'gaps', 'exclusions', 'evidence', 'tool'], 'coverage');
  const c: CoverageRecord = {
    domain: string(v.domain, 'domain'),
    scope: string(v.scope, 'scope'),
    status: oneOf(v.status, ['assessed', 'partial', 'not_assessed', 'not_applicable'], 'coverage status'),
    method: string(v.method, 'method'),
    gaps: strings(v.gaps, 'gaps'),
    exclusions: strings(v.exclusions, 'exclusions'),
    evidence: strings(v.evidence, 'evidence'),
  };
  if (c.status === 'assessed' && (c.gaps.length || !c.evidence.length))
    throw new CsoError('INVALID_SCHEMA', 'Assessed coverage needs evidence and no outstanding gaps');
  if (c.status === 'partial' && (!c.gaps.length || !c.evidence.length))
    throw new CsoError('INVALID_SCHEMA', 'Partial coverage needs assessed evidence and a concrete gap');
  if (c.status === 'not_assessed' && !c.gaps.length)
    throw new CsoError('INVALID_SCHEMA', 'Unassessed coverage needs a concrete gap');
  if (c.status === 'not_applicable' && (!c.evidence.length || c.gaps.length))
    throw new CsoError(
      'INVALID_SCHEMA',
      'Non-applicability requires evidence and cannot retain an assessment gap',
    );
  if (v.tool) {
    const t = object(v.tool);
    exact(t, ['name', 'version', 'freshness', 'outcome'], 'coverage tool');
    c.tool = {
      name: string(t.name, 'tool name'),
      version: string(t.version, 'tool version'),
      freshness: string(t.freshness, 'freshness'),
      outcome: string(t.outcome, 'outcome'),
    };
  }
  return c;
}
export function validateCommand(value: unknown, name: string): Command {
  const v = object(value, name),
    executable = string(v.executable, `${name}.executable`, 4096),
    args = strings(v.args ?? [], `${name}.args`);
  exact(v, ['executable', 'args'], name);
  if (!executable.startsWith('/') || executable.includes('..'))
    throw new CsoError('INVALID_SCHEMA', `${name}.executable must be an absolute in-container path`);
  return { executable, args };
}
export function validateVerificationObservation(value: unknown): VerificationObservation {
  const v = object(value, 'verification observation');
  for (const key of Object.keys(v))
    if (!['booted', 'legitimate', 'security', 'existingTests', 'output', 'inputHash'].includes(key))
      throw new CsoError('INVALID_SCHEMA', `Unexpected verification observation field: ${key}`);
  if (
    typeof v.booted !== 'boolean' ||
    typeof v.legitimate !== 'boolean' ||
    typeof v.existingTests !== 'boolean'
  )
    throw new CsoError('INVALID_SCHEMA', 'Verification observation outcomes must be booleans');
  if (typeof v.output !== 'string' || v.output.length > 8192 || v.output.includes('\0'))
    throw new CsoError('INVALID_SCHEMA', 'Verification observation output must be a bounded string');
  if (typeof v.inputHash !== 'string' || (!/^$/.test(v.inputHash) && !/^[a-f0-9]{64}$/.test(v.inputHash)))
    throw new CsoError('INVALID_SCHEMA', 'Verification observation inputHash must be empty or a sha256 hash');
  return {
    booted: v.booted,
    legitimate: v.legitimate,
    security: oneOf(
      v.security,
      ['pass', 'intended_failure', 'inconclusive'],
      'verification security outcome',
    ),
    existingTests: v.existingTests,
    output: v.output,
    inputHash: v.inputHash,
  };
}
function assertion(value: unknown, name: string): HttpAssertion {
  const v = object(value, name),
    expected = object(v.expected, `${name}.expected`);
  exact(v, ['name', 'path', 'method', 'headers', 'body', 'expected', 'vulnerable'], name);
  const oracle = (x: Record<string, any>, n: string) => {
    exact(x, ['status', 'includes', 'excludes'], n);
    if (!Number.isInteger(x.status) || x.status < 100 || x.status > 599)
      throw new CsoError('INVALID_SCHEMA', `${n}.status must be an HTTP status`);
    return {
      status: x.status,
      ...(x.includes === undefined ? {} : { includes: string(x.includes, `${n}.includes`) }),
      ...(x.excludes === undefined ? {} : { excludes: string(x.excludes, `${n}.excludes`) }),
    };
  };
  const path = string(v.path, `${name}.path`, 4096);
  if (!path.startsWith('/') || path.startsWith('//') || /[\r\n]/.test(path))
    throw new CsoError('INVALID_SCHEMA', `${name}.path must stay on numeric loopback`);
  const headers: Record<string, string> = {};
  if (v.headers !== undefined)
    for (const [k, val] of Object.entries(object(v.headers, `${name}.headers`))) {
      if (
        !/^[A-Za-z0-9-]{1,100}$/.test(k) ||
        typeof val !== 'string' ||
        val.length > 8192 ||
        /[\r\n]/.test(val)
      )
        throw new CsoError('INVALID_SCHEMA', `Invalid ${name} header`);
      headers[k] = val;
    }
  return {
    name: string(v.name, `${name}.name`),
    path,
    method: oneOf(v.method, ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], `${name}.method`),
    ...(Object.keys(headers).length ? { headers } : {}),
    ...(v.body === undefined ? {} : { body: string(v.body, `${name}.body`, 65536) }),
    expected: oracle(expected, `${name}.expected`),
    ...(v.vulnerable === undefined ? {} : { vulnerable: oracle(object(v.vulnerable), `${name}.vulnerable`) }),
  };
}
export function validateVerificationRequest(input: unknown): VerificationRequest {
  const v = object(input, 'verification request'),
    changes = v.changes,
    fixtures = object(v.fixtures ?? {}, 'fixtures'),
    review = object(v.review, 'review');
  exact(
    v,
    [
      'findingId',
      'runtimeProfile',
      'port',
      'start',
      'legitimate',
      'security',
      'existingTests',
      'fixtures',
      'boundaryFiles',
      'testFiles',
      'changes',
      'review',
    ],
    'verification request',
  );
  exact(
    review,
    [
      'reviewer',
      'independent',
      'rootCauseRepaired',
      'featurePreserved',
      'boundaryMocks',
      'rationale',
      'reviewedPatchHash',
      'artifactId',
    ],
    'review',
  );
  if (!Array.isArray(changes) || !changes.length || changes.length > 100)
    throw new CsoError('INVALID_SCHEMA', 'changes must contain 1..100 declared patch effects');
  const cleanFixtures: Record<string, string> = {};
  for (const [p, body] of Object.entries(fixtures)) {
    cleanFixtures[relativePath(p)] = string(body, `fixture ${p}`, 1024 * 1024);
  }
  const request: VerificationRequest = {
    findingId: string(v.findingId, 'findingId'),
    runtimeProfile: string(v.runtimeProfile, 'runtimeProfile', 100),
    port: v.port,
    start: validateCommand(v.start, 'start'),
    legitimate: (Array.isArray(v.legitimate) ? v.legitimate : []).map((x, i) =>
      assertion(x, `legitimate[${i}]`),
    ),
    security: assertion(v.security, 'security'),
    existingTests: (Array.isArray(v.existingTests) ? v.existingTests : []).map((x, i) =>
      validateCommand(x, `existingTests[${i}]`),
    ),
    fixtures: cleanFixtures,
    boundaryFiles: strings(v.boundaryFiles, 'boundaryFiles').map(snapshotReference),
    testFiles: strings(v.testFiles, 'testFiles').map(snapshotReference),
    changes: changes.map((raw: any, i: number) => {
      const x = object(raw, `changes[${i}]`),
        before = x.beforeSha256;
      exact(x, ['path', 'beforeSha256', 'after', 'effect'], `changes[${i}]`);
      if (before !== null && (typeof before !== 'string' || !/^[a-f0-9]{64}$/.test(before)))
        throw new CsoError('INVALID_SCHEMA', `changes[${i}].beforeSha256 must be a hash or null`);
      return {
        path: snapshotReference(x.path),
        beforeSha256: before,
        after: x.after === null ? null : string(x.after, `changes[${i}].after`, 1024 * 1024),
        effect: oneOf(x.effect, ['source', 'configuration', 'dependency'], `changes[${i}].effect`),
      };
    }),
    review: {
      reviewer: string(review.reviewer, 'reviewer'),
      independent: boolean(review.independent, 'review.independent'),
      rootCauseRepaired: boolean(review.rootCauseRepaired, 'review.rootCauseRepaired'),
      featurePreserved: boolean(review.featurePreserved, 'review.featurePreserved'),
      boundaryMocks: boolean(review.boundaryMocks, 'review.boundaryMocks'),
      rationale: string(review.rationale, 'review rationale'),
      reviewedPatchHash: string(review.reviewedPatchHash, 'reviewedPatchHash'),
      ...(review.artifactId === undefined
        ? {}
        : { artifactId: string(review.artifactId, 'review artifact ID') }),
    },
  };
  if (!/^[a-f0-9]{32}$/.test(request.findingId))
    throw new CsoError('INVALID_SCHEMA', 'findingId must be a helper-issued identifier');
  if (request.review.artifactId !== undefined && !/^[a-f0-9]{32}$/.test(request.review.artifactId))
    throw new CsoError('INVALID_SCHEMA', 'review artifact ID must be a helper-issued identifier');
  if (!Number.isInteger(request.port) || request.port < 1024 || request.port > 65535)
    throw new CsoError('INVALID_SCHEMA', 'port must be 1024..65535');
  if (
    !request.legitimate.length ||
    !request.security.vulnerable ||
    !request.existingTests.length ||
    !request.boundaryFiles.length ||
    !request.testFiles.length
  )
    throw new CsoError(
      'INVALID_SCHEMA',
      'Verification needs a legitimate control, distinct before/fixed security oracles, existing tests, immutable test files, and boundary files',
    );
  const secure = request.security.expected,
    vulnerable = request.security.vulnerable;
  const mutuallyExclusive =
    secure.status !== vulnerable.status ||
    (secure.includes !== undefined &&
      vulnerable.excludes !== undefined &&
      secure.includes.includes(vulnerable.excludes)) ||
    (vulnerable.includes !== undefined &&
      secure.excludes !== undefined &&
      vulnerable.includes.includes(secure.excludes));
  if (!mutuallyExclusive)
    throw new CsoError(
      'INVALID_SCHEMA',
      'The vulnerable and fixed security oracles must be provably mutually exclusive',
    );
  if (new Set(request.changes.map((x) => x.path)).size !== request.changes.length)
    throw new CsoError('INVALID_SCHEMA', 'Patch paths must be unique');
  if (
    new Set(request.testFiles).size !== request.testFiles.length ||
    request.changes.some((change) => request.testFiles.includes(change.path))
  )
    throw new CsoError(
      'INVALID_SCHEMA',
      'Existing-test source files must be unique and unchanged by the repair',
    );
  if (
    request.existingTests.some((command) =>
      /(?:^|\/)(?:true|false|echo|printf|env|sh|bash)$/.test(command.executable),
    )
  )
    throw new CsoError(
      'INVALID_SCHEMA',
      'Generic success or shell commands cannot stand in for a project test suite',
    );
  if (
    !request.changes.some(
      (change) =>
        change.beforeSha256 === null || change.after === null || sha256(change.after) !== change.beforeSha256,
    )
  )
    throw new CsoError('INVALID_SCHEMA', 'A tested repair must contain at least one material patch effect');
  return request;
}
export function completeness(report: Pick<RunReportV3, 'coverage' | 'gaps'>): Completeness {
  // Scanner adapters preserve operational outcomes, but scanner output is only
  // candidate evidence. The corresponding investigation domain decides whether
  // assessment work remains; an optional tool failure cannot override it.
  // A successful snapshot is a prerequisite, not security assessment work by
  // itself. Its helper-owned partial/not-assessed state remains material.
  const work = report.coverage.filter(
    (c) =>
      c.status !== 'not_applicable' &&
      !c.domain.startsWith('scanner:') &&
      !(['snapshot-inputs', 'history-inputs'].includes(c.domain) && c.status === 'assessed'),
  );
  if (!report.gaps.length && work.length && work.every((c) => c.status === 'assessed')) return 'complete';
  return work.some((c) => c.status === 'assessed' || c.status === 'partial') ? 'partial' : 'not assessed';
}
export function renderReport(report: RunReportV3): string {
  const supported = report.findings.filter((f) => f.evidence === 'supported');
  const gaps = [
    ...new Set([
      ...report.gaps,
      ...report.coverage.filter((c) => !c.domain.startsWith('scanner:')).flatMap((c) => c.gaps),
    ]),
  ];
  const transformations = report.source.transformations ?? [];
  // Report JSON is canonical evidence. Markdown is a safe plain-text view:
  // collapse line breaks and escape all Markdown control characters so model,
  // repository, scanner, and advisory strings cannot forge report structure.
  const plain = (value: unknown): string =>
    String(value)
      .replace(/[\x00-\x1f\x7f-\x9f\u061c\u200e\u200f\u2028\u2029\u202a-\u202e\u2066-\u2069]+/gu, ' ')
      .replace(/\s{2,}/g, ' ')
      .trim()
      .replace(/[\\`*_[\]{}()#+!|<>]/g, '\\$&');
  const list = (values: string[]): string => (values.length ? values.map(plain).join('; ') : 'none');
  const terminal = [...report.events].reverse().find((item) => item.kind === 'terminal'),
    startedAt = Date.parse(report.createdAt),
    terminalAt = terminal ? Date.parse(terminal.at) : NaN;
  const elapsed =
    Number.isFinite(startedAt) && Number.isFinite(terminalAt) && terminalAt >= startedAt
      ? `; elapsed ${terminalAt - startedAt} ms`
      : '';
  const timing = `Timing: started ${plain(report.createdAt)}; deadline ${plain(report.deadline)}${terminal ? `; terminal ${plain(terminal.at)}${elapsed}` : ''}.`;
  const usage = report.modelUsage
    ? `Model usage: ${report.modelUsage.tokens} host-reported tokens from ${plain(report.modelUsage.source)}${report.modelUsage.cost === undefined ? '' : `; host-reported cost ${report.modelUsage.cost}`}.`
    : undefined;
  const findingLines = (f: FindingV3): string[] => [
    `- ${plain(f.severity.toUpperCase())} ${plain(f.title)} [${plain(f.id)}]`,
    `  Location: ${plain(f.location.path)}:${f.location.line} (${plain(f.location.symbol)}). Confidence: ${plain(f.confidence)} — ${plain(f.confidenceRationale)}. Evidence: ${plain(f.evidence)}.`,
    `  Attacker scenario: ${plain(f.scenario)}`,
    `  Attacker control: ${plain(f.attackerControl)}. Impact: ${plain(f.impact)}.`,
    `  Trace: ${list(f.trace)}. Supporting references: ${list(f.references)}.`,
    `  Counterevidence considered: ${plain(f.challenge.counterevidence)}. Challenge: ${plain(f.challenge.mode)} by ${plain(f.challenge.reviewer)}. Conclusion: ${plain(f.challenge.conclusion)}.`,
    `  Repair recommendation: ${plain(f.recommendation)}`,
    `  Reproduction: ${plain(f.reproduction)}${f.reproductionAttemptId ? ` (attempt ${plain(f.reproductionAttemptId)})` : ''}. Repair: ${plain(f.repair)}. Closure: ${plain(f.closure)}.`,
    ...(f.verificationId
      ? [
          `  Verification: ${plain(f.verificationId)}. Bundle: bundles/${plain(f.verificationId)}.json. Assertion assurance: ${plain(f.verificationAssurance?.assertions ?? 'unknown')}. Test completion assurance: ${plain(f.verificationAssurance?.testCompletion ?? 'unknown')}. Review assurance: ${plain(f.verificationAssurance?.review ?? 'unknown')}.`,
        ]
      : []),
  ];
  const model = report.application;
  return [
    `${report.completeness} — ${plain(report.policy.scope)}${report.policy.diff ? ` (diff against ${plain(report.policy.base)})` : ''}`,
    `Run: ${plain(report.runId)}. Mode: ${plain(report.policy.mode)}.`,
    timing,
    ...(usage ? [usage] : []),
    `Material gaps: ${gaps.length ? list(gaps) : 'none reported'}.`,
    '',
    'Application model:',
    `- Actors: ${list(model.actors)}.`,
    `- Assets: ${list(model.assets)}.`,
    `- Entrypoints: ${list(model.entrypoints)}.`,
    `- Tenant boundaries: ${list(model.tenantBoundaries)}.`,
    `- Sensitive operations: ${list(model.sensitiveOperations)}.`,
    `- Security invariants: ${list(model.invariants)}.`,
    '',
    ...(supported.length
      ? ['Supported findings:', ...supported.flatMap(findingLines)]
      : ['No supported findings in the assessed scope.']),
    ...(report.policy.mode === 'comprehensive'
      ? [
          '',
          'Hypotheses (unconfirmed):',
          ...report.findings.filter((f) => f.evidence === 'hypothesis').flatMap(findingLines),
        ]
      : []),
    '',
    'Snapshot transformations:',
    ...(transformations.length
      ? transformations.map((item) => `- ${plain(item.path)}: ${plain(item.handling)}`)
      : ['- none']),
    '',
    'Coverage:',
    ...report.coverage.flatMap((c) => [
      `- ${plain(c.domain)}: ${plain(c.status)}; ${plain(c.method)}${c.tool ? `; tool ${plain(c.tool.name)} ${plain(c.tool.version)}, freshness ${plain(c.tool.freshness)}, outcome ${plain(c.tool.outcome)}` : ''}.`,
      `  Scope: ${plain(c.scope)}. Evidence: ${list(c.evidence)}. Gaps: ${list(c.gaps)}. Exclusions: ${list(c.exclusions)}.`,
    ]),
    '',
  ].join('\n');
}
type LegacyJson = null | boolean | number | string | LegacyJson[] | { [key: string]: LegacyJson };
function legacyJson(value: unknown, depth = 0, seen = new WeakSet<object>()): LegacyJson {
  if (depth > 32) throw new CsoError('INVALID_SCHEMA', 'Legacy report nesting is too deep');
  if (value === null || typeof value === 'boolean') return value;
  if (typeof value === 'number') {
    if (!Number.isFinite(value)) throw new CsoError('INVALID_SCHEMA', 'Legacy report numbers must be finite');
    return value;
  }
  if (typeof value === 'string') {
    if (value.length > MAX_OUTPUT || UNSAFE_STRING_CONTROLS.test(value))
      throw new CsoError(
        'INVALID_SCHEMA',
        'Legacy report strings must be bounded and free of unsafe control characters',
      );
    return value;
  }
  if (!value || typeof value !== 'object')
    throw new CsoError('INVALID_SCHEMA', 'Legacy report contains a non-JSON value');
  if (seen.has(value)) throw new CsoError('INVALID_SCHEMA', 'Legacy report cannot be cyclic');
  seen.add(value);
  try {
    if (Array.isArray(value)) {
      if (value.length > 10_000) throw new CsoError('INVALID_SCHEMA', 'Legacy report array is too large');
      return value.map((item) => legacyJson(item, depth + 1, seen));
    }
    const entries = Object.entries(value as Record<string, unknown>);
    if (entries.length > 10_000) throw new CsoError('INVALID_SCHEMA', 'Legacy report object is too large');
    const out: Record<string, LegacyJson> = Object.create(null);
    for (const [key, item] of entries) {
      if (
        key.length > 1024 ||
        ['__proto__', 'prototype', 'constructor'].includes(key) ||
        UNSAFE_PROPERTY_CONTROLS.test(key)
      )
        throw new CsoError('INVALID_SCHEMA', 'Legacy report contains an unsafe property');
      out[key] = legacyJson(item, depth + 1, seen);
    }
    return out;
  } finally {
    seen.delete(value);
  }
}
export function importLegacy(input: unknown): {
  schemaVersion: 2;
  readOnly: true;
  findings: any[];
  warning: string;
} {
  const v = object(input, 'legacy report');
  if (
    !Array.isArray(v.findings) ||
    ![2, '2', '2.0', '2.0.0'].includes(v.schemaVersion ?? v.schema_version ?? v.version)
  )
    throw new CsoError('INVALID_SCHEMA', 'Expected a v2 report with findings');
  return {
    schemaVersion: 2,
    readOnly: true,
    warning:
      'Legacy VERIFIED is review evidence only; it does not establish reproduction, tested repair, or closure.',
    findings: v.findings.map((raw: any, index: number) => {
      const f = object(raw, `legacy finding ${index + 1}`);
      return {
        title: typeof f.title === 'string' ? string(f.title, 'legacy title') : `Legacy finding ${index + 1}`,
        status: typeof f.status === 'string' ? string(f.status, 'legacy status') : 'unknown',
        ...(typeof f.severity === 'string' ? { severity: string(f.severity, 'legacy severity') } : {}),
        ...(typeof f.description === 'string'
          ? { description: string(f.description, 'legacy description') }
          : {}),
        legacy: legacyJson(f),
        evidence: 'legacy_review',
        reproduction: 'not_attempted',
        repair: 'not_attempted',
        closure: 'unknown',
      };
    }),
  };
}