@neurcode-ai/contracts 0.1.3 → 0.2.1

package/src/index.ts

@@ -1,806 +0,0 @@
-export const CLI_JSON_CONTRACT_VERSION = '2026-05-11';
-
-/** Compare YYYY-MM-DD contract stamps; returns null when either side is unparsable. */
-export function compareCalendarContractVersion(left: string, right: string): number | null {
-  const parse = (value: string): number | null => {
-    const match = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim());
-    if (!match) return null;
-    const ms = Date.parse(`${match[1]}T00:00:00.000Z`);
-    return Number.isNaN(ms) ? null : ms;
-  };
-  const leftMs = parse(left);
-  const rightMs = parse(right);
-  if (leftMs === null || rightMs === null) return null;
-  if (leftMs === rightMs) return 0;
-  return leftMs < rightMs ? -1 : 1;
-}
-export * from './intelligence';
-export * from './status-vocabulary';
-export * from './verification';
-export * from './remediation';
-export * from './admission';
-export const RUNTIME_COMPATIBILITY_CONTRACT_ID = 'neurcode-runtime-compatibility';
-export const RUNTIME_COMPATIBILITY_CONTRACT_VERSION = '2026-04-04';
-export const RUNTIME_COMPATIBILITY_MANIFEST_VERSION = '2026-06-02.1';
-export const RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION = 1;
-
-/**
- * Runtime Admission contract (Phase A — Provenance Core). Additive: surfaces a
- * version for the self-attested admission artifact + coverage manifest so the
- * future Action and backend can negotiate compatibility. No enforcement yet.
- */
-export const ADMISSION_CONTRACT_ID = 'neurcode-runtime-admission';
-export const ADMISSION_CONTRACT_VERSION = '2026-06-02';
-
-export type RuntimeComponent = 'cli' | 'action' | 'api';
-
-export type RuntimeMinimumPeerVersions = Partial<Record<RuntimeComponent, string>>;
-
-export interface RuntimeCompatibilityTriplet {
-  id: string;
-  channel: 'current' | 'support-floor' | 'compat-canary';
-  versions: Record<RuntimeComponent, string>;
-  notes?: string;
-}
-
-export interface RuntimeCompatibilityManifest {
-  schemaVersion: number;
-  manifestVersion: string;
-  contractId: string;
-  runtimeContractVersion: string;
-  cliJsonContractVersion: string;
-  /** Runtime Admission provenance contract version (additive; Phase A). */
-  admissionContractVersion: string;
-  minimumPeerVersions: Record<RuntimeComponent, RuntimeMinimumPeerVersions>;
-  validatedTriplets: RuntimeCompatibilityTriplet[];
-}
-
-const RUNTIME_COMPATIBILITY_MANIFEST: RuntimeCompatibilityManifest = {
-  schemaVersion: RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
-  manifestVersion: RUNTIME_COMPATIBILITY_MANIFEST_VERSION,
-  contractId: RUNTIME_COMPATIBILITY_CONTRACT_ID,
-  runtimeContractVersion: RUNTIME_COMPATIBILITY_CONTRACT_VERSION,
-  cliJsonContractVersion: CLI_JSON_CONTRACT_VERSION,
-  admissionContractVersion: ADMISSION_CONTRACT_VERSION,
-  minimumPeerVersions: {
-    cli: {
-      action: '0.2.1',
-      api: '0.2.0',
-    },
-    action: {
-      cli: '0.9.35',
-      api: '0.2.0',
-    },
-    api: {
-      cli: '0.9.35',
-      action: '0.2.1',
-    },
-  },
-  validatedTriplets: [
-    {
-      id: 'current',
-      channel: 'current',
-      versions: {
-        cli: '0.14.0',
-        action: '0.2.4',
-        api: '0.2.0',
-      },
-      notes: 'Current release train validated in monorepo CI.',
-    },
-    {
-      id: 'support-floor',
-      channel: 'support-floor',
-      versions: {
-        cli: '0.9.35',
-        action: '0.2.1',
-        api: '0.2.0',
-      },
-      notes: 'Minimum supported compatibility floor for enterprise rollout.',
-    },
-  ],
-};
-
-const RUNTIME_MINIMUM_PEER_VERSIONS: Record<RuntimeComponent, RuntimeMinimumPeerVersions> =
-  RUNTIME_COMPATIBILITY_MANIFEST.minimumPeerVersions;
-
-export function getRuntimeCompatibilityManifest(): RuntimeCompatibilityManifest {
-  return {
-    ...RUNTIME_COMPATIBILITY_MANIFEST,
-    admissionContractVersion: RUNTIME_COMPATIBILITY_MANIFEST.admissionContractVersion,
-    minimumPeerVersions: {
-      cli: { ...RUNTIME_COMPATIBILITY_MANIFEST.minimumPeerVersions.cli },
-      action: { ...RUNTIME_COMPATIBILITY_MANIFEST.minimumPeerVersions.action },
-      api: { ...RUNTIME_COMPATIBILITY_MANIFEST.minimumPeerVersions.api },
-    },
-    validatedTriplets: RUNTIME_COMPATIBILITY_MANIFEST.validatedTriplets.map((triplet) => ({
-      ...triplet,
-      versions: { ...triplet.versions },
-    })),
-  };
-}
-
-export interface RuntimeCompatibilityDescriptor {
-  contractId: string;
-  runtimeContractVersion: string;
-  cliJsonContractVersion: string;
-  manifestVersion?: string;
-  /** Runtime Admission provenance contract version (additive; optional for legacy peers). */
-  admissionContractVersion?: string;
-  component: RuntimeComponent;
-  componentVersion: string;
-  minimumPeerVersions: RuntimeMinimumPeerVersions;
-}
-
-export interface CliContractBase {
-  contractVersion?: string;
-  [key: string]: unknown;
-}
-
-export interface CliPlanJsonPayload extends CliContractBase {
-  success: boolean;
-  cached: boolean;
-  mode: string;
-  planId: string | null;
-  sessionId: string | null;
-  timestamp: string;
-  message: string;
-}
-
-export interface CliApplyJsonPayload extends CliContractBase {
-  success: boolean;
-  planId: string;
-  filesGenerated: number;
-  files: unknown[];
-  writtenFiles: unknown[];
-  message: string;
-}
-
-export type VerifyVerdict = 'PASS' | 'WARN' | 'FAIL';
-export type VerifySeverity = 'critical' | 'high' | 'warning' | 'info';
-
-export interface VerifyOutputSummary {
-  totalFilesChanged: number;
-  totalViolations: number;
-  totalWarnings: number;
-  totalScopeIssues: number;
-}
-
-export interface VerifyOutputViolation {
-  file: string;
-  message: string;
-  policy: string;
-  severity: VerifySeverity;
-}
-
-export interface VerifyOutputWarning {
-  file: string;
-  message: string;
-  policy: string;
-}
-
-export type VerifyScopeIssuePolicy = 'forbidden' | 'review-required' | 'out-of-scope' | 'generated-code' | 'unscoped';
-export type VerifyScopeIssueBoundaryType = 'sensitive' | 'infra' | 'ci' | 'dependency-manifest' | 'service' | 'module' | 'generated-code' | 'unspecified';
-
-export type VerifyImportEdgeKind = 'static' | 'relative' | 'dynamic' | 'require' | 'side-effect';
-export type VerifyImportEdgeLanguage = 'python' | 'typescript' | 'javascript';
-
-/**
- * Discriminator metadata attached to a scope issue when the breach was
- * detected through an import edge rather than a touched file path.
- * Present iff the scope issue originated from `evaluateImportEdgeGovernance`.
- */
-export interface VerifyOutputImportEdge {
-  sourceFile: string;
-  sourceLine: number;
-  importTarget: string;
-  resolvedTargetPath: string;
-  resolvedBoundary: string;
-  edgeKind: VerifyImportEdgeKind;
-  language: VerifyImportEdgeLanguage;
-  deterministic: true;
-  replayStable: true;
-}
-
-export interface VerifyOutputScopeIssue {
-  file: string;
-  message: string;
-  /**
-   * Severity / governance classification of the scope issue.
-   * Optional for backward compatibility with pre-runtime-activation payloads.
-   */
-  policy?: VerifyScopeIssuePolicy;
-  /**
-   * Boundary category this file touched (when known). Optional so legacy
-   * payloads remain valid.
-   */
-  boundaryType?: VerifyScopeIssueBoundaryType;
-  /**
-   * Set on issues raised by the deterministic import-edge governance layer
-   * (an allowed source file importing from a forbidden boundary).
-   */
-  importEdge?: VerifyOutputImportEdge;
-}
-
-export interface VerifyOutput {
-  verdict: VerifyVerdict;
-  summary: VerifyOutputSummary;
-  violations: VerifyOutputViolation[];
-  warnings: VerifyOutputWarning[];
-  scopeIssues: VerifyOutputScopeIssue[];
-  driftScore?: number;
-  /** Canonical governance model (additive; absent in legacy payloads). */
-  governanceVerification?: import('./verification').GovernanceVerificationEnvelope;
-  governanceFindings?: import('./verification').GovernanceFinding[];
-}
-
-export type CliVerifyJsonPayload = VerifyOutput;
-
-export interface CliPromptJsonPayload extends CliContractBase {
-  success: boolean;
-  planId: string | null;
-  intent: string | null;
-  prompt: string | null;
-  copied: boolean;
-  outputPath: string | null;
-  message: string;
-}
-
-export interface CliContractImportJsonPayload extends CliContractBase {
-  success: boolean;
-  provider: string | null;
-  planId: string | null;
-  sessionId: string | null;
-  projectId: string | null;
-  parseMode: 'json' | 'text' | null;
-  importedFiles: number;
-  sourcePath?: string | null;
-  autoDetect?: Record<string, unknown> | null;
-  warnings: unknown[];
-  changeContract?: Record<string, unknown> | null;
-  message: string;
-  timestamp: string;
-}
-
-export interface CliShipJsonPayload extends CliContractBase {
-  success: boolean;
-  status: string;
-  finalPlanId: string | null;
-  audit?: Record<string, unknown>;
-  error?: Record<string, unknown>;
-}
-
-export interface CliShipRunsJsonPayload extends CliContractBase {
-  runs: unknown[];
-}
-
-export interface CliShipResumeJsonPayload extends CliContractBase {
-  success: boolean;
-  status: string;
-  error?: Record<string, unknown>;
-}
-
-export interface CliShipAttestationVerifyJsonPayload extends CliContractBase {
-  pass: boolean;
-  message?: string;
-  digest?: Record<string, unknown>;
-}
-
-export interface CliCompatJsonPayload extends CliContractBase {
-  success: boolean;
-  timestamp: string;
-  component: 'cli';
-  componentVersion: string;
-  compatibility: RuntimeCompatibilityDescriptor;
-}
-
-function asRecord(value: unknown, label: string): Record<string, unknown> {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${label}: expected object`);
-  }
-  return value as Record<string, unknown>;
-}
-
-function asBoolean(record: Record<string, unknown>, key: string, label: string): boolean {
-  if (typeof record[key] !== 'boolean') {
-    throw new Error(`${label}: expected ${key}:boolean`);
-  }
-  return record[key] as boolean;
-}
-
-function asNumber(record: Record<string, unknown>, key: string, label: string): number {
-  if (typeof record[key] !== 'number' || Number.isNaN(record[key])) {
-    throw new Error(`${label}: expected ${key}:number`);
-  }
-  return record[key] as number;
-}
-
-function asString(record: Record<string, unknown>, key: string, label: string): string {
-  if (typeof record[key] !== 'string') {
-    throw new Error(`${label}: expected ${key}:string`);
-  }
-  return record[key] as string;
-}
-
-function asNullableString(record: Record<string, unknown>, key: string, label: string): string | null {
-  const value = record[key];
-  if (value === null || typeof value === 'string') {
-    return value as string | null;
-  }
-  throw new Error(`${label}: expected ${key}:string|null`);
-}
-
-function asArray(record: Record<string, unknown>, key: string, label: string): unknown[] {
-  if (!Array.isArray(record[key])) {
-    throw new Error(`${label}: expected ${key}:array`);
-  }
-  return record[key] as unknown[];
-}
-
-function asOptionalRecord(record: Record<string, unknown>, key: string, label: string): Record<string, unknown> | undefined {
-  const value = record[key];
-  if (value === undefined) return undefined;
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error(`${label}: expected ${key}:object`);
-  }
-  return value as Record<string, unknown>;
-}
-
-function asOptionalString(record: Record<string, unknown>, key: string, label: string): string | undefined {
-  const value = record[key];
-  if (value === undefined) return undefined;
-  if (typeof value !== 'string') {
-    throw new Error(`${label}: expected ${key}:string`);
-  }
-  return value;
-}
-
-function asIntegerNumber(record: Record<string, unknown>, key: string, label: string): number {
-  const value = asNumber(record, key, label);
-  return Math.max(0, Math.floor(value));
-}
-
-function asContractVersion(record: Record<string, unknown>): string | undefined {
-  const value = record.contractVersion;
-  if (value === undefined) return undefined;
-  if (typeof value !== 'string') {
-    throw new Error('contractVersion: expected string when present');
-  }
-  return value;
-}
-
-function asRuntimeComponent(record: Record<string, unknown>, key: string, label: string): RuntimeComponent {
-  const value = asString(record, key, label);
-  if (value === 'cli' || value === 'action' || value === 'api') {
-    return value;
-  }
-  throw new Error(`${label}: expected ${key}:("cli"|"action"|"api")`);
-}
-
-function parseRuntimeMinimumPeerVersions(
-  value: unknown,
-  label: string
-): RuntimeMinimumPeerVersions {
-  if (value === undefined || value === null) return {};
-  const record = asRecord(value, `${label}.minimumPeerVersions`);
-  const next: RuntimeMinimumPeerVersions = {};
-  for (const component of ['cli', 'action', 'api'] as const) {
-    const componentValue = record[component];
-    if (componentValue === undefined) continue;
-    if (typeof componentValue !== 'string' || !componentValue.trim()) {
-      throw new Error(`${label}.minimumPeerVersions: expected ${component}:string`);
-    }
-    next[component] = componentValue.trim();
-  }
-  return next;
-}
-
-function parseRuntimeCompatibilityDescriptor(
-  value: unknown,
-  label: string
-): RuntimeCompatibilityDescriptor {
-  const record = asRecord(value, `${label}.compatibility`);
-  return {
-    contractId: asString(record, 'contractId', `${label}.compatibility`),
-    runtimeContractVersion: asString(record, 'runtimeContractVersion', `${label}.compatibility`),
-    cliJsonContractVersion: asString(record, 'cliJsonContractVersion', `${label}.compatibility`),
-    manifestVersion: asOptionalString(record, 'manifestVersion', `${label}.compatibility`),
-    admissionContractVersion: asOptionalString(record, 'admissionContractVersion', `${label}.compatibility`),
-    component: asRuntimeComponent(record, 'component', `${label}.compatibility`),
-    componentVersion: asString(record, 'componentVersion', `${label}.compatibility`),
-    minimumPeerVersions: parseRuntimeMinimumPeerVersions(record.minimumPeerVersions, `${label}.compatibility`),
-  };
-}
-
-function parseSemver(value: string): [number, number, number] | null {
-  const normalized = value.trim().replace(/^v/i, '').split('+')[0].split('-')[0];
-  const match = normalized.match(/^(\d+)\.(\d+)\.(\d+)$/);
-  if (!match) return null;
-  const major = Number(match[1]);
-  const minor = Number(match[2]);
-  const patch = Number(match[3]);
-  if (!Number.isFinite(major) || !Number.isFinite(minor) || !Number.isFinite(patch)) {
-    return null;
-  }
-  return [major, minor, patch];
-}
-
-export function compareSemver(left: string, right: string): number | null {
-  const l = parseSemver(left);
-  const r = parseSemver(right);
-  if (!l || !r) return null;
-  for (let idx = 0; idx < 3; idx += 1) {
-    if (l[idx] > r[idx]) return 1;
-    if (l[idx] < r[idx]) return -1;
-  }
-  return 0;
-}
-
-export function isSemverAtLeast(actual: string, minimum: string): boolean | null {
-  const compare = compareSemver(actual, minimum);
-  if (compare === null) return null;
-  return compare >= 0;
-}
-
-export function getMinimumCompatiblePeerVersion(
-  component: RuntimeComponent,
-  peer: RuntimeComponent
-): string | undefined {
-  return RUNTIME_MINIMUM_PEER_VERSIONS[component][peer];
-}
-
-export function getRuntimeMinimumPeerVersionMatrix(): Record<RuntimeComponent, RuntimeMinimumPeerVersions> {
-  return {
-    cli: { ...RUNTIME_MINIMUM_PEER_VERSIONS.cli },
-    action: { ...RUNTIME_MINIMUM_PEER_VERSIONS.action },
-    api: { ...RUNTIME_MINIMUM_PEER_VERSIONS.api },
-  };
-}
-
-export function buildRuntimeCompatibilityDescriptor(
-  component: RuntimeComponent,
-  componentVersion: string
-): RuntimeCompatibilityDescriptor {
-  return {
-    contractId: RUNTIME_COMPATIBILITY_CONTRACT_ID,
-    runtimeContractVersion: RUNTIME_COMPATIBILITY_CONTRACT_VERSION,
-    cliJsonContractVersion: CLI_JSON_CONTRACT_VERSION,
-    manifestVersion: RUNTIME_COMPATIBILITY_MANIFEST_VERSION,
-    admissionContractVersion: ADMISSION_CONTRACT_VERSION,
-    component,
-    componentVersion,
-    minimumPeerVersions: { ...RUNTIME_MINIMUM_PEER_VERSIONS[component] },
-  };
-}
-
-export interface RuntimePeerCompatibilityIssue {
-  component: RuntimeComponent;
-  peer: RuntimeComponent;
-  required: string;
-  actual: string;
-  code: 'UNPARSABLE_VERSION' | 'VERSION_BELOW_MINIMUM';
-}
-
-export function evaluateRuntimePeerCompatibility(versions: Record<RuntimeComponent, string>): RuntimePeerCompatibilityIssue[] {
-  const issues: RuntimePeerCompatibilityIssue[] = [];
-  for (const component of ['cli', 'action', 'api'] as const) {
-    for (const peer of ['cli', 'action', 'api'] as const) {
-      if (peer === component) continue;
-      const required = getMinimumCompatiblePeerVersion(component, peer);
-      if (!required) continue;
-      const actual = versions[peer];
-      const compatible = isSemverAtLeast(actual, required);
-      if (compatible === null) {
-        issues.push({
-          component,
-          peer,
-          required,
-          actual,
-          code: 'UNPARSABLE_VERSION',
-        });
-      } else if (!compatible) {
-        issues.push({
-          component,
-          peer,
-          required,
-          actual,
-          code: 'VERSION_BELOW_MINIMUM',
-        });
-      }
-    }
-  }
-  return issues;
-}
-
-export function parseCliPlanJsonPayload(value: unknown, label = 'plan'): CliPlanJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    cached: asBoolean(record, 'cached', label),
-    mode: asString(record, 'mode', label),
-    planId: asNullableString(record, 'planId', label),
-    sessionId: asNullableString(record, 'sessionId', label),
-    timestamp: asString(record, 'timestamp', label),
-    message: asString(record, 'message', label),
-  };
-}
-
-export function parseCliApplyJsonPayload(value: unknown, label = 'apply'): CliApplyJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    planId: asString(record, 'planId', label),
-    filesGenerated: asNumber(record, 'filesGenerated', label),
-    files: asArray(record, 'files', label),
-    writtenFiles: asArray(record, 'writtenFiles', label),
-    message: asString(record, 'message', label),
-  };
-}
-
-export function parseCliVerifyJsonPayload(value: unknown, label = 'verify'): CliVerifyJsonPayload {
-  return parseVerifyOutput(value, label);
-}
-
-export function parseVerifyOutput(value: unknown, label = 'verify'): VerifyOutput {
-  const record = asRecord(value, label);
-  const verdictRaw = asString(record, 'verdict', label).trim().toUpperCase();
-  if (verdictRaw !== 'PASS' && verdictRaw !== 'WARN' && verdictRaw !== 'FAIL') {
-    throw new Error(`${label}: expected verdict:"PASS"|"WARN"|"FAIL"`);
-  }
-
-  const summaryRecord = asRecord(record.summary, `${label}.summary`);
-  const summary: VerifyOutputSummary = {
-    totalFilesChanged: asIntegerNumber(summaryRecord, 'totalFilesChanged', `${label}.summary`),
-    totalViolations: asIntegerNumber(summaryRecord, 'totalViolations', `${label}.summary`),
-    totalWarnings: asIntegerNumber(summaryRecord, 'totalWarnings', `${label}.summary`),
-    totalScopeIssues: asIntegerNumber(summaryRecord, 'totalScopeIssues', `${label}.summary`),
-  };
-
-  const violations = asArray(record, 'violations', label).map((entry, index) => {
-    const item = asRecord(entry, `${label}.violations[${index}]`);
-    const severity = asString(item, 'severity', `${label}.violations[${index}]`).trim().toLowerCase();
-    if (severity !== 'critical' && severity !== 'high' && severity !== 'warning' && severity !== 'info') {
-      throw new Error(
-        `${label}.violations[${index}]: expected severity:"critical"|"high"|"warning"|"info"`
-      );
-    }
-    return {
-      file: asString(item, 'file', `${label}.violations[${index}]`),
-      message: asString(item, 'message', `${label}.violations[${index}]`),
-      policy: asString(item, 'policy', `${label}.violations[${index}]`),
-      severity,
-    } as VerifyOutputViolation;
-  });
-
-  const warnings = asArray(record, 'warnings', label).map((entry, index) => {
-    const item = asRecord(entry, `${label}.warnings[${index}]`);
-    return {
-      file: asString(item, 'file', `${label}.warnings[${index}]`),
-      message: asString(item, 'message', `${label}.warnings[${index}]`),
-      policy: asString(item, 'policy', `${label}.warnings[${index}]`),
-    } as VerifyOutputWarning;
-  });
-
-  const scopeIssues = asArray(record, 'scopeIssues', label).map((entry, index) => {
-    const item = asRecord(entry, `${label}.scopeIssues[${index}]`);
-    const issue: VerifyOutputScopeIssue = {
-      file: asString(item, 'file', `${label}.scopeIssues[${index}]`),
-      message: asString(item, 'message', `${label}.scopeIssues[${index}]`),
-    };
-    const rawPolicy = item.policy;
-    if (typeof rawPolicy === 'string' && rawPolicy.length > 0) {
-      const allowedPolicies: VerifyScopeIssuePolicy[] = ['forbidden', 'review-required', 'out-of-scope', 'generated-code', 'unscoped'];
-      if ((allowedPolicies as string[]).includes(rawPolicy)) {
-        issue.policy = rawPolicy as VerifyScopeIssuePolicy;
-      }
-    }
-    const rawBoundary = item.boundaryType;
-    if (typeof rawBoundary === 'string' && rawBoundary.length > 0) {
-      const allowedBoundaries: VerifyScopeIssueBoundaryType[] = [
-        'sensitive', 'infra', 'ci', 'dependency-manifest', 'service', 'module', 'generated-code', 'unspecified',
-      ];
-      if ((allowedBoundaries as string[]).includes(rawBoundary)) {
-        issue.boundaryType = rawBoundary as VerifyScopeIssueBoundaryType;
-      }
-    }
-    const rawImportEdge = item.importEdge;
-    if (rawImportEdge && typeof rawImportEdge === 'object' && !Array.isArray(rawImportEdge)) {
-      const edgeRecord = rawImportEdge as Record<string, unknown>;
-      const allowedEdgeKinds: VerifyImportEdgeKind[] = ['static', 'relative', 'dynamic', 'require', 'side-effect'];
-      const allowedEdgeLanguages: VerifyImportEdgeLanguage[] = ['python', 'typescript', 'javascript'];
-      const sourceFile = edgeRecord.sourceFile;
-      const importTarget = edgeRecord.importTarget;
-      const resolvedTargetPath = edgeRecord.resolvedTargetPath;
-      const resolvedBoundary = edgeRecord.resolvedBoundary;
-      const sourceLine = edgeRecord.sourceLine;
-      const edgeKind = edgeRecord.edgeKind;
-      const language = edgeRecord.language;
-      if (
-        typeof sourceFile === 'string'
-        && typeof importTarget === 'string'
-        && typeof resolvedTargetPath === 'string'
-        && typeof resolvedBoundary === 'string'
-        && typeof sourceLine === 'number'
-        && Number.isFinite(sourceLine)
-        && typeof edgeKind === 'string'
-        && typeof language === 'string'
-        && (allowedEdgeKinds as string[]).includes(edgeKind)
-        && (allowedEdgeLanguages as string[]).includes(language)
-      ) {
-        issue.importEdge = {
-          sourceFile,
-          sourceLine,
-          importTarget,
-          resolvedTargetPath,
-          resolvedBoundary,
-          edgeKind: edgeKind as VerifyImportEdgeKind,
-          language: language as VerifyImportEdgeLanguage,
-          deterministic: true,
-          replayStable: true,
-        };
-      }
-    }
-    return issue;
-  });
-
-  const driftScoreRaw = record.driftScore;
-  const driftScore =
-    driftScoreRaw === undefined
-      ? undefined
-      : (typeof driftScoreRaw === 'number' && Number.isFinite(driftScoreRaw)
-        ? Math.round(Math.max(0, Math.min(100, driftScoreRaw)))
-        : (() => {
-          throw new Error(`${label}: expected driftScore:number when present`);
-        })());
-
-  const governanceFindingsRaw = record.governanceFindings;
-  if (governanceFindingsRaw !== undefined && !Array.isArray(governanceFindingsRaw)) {
-    throw new Error(`${label}: expected governanceFindings:array when present`);
-  }
-
-  const governanceVerificationRaw = record.governanceVerification;
-  if (
-    governanceVerificationRaw !== undefined
-    && (typeof governanceVerificationRaw !== 'object' || governanceVerificationRaw === null || Array.isArray(governanceVerificationRaw))
-  ) {
-    throw new Error(`${label}: expected governanceVerification:object when present`);
-  }
-
-  return {
-    verdict: verdictRaw,
-    summary,
-    violations,
-    warnings,
-    scopeIssues,
-    ...(typeof driftScore === 'number' ? { driftScore } : {}),
-    ...(governanceFindingsRaw !== undefined
-      ? { governanceFindings: governanceFindingsRaw as import('./verification').GovernanceFinding[] }
-      : {}),
-    ...(governanceVerificationRaw !== undefined
-      ? {
-          governanceVerification:
-            governanceVerificationRaw as import('./verification').GovernanceVerificationEnvelope,
-        }
-      : {}),
-  };
-}
-
-export function parseCliPromptJsonPayload(value: unknown, label = 'prompt'): CliPromptJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    planId: asNullableString(record, 'planId', label),
-    intent: asNullableString(record, 'intent', label),
-    prompt: asNullableString(record, 'prompt', label),
-    copied: asBoolean(record, 'copied', label),
-    outputPath: asNullableString(record, 'outputPath', label),
-    message: asString(record, 'message', label),
-  };
-}
-
-export function parseCliContractImportJsonPayload(
-  value: unknown,
-  label = 'contract-import'
-): CliContractImportJsonPayload {
-  const record = asRecord(value, label);
-  const parseModeRaw = record.parseMode;
-  let parseMode: 'json' | 'text' | null = null;
-  if (parseModeRaw !== undefined && parseModeRaw !== null) {
-    const parseModeValue = asString(record, 'parseMode', label);
-    if (parseModeValue !== 'json' && parseModeValue !== 'text') {
-      throw new Error(`${label}: expected parseMode:"json"|"text"|null`);
-    }
-    parseMode = parseModeValue;
-  }
-  const changeContractValue = record.changeContract;
-  let changeContract: Record<string, unknown> | null | undefined;
-  if (changeContractValue === null) {
-    changeContract = null;
-  } else if (changeContractValue !== undefined) {
-    changeContract = asOptionalRecord(record, 'changeContract', label);
-  }
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    provider: asNullableString(record, 'provider', label),
-    planId: asNullableString(record, 'planId', label),
-    sessionId: asNullableString(record, 'sessionId', label),
-    projectId: asNullableString(record, 'projectId', label),
-    parseMode,
-    importedFiles: asNumber(record, 'importedFiles', label),
-    warnings: asArray(record, 'warnings', label),
-    changeContract,
-    message: asString(record, 'message', label),
-    timestamp: asString(record, 'timestamp', label),
-  };
-}
-
-export function parseCliShipJsonPayload(value: unknown, label = 'ship'): CliShipJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    status: asString(record, 'status', label),
-    finalPlanId: asNullableString(record, 'finalPlanId', label),
-    audit: asOptionalRecord(record, 'audit', label),
-    error: asOptionalRecord(record, 'error', label),
-  };
-}
-
-export function parseCliShipRunsJsonPayload(value: unknown, label = 'ship-runs'): CliShipRunsJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    runs: asArray(record, 'runs', label),
-  };
-}
-
-export function parseCliShipResumeJsonPayload(value: unknown, label = 'ship-resume'): CliShipResumeJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    status: asString(record, 'status', label),
-    error: asOptionalRecord(record, 'error', label),
-  };
-}
-
-export function parseCliShipAttestationVerifyJsonPayload(
-  value: unknown,
-  label = 'ship-attestation-verify'
-): CliShipAttestationVerifyJsonPayload {
-  const record = asRecord(value, label);
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    pass: asBoolean(record, 'pass', label),
-    message: record.message === undefined ? undefined : asString(record, 'message', label),
-    digest: asOptionalRecord(record, 'digest', label),
-  };
-}
-
-export function parseCliCompatJsonPayload(value: unknown, label = 'compat'): CliCompatJsonPayload {
-  const record = asRecord(value, label);
-  const component = asString(record, 'component', label);
-  if (component !== 'cli') {
-    throw new Error(`${label}: expected component:"cli"`);
-  }
-  return {
-    ...record,
-    contractVersion: asContractVersion(record),
-    success: asBoolean(record, 'success', label),
-    timestamp: asString(record, 'timestamp', label),
-    component: 'cli',
-    componentVersion: asString(record, 'componentVersion', label),
-    compatibility: parseRuntimeCompatibilityDescriptor(record.compatibility, label),
-  };
-}