@neurcode-ai/contracts 0.1.1 → 0.1.3

package/src/index.ts

@@ -1,9 +1,37 @@
-export const CLI_JSON_CONTRACT_VERSION = '2026-04-04';
+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-04-04.1';
+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>>;
@@ -21,6 +49,8 @@ export interface RuntimeCompatibilityManifest {
   contractId: string;
   runtimeContractVersion: string;
   cliJsonContractVersion: string;
+  /** Runtime Admission provenance contract version (additive; Phase A). */
+  admissionContractVersion: string;
   minimumPeerVersions: Record<RuntimeComponent, RuntimeMinimumPeerVersions>;
   validatedTriplets: RuntimeCompatibilityTriplet[];
 }
@@ -31,6 +61,7 @@ const RUNTIME_COMPATIBILITY_MANIFEST: RuntimeCompatibilityManifest = {
   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',
@@ -50,8 +81,8 @@ const RUNTIME_COMPATIBILITY_MANIFEST: RuntimeCompatibilityManifest = {
       id: 'current',
       channel: 'current',
       versions: {
-        cli: '0.9.36',
-        action: '0.2.2',
+        cli: '0.14.0',
+        action: '0.2.4',
         api: '0.2.0',
       },
       notes: 'Current release train validated in monorepo CI.',
@@ -75,6 +106,7 @@ const RUNTIME_MINIMUM_PEER_VERSIONS: Record<RuntimeComponent, RuntimeMinimumPeer
 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 },
@@ -92,6 +124,8 @@ export interface RuntimeCompatibilityDescriptor {
   runtimeContractVersion: string;
   cliJsonContractVersion: string;
   manifestVersion?: string;
+  /** Runtime Admission provenance contract version (additive; optional for legacy peers). */
+  admissionContractVersion?: string;
   component: RuntimeComponent;
   componentVersion: string;
   minimumPeerVersions: RuntimeMinimumPeerVersions;
@@ -121,18 +155,86 @@ export interface CliApplyJsonPayload extends CliContractBase {
   message: string;
 }
 
-export interface CliVerifyJsonPayload extends CliContractBase {
-  grade: string;
-  score: number;
-  verdict: string;
-  violations: unknown[];
+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;
-  scopeGuardPassed: boolean;
-  verificationSource?: 'api' | 'local_fallback' | 'policy_only' | string;
-  policyCompilation?: Record<string, unknown>;
-  changeContract?: Record<string, unknown>;
+  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;
@@ -151,6 +253,8 @@ export interface CliContractImportJsonPayload extends CliContractBase {
   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;
@@ -250,6 +354,11 @@ function asOptionalString(record: Record<string, unknown>, key: string, label: s
   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;
@@ -295,6 +404,7 @@ function parseRuntimeCompatibilityDescriptor(
     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`),
@@ -355,6 +465,7 @@ export function buildRuntimeCompatibilityDescriptor(
     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] },
@@ -430,21 +541,150 @@ export function parseCliApplyJsonPayload(value: unknown, label = 'apply'): CliAp
 }
 
 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 verificationSourceRaw = record.verificationSource;
-  const verificationSource = verificationSourceRaw === undefined
-    ? undefined
-    : asString(record, 'verificationSource', 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 {
-    ...record,
-    contractVersion: asContractVersion(record),
-    grade: asString(record, 'grade', label),
-    score: asNumber(record, 'score', label),
-    verdict: asString(record, 'verdict', label),
-    violations: asArray(record, 'violations', label),
-    message: asString(record, 'message', label),
-    scopeGuardPassed: asBoolean(record, 'scopeGuardPassed', label),
-    verificationSource,
+    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,
+        }
+      : {}),
   };
 }