@neurcode-ai/contracts 0.1.2 → 0.1.3

package/src/remediation/capabilities.ts

@@ -0,0 +1,53 @@
+/**
+ * RemediationProviderCapabilities — describes what an adapter can and cannot do.
+ * Used by the registry for capability negotiation before dispatching requests.
+ */
+
+import type { GovernanceFindingCategory } from '../verification/taxonomy';
+
+export type RemediationExecutionMode = 'export' | 'assisted' | 'apply';
+
+export type RemediationTransport =
+  | 'stdin-stdout'    // local process: write prompt to stdin, read patch from stdout
+  | 'json-file'       // write request JSON to file, adapter reads and writes response JSON
+  | 'http-local'      // local HTTP (e.g. Cursor MCP server on localhost)
+  | 'http-remote';    // remote HTTP API (e.g. Anthropic Claude, OpenAI)
+
+export interface RemediationProviderCapabilities {
+  /** Stable provider ID (e.g. "cursor", "claude", "codex", "openai-compatible"). */
+  providerId: string;
+
+  /** Human-readable display name. */
+  providerName: string;
+
+  /** Supported execution modes. All providers must support 'export'. */
+  supportedModes: RemediationExecutionMode[];
+
+  /** Supported transport mechanisms. */
+  supportedTransports: RemediationTransport[];
+
+  /** Finding categories this provider handles well. */
+  supportedCategories: GovernanceFindingCategory[];
+
+  /** Structural rule IDs this provider has been validated against (e.g. ["SR001", "DS001"]). */
+  validatedRuleIds: string[];
+
+  /** Maximum context length the provider can accept (characters). */
+  maxContextChars: number;
+
+  /** True when the provider can run without network access (air-gapped). */
+  supportsOffline: boolean;
+
+  /** True when the provider requires network access to function. */
+  requiresNetwork: boolean;
+
+  /**
+   * True when the provider is deterministic given identical inputs.
+   * Currently false for all LLM-backed providers.
+   * True only for future AST-based adapters.
+   */
+  isDeterministic: boolean;
+
+  /** Provider schema version for capability negotiation. */
+  capabilitiesVersion: string;
+}

package/src/remediation/index.ts

@@ -0,0 +1,29 @@
+export type {
+  GovernanceRemediationContext,
+  GovernanceRemediationRequest,
+  ModificationBoundary,
+  RemediationCodeSpan,
+  RemediationReplayMetadata,
+  RemediationTrustBoundary,
+} from './request';
+
+export type {
+  GovernanceRemediationResponse,
+  RemediationPostcondition,
+  RemediationProviderMetadata,
+} from './response';
+
+export type {
+  RemediationExecutionMode,
+  RemediationProviderCapabilities,
+  RemediationTransport,
+} from './capabilities';
+
+export type {
+  RemediationGovernanceCheckResult,
+  RemediationPostconditionCheckResult,
+  RemediationScopeCheckResult,
+  RemediationSyntaxCheckResult,
+  RemediationValidationReceipt,
+  RemediationValidationResult,
+} from './validation';

package/src/remediation/request.ts

@@ -0,0 +1,236 @@
+/**
+ * GovernanceRemediationRequest — deterministic input to probabilistic remediation.
+ *
+ * This contract is:
+ *   - replayable: stable serialization, content-hashed
+ *   - auditable: provenance + plan linkage required
+ *   - bounded: allowed modification scope is explicit
+ *   - provider-agnostic: no provider SDK references
+ *
+ * IMPORTANT: This contract is governance infrastructure, not AI infrastructure.
+ * The finding it encodes is deterministic. The remediation it requests is optional and advisory.
+ */
+
+import type { DeterminismClassification, GovernanceFindingCategory, GovernanceSeverity } from '../verification';
+import type { GOVERNANCE_FINDINGS_SCHEMA_VERSION } from '../verification/taxonomy';
+
+// ── Span and location ──────────────────────────────────────────────────────────
+
+export interface RemediationCodeSpan {
+  /** 1-indexed start line (inclusive). */
+  startLine: number;
+  /** 1-indexed end line (inclusive). */
+  endLine: number;
+  /** 0-indexed start column (optional, when AST provides it). */
+  startColumn?: number;
+  /** 0-indexed end column (optional). */
+  endColumn?: number;
+}
+
+// ── Modification boundary ──────────────────────────────────────────────────────
+
+/**
+ * Explicit scope of changes the remediation is allowed to make.
+ * Adapters MUST communicate this to the external tool.
+ * The validation pipeline enforces it on the response.
+ */
+export interface ModificationBoundary {
+  /** Repo-relative file paths the remediation may touch. Must be non-empty. */
+  allowedFiles: string[];
+  /** If set, mutation is restricted to this span within the primary file. */
+  restrictToSpan?: RemediationCodeSpan;
+  /** Max lines the patch may add across all allowed files. */
+  maxLinesAdded?: number;
+  /** Max lines the patch may remove across all allowed files. */
+  maxLinesRemoved?: number;
+  /** When true, the remediation must not introduce new imports not already present. */
+  noNewImports?: boolean;
+  /** When true, the remediation must not rename symbols. */
+  noSymbolRename?: boolean;
+  /** Human-readable constraint summary for prompt injection. */
+  constraintSummary: string;
+}
+
+// ── Trust boundary ─────────────────────────────────────────────────────────────
+
+/**
+ * Declares what Neurcode can assert about this finding and what it cannot.
+ * Adapters must surface this to engineers — never hide trust boundaries.
+ */
+export interface RemediationTrustBoundary {
+  /** The finding itself is deterministic and reproducible. */
+  findingIsDeterministic: boolean;
+  /** The remediation is advisory — engineer must approve before application. */
+  remediationIsAdvisory: true;
+  /** Governance verdict is never determined by LLM output. */
+  governanceIsLlmFree: true;
+  /**
+   * The DeterminismClassification of the original finding.
+   * 'deterministic-structural' = AST-verified, highest trust.
+   * 'heuristic-advisory' = pattern match, lower confidence.
+   */
+  findingDeterminism: DeterminismClassification;
+  /** Confidence score of the original finding (0–1). */
+  findingConfidence: number;
+  /**
+   * Human-readable trust statement for display in remediation UIs.
+   * Example: "Finding is AST-verified (confidence 0.92). Fix is advisory and must be reviewed."
+   */
+  trustStatement: string;
+}
+
+// ── Replay metadata ────────────────────────────────────────────────────────────
+
+export interface RemediationReplayMetadata {
+  /** SHA-256 of the request payload excluding this field. Used for de-duplication and replay. */
+  requestHash: string;
+  /** The verify run that produced this finding. Links to ProvenanceRecord.runId. */
+  sourceRunId: string;
+  /** When the source verify run executed (ISO 8601). */
+  sourceRunAt: string;
+  /** Schema version of the governance findings that produced this request. */
+  sourceSchemaVersion: typeof GOVERNANCE_FINDINGS_SCHEMA_VERSION;
+  /** True when the request was re-generated from a replay artifact (not a live run). */
+  isReplay: boolean;
+  /** If replayed, the original request ID this was derived from. */
+  replayedFromRequestId?: string;
+}
+
+// ── Code context ───────────────────────────────────────────────────────────────
+
+/**
+ * Deterministic code context extracted from the repository at verify time.
+ * Frozen at request creation — not re-read at remediation time.
+ */
+export interface GovernanceRemediationContext {
+  /** Exact flagged code snippet (as found by the structural rule). */
+  codeExcerpt: string;
+  /** Lines surrounding the violation for LLM context (before + after). */
+  surroundingContext: string;
+  /** Relevant import lines from the file header. */
+  fileImports: string[];
+  /** Containing function/method signature if detectable. */
+  containingFunctionSignature?: string;
+  /** TypeScript/Python language of the file. */
+  language: 'typescript' | 'python' | 'javascript';
+  /**
+   * Structural explanation: why this specific AST pattern violates the rule.
+   * Generated by the structural rule, not by an LLM.
+   */
+  structuralExplanation: string;
+  /**
+   * Governance-level reasoning: what operational risk this creates.
+   * From the structural rule's operationalRisk field.
+   */
+  governanceReasoning: string;
+  /**
+   * Optional semantic hints: related symbols, patterns, or service names
+   * that may help the external tool understand system context.
+   * These are heuristic — never used for governance verdicts.
+   */
+  semanticHints?: string[];
+  /**
+   * PatternKind from the patch engine, if classified.
+   * Used to select the best adapter prompt template.
+   */
+  patternKind?: string;
+  /**
+   * Postconditions the fix must satisfy for governance re-verification to pass.
+   * Deterministic — derived from the rule's remediation instruction.
+   */
+  requiredPostconditions: string[];
+}
+
+// ── Main request ───────────────────────────────────────────────────────────────
+
+/**
+ * GovernanceRemediationRequest — the canonical deterministic handoff from
+ * Neurcode governance to an external remediation provider.
+ *
+ * Invariants:
+ *   1. This object is fully serializable and content-addressable.
+ *   2. It must never be modified after creation (immutable input to remediation).
+ *   3. Its existence does not imply that remediation will occur — export mode
+ *      generates this without invoking any provider.
+ */
+export interface GovernanceRemediationRequest {
+  /** Schema version — matches GOVERNANCE_FINDINGS_SCHEMA_VERSION for traceability. */
+  schemaVersion: '2026-05-11.1';
+
+  /** Deterministic request ID: sha256-128 of (findingId + sourceRunId + filePath + line). */
+  requestId: string;
+
+  /** ISO 8601 creation timestamp. */
+  createdAt: string;
+
+  // ── Finding linkage ──────────────────────────────────────────────────────────
+
+  /** GovernanceFinding.id from the canonical governance envelope. */
+  findingId: string;
+
+  /** StructuralViolation.ruleId (e.g. "SR001") or policy rule ID. */
+  ruleId: string;
+
+  /** Human-readable rule name (e.g. "Swallowed async rejection"). */
+  ruleName: string;
+
+  /** GovernanceFindingCategory from taxonomy. */
+  category: GovernanceFindingCategory;
+
+  severity: GovernanceSeverity;
+
+  determinismClassification: DeterminismClassification;
+
+  /** 0–1 confidence of the underlying finding. */
+  confidence: number;
+
+  /** Human-readable finding title. */
+  title: string;
+
+  // ── Location ─────────────────────────────────────────────────────────────────
+
+  /** Repo-relative file path (e.g. "src/services/auth/auth-service.ts"). */
+  filePath: string;
+
+  /** 1-indexed line number of the violation. */
+  line: number;
+
+  /** 0-indexed column of the violation. */
+  column: number;
+
+  /** Precise span when the rule provides it. */
+  span?: RemediationCodeSpan;
+
+  // ── Operational context ───────────────────────────────────────────────────────
+
+  /** What breaks in production if this is not fixed. */
+  operationalImplication: string;
+
+  /** The structural rule's built-in fix instruction (deterministic). */
+  remediationHint: string;
+
+  /** Code context frozen at verify time. */
+  context: GovernanceRemediationContext;
+
+  // ── Governance constraints ────────────────────────────────────────────────────
+
+  /** Explicit scope of allowed changes. Adapters must enforce this. */
+  allowedModificationBoundaries: ModificationBoundary;
+
+  // ── Provenance linkage ────────────────────────────────────────────────────────
+
+  /** Links to ProvenanceRecord.runId. */
+  provenanceRunId: string;
+
+  /** The plan ID active during the verify run (if any). */
+  planId?: string;
+
+  /** Schema version of the governance findings that produced this request. */
+  verifySchemaVersion: typeof GOVERNANCE_FINDINGS_SCHEMA_VERSION;
+
+  // ── Replay and trust ─────────────────────────────────────────────────────────
+
+  replayMetadata: RemediationReplayMetadata;
+
+  trustBoundary: RemediationTrustBoundary;
+}

package/src/remediation/response.ts

@@ -0,0 +1,129 @@
+/**
+ * GovernanceRemediationResponse — the structured output from an external remediation provider.
+ *
+ * IMPORTANT:
+ *   - This is ADVISORY. It must never be applied without engineer approval.
+ *   - Governance re-verification (neurcode verify) is required after application.
+ *   - The response is not a governance verdict — it is a suggestion.
+ */
+
+// ── Postcondition ──────────────────────────────────────────────────────────────
+
+/**
+ * A verifiable condition the patch must satisfy for the finding to be resolved.
+ * Generated deterministically from the structural rule — not by an LLM.
+ */
+export interface RemediationPostcondition {
+  /** Unique identifier for this postcondition. */
+  id: string;
+  /** Human-readable description. */
+  description: string;
+  /**
+   * Verification method:
+   *   structural-re-run     → re-run the original structural rule; violation must be absent
+   *   pattern-absent        → the violating pattern must not appear in the patched file
+   *   pattern-present       → a required pattern must appear (e.g. "throw err")
+   *   syntax-valid          → file must parse without TypeScript/Python syntax errors
+   *   scope-within-boundary → all changes must be within allowed modification boundary
+   */
+  verificationMethod:
+    | 'structural-re-run'
+    | 'pattern-absent'
+    | 'pattern-present'
+    | 'syntax-valid'
+    | 'scope-within-boundary';
+  /** For pattern-based methods: the pattern to check (regex string). */
+  pattern?: string;
+  /** Whether failing this postcondition is blocking (true) or advisory (false). */
+  blocking: boolean;
+}
+
+// ── Provider metadata ──────────────────────────────────────────────────────────
+
+export interface RemediationProviderMetadata {
+  /** Stable provider identifier (e.g. "cursor", "claude-3-5-sonnet", "codex"). */
+  providerId: string;
+  /** Human-readable provider name. */
+  providerName: string;
+  /** Model version if applicable. */
+  modelVersion?: string;
+  /** Total input tokens used (for cost tracking). */
+  inputTokens?: number;
+  /** Total output tokens generated. */
+  outputTokens?: number;
+  /** Wall-clock time from prompt send to response receive (ms). */
+  latencyMs?: number;
+}
+
+// ── Main response ──────────────────────────────────────────────────────────────
+
+/**
+ * GovernanceRemediationResponse — structured output from remediation provider.
+ *
+ * Invariants:
+ *   1. requestId must match the GovernanceRemediationRequest this responds to.
+ *   2. patchDiff must be a valid unified diff (--- a/... +++ b/... format).
+ *   3. This object is not applied automatically — engineer approval required.
+ *   4. Governance re-verification must run after any application.
+ */
+export interface GovernanceRemediationResponse {
+  /** Fixed schema version. */
+  schemaVersion: '2026-05-11.1';
+
+  /** Unique ID for this response. */
+  responseId: string;
+
+  /** Links to GovernanceRemediationRequest.requestId. */
+  requestId: string;
+
+  /** ISO 8601 generation timestamp. */
+  createdAt: string;
+
+  /** Provider that generated this response. */
+  provider: RemediationProviderMetadata;
+
+  // ── Generated patch ──────────────────────────────────────────────────────────
+
+  /**
+   * Unified diff of the proposed fix.
+   * Format: git-compatible unified diff (--- a/... +++ b/...).
+   * Empty when no patch could be generated (see status).
+   */
+  patchDiff: string;
+
+  /**
+   * Full patched file content (after applying patchDiff).
+   * Included when the provider returns full content.
+   * Optional — validation can work from patchDiff alone.
+   */
+  patchedContent?: string;
+
+  // ── Response metadata ─────────────────────────────────────────────────────────
+
+  /**
+   * Response status:
+   *   generated       → patch successfully produced
+   *   no-fix-needed   → provider determined no change required
+   *   unable-to-fix   → provider could not generate a valid fix
+   *   out-of-scope    → provider declined (change would exceed modification boundary)
+   */
+  status: 'generated' | 'no-fix-needed' | 'unable-to-fix' | 'out-of-scope';
+
+  /** Provider's explanation of the fix (or why no fix was generated). */
+  explanation: string;
+
+  /** Provider's self-reported confidence (0–1). Advisory — not used for governance. */
+  providerConfidence: number;
+
+  /** True when the provider flags this for mandatory human review. */
+  requiresManualReview: boolean;
+
+  /** Postconditions the patch should satisfy (copied from request, for validation reference). */
+  postconditions: RemediationPostcondition[];
+
+  /**
+   * Raw prompt used to generate this response.
+   * Included for auditability — engineers can inspect exactly what was sent.
+   */
+  promptUsed?: string;
+}

package/src/remediation/validation.ts

@@ -0,0 +1,109 @@
+/**
+ * RemediationValidationResult — output of the deterministic patch validation pipeline.
+ *
+ * The validation pipeline is always deterministic:
+ *   - syntax validation uses the TypeScript/Python parser
+ *   - scope validation checks file paths and line counts
+ *   - governance validation re-runs the original structural rule
+ *   - postcondition validation checks regex patterns
+ *
+ * LLM output is NEVER trusted without passing this pipeline.
+ * A failed validation does not modify any files.
+ */
+
+// ── Individual check results ───────────────────────────────────────────────────
+
+export interface RemediationSyntaxCheckResult {
+  valid: boolean;
+  errors: string[];
+  /** True when the parser was available; false when check was skipped. */
+  checkerAvailable: boolean;
+}
+
+export interface RemediationScopeCheckResult {
+  valid: boolean;
+  /** Files in the patch that are outside ModificationBoundary.allowedFiles. */
+  outOfScopeFiles: string[];
+  /** True when line count changes exceed boundary limits. */
+  lineLimitExceeded: boolean;
+  /** True when new imports were added in violation of noNewImports boundary. */
+  newImportsAdded: boolean;
+  details: string[];
+}
+
+export interface RemediationGovernanceCheckResult {
+  /**
+   * True when re-running the original structural rule on the patched file
+   * produces zero violations for the specific ruleId.
+   */
+  originalFindingResolved: boolean;
+  /** Any new structural violations introduced by the patch. */
+  newViolationsIntroduced: string[];
+  /** True when re-running governance found no regressions. */
+  noRegressions: boolean;
+  details: string[];
+}
+
+export interface RemediationPostconditionCheckResult {
+  postconditionId: string;
+  passed: boolean;
+  verificationMethod: string;
+  detail: string;
+}
+
+// ── Validation receipt ─────────────────────────────────────────────────────────
+
+/**
+ * Immutable receipt created by the validation pipeline.
+ * Stored as a governance artifact — append-only.
+ */
+export interface RemediationValidationReceipt {
+  schemaVersion: '2026-05-11.1';
+  receiptId: string;
+  /** Links to GovernanceRemediationRequest.requestId. */
+  requestId: string;
+  /** Links to GovernanceRemediationResponse.responseId. */
+  responseId: string;
+  validatedAt: string;
+  /** SHA-256 of the response patchDiff (for replay integrity). */
+  patchDiffHash: string;
+  /** SHA-256 of the patched file content (after applying diff). */
+  patchedContentHash?: string;
+  /** Overall validation verdict. */
+  verdict: 'approved' | 'rejected' | 'requires-review';
+  /** Human-readable summary of the validation result. */
+  summary: string;
+}
+
+// ── Main validation result ─────────────────────────────────────────────────────
+
+export interface RemediationValidationResult {
+  schemaVersion: '2026-05-11.1';
+
+  /** Overall: true only when all blocking checks pass. */
+  valid: boolean;
+
+  /** Whether the patch can be applied safely (valid + no new governance violations). */
+  safeToApply: boolean;
+
+  /** True when the original governance finding is resolved by the patch. */
+  findingResolved: boolean;
+
+  // ── Individual check results ───────────────────────────────────────────────────
+
+  syntax: RemediationSyntaxCheckResult;
+  scope: RemediationScopeCheckResult;
+  governance: RemediationGovernanceCheckResult;
+  postconditions: RemediationPostconditionCheckResult[];
+
+  // ── Summary ────────────────────────────────────────────────────────────────────
+
+  /** All blocking errors that prevent application. */
+  blockingErrors: string[];
+
+  /** Non-blocking warnings for engineer review. */
+  warnings: string[];
+
+  /** Immutable audit receipt. */
+  receipt: RemediationValidationReceipt;
+}

package/src/status-vocabulary.ts

@@ -0,0 +1,125 @@
+export const STATUS_VOCABULARY_VERSION = 'neurcode.status.v1';
+
+export const STATUS_TERMS = {
+  verificationComplete: 'Verification Complete',
+  safePatchApplied: 'Safe Patch Applied',
+  patchRejected: 'Patch Rejected',
+  rollbackAvailable: 'Rollback Available',
+  rollbackApplied: 'Rollback Applied',
+  replayAvailable: 'Replay Available',
+  evidenceGenerated: 'Evidence Generated',
+  manualReviewRecommended: 'Manual Review Recommended',
+  filesystemChangedSincePreview: 'Filesystem Changed Since Preview',
+  transactionVerified: 'Transaction Verified',
+  retrySafe: 'Retry Safe',
+} as const;
+
+export type StatusTermKey = keyof typeof STATUS_TERMS;
+export type SeverityLabel =
+  | 'critical'
+  | 'blocking'
+  | 'high'
+  | 'advisory'
+  | 'medium'
+  | 'warning'
+  | 'low'
+  | 'info';
+
+export const SEVERITY_LABELS: Record<SeverityLabel, string> = {
+  critical: 'Critical',
+  blocking: 'Blocking',
+  high: 'High',
+  advisory: 'Advisory',
+  medium: 'Medium',
+  warning: 'Warning',
+  low: 'Low',
+  info: 'Info',
+};
+
+export type VerificationSummaryState = 'clean' | 'issues' | 'partial' | 'failed';
+
+export const VERIFICATION_SUMMARY_LABELS: Record<VerificationSummaryState, string> = {
+  clean: STATUS_TERMS.verificationComplete,
+  issues: 'Verification Findings Detected',
+  partial: 'Verification Partially Complete',
+  failed: 'Verification Failed',
+};
+
+export type PatchState =
+  | 'applied'
+  | 'partial'
+  | 'rejected'
+  | 'stale_preview'
+  | 'filesystem_changed_since_preview'
+  | 'rollback_applied'
+  | 'rollback_stale'
+  | 'rollback_rejected';
+
+export type ConfidenceLabel = 'HIGH' | 'MEDIUM' | 'LOW';
+
+export const CONFIDENCE_LABELS: Record<ConfidenceLabel, string> = {
+  HIGH: 'HIGH confidence',
+  MEDIUM: 'MEDIUM confidence',
+  LOW: 'LOW confidence',
+};
+
+export function statusTerm(key: StatusTermKey): string {
+  return STATUS_TERMS[key];
+}
+
+export function severityLabel(severity: SeverityLabel): string {
+  return SEVERITY_LABELS[severity];
+}
+
+export function toPatchStateLabel(state: PatchState): string {
+  if (state === 'applied') return STATUS_TERMS.safePatchApplied;
+  if (state === 'partial') return `${STATUS_TERMS.safePatchApplied} · ${STATUS_TERMS.manualReviewRecommended}`;
+  if (state === 'stale_preview' || state === 'filesystem_changed_since_preview') {
+    return STATUS_TERMS.filesystemChangedSincePreview;
+  }
+  if (state === 'rollback_applied') return STATUS_TERMS.rollbackApplied;
+  if (state === 'rollback_stale') return `${STATUS_TERMS.patchRejected} · ${STATUS_TERMS.filesystemChangedSincePreview}`;
+  if (state === 'rollback_rejected') return STATUS_TERMS.patchRejected;
+  return STATUS_TERMS.patchRejected;
+}
+
+export function toRetrySafeMessage(context: string): string {
+  return `${context}. ${STATUS_TERMS.retrySafe}.`;
+}
+
+export function toManualReviewMessage(context: string): string {
+  return `${STATUS_TERMS.manualReviewRecommended}: ${context}`;
+}
+
+export function toVerificationCompleteTitle(confidenceSuffix = ''): string {
+  return `${STATUS_TERMS.verificationComplete}${confidenceSuffix}`;
+}
+
+export function toVerificationSummaryLabel(state: VerificationSummaryState): string {
+  return VERIFICATION_SUMMARY_LABELS[state];
+}
+
+export const DAEMON_ERROR_CODES = {
+  badRequest: 'daemon.bad_request',
+  unauthorized: 'daemon.unauthorized',
+  forbidden: 'daemon.forbidden',
+  notFound: 'daemon.not_found',
+  routeNotFound: 'daemon.route_not_found',
+  timeout: 'daemon.timeout',
+  conflict: 'daemon.conflict',
+  validationFailed: 'daemon.validation_failed',
+  rateLimited: 'daemon.rate_limited',
+  internalError: 'daemon.internal_error',
+  unknown: 'daemon.error',
+} as const;
+
+export type DaemonErrorCode = typeof DAEMON_ERROR_CODES[keyof typeof DAEMON_ERROR_CODES];
+
+export const ONBOARDING_HINTS = [
+  'Run your first verification',
+  'Review findings',
+  'Preview deterministic patch',
+  'Apply safe patch',
+  'View evidence',
+  'Replay execution history',
+] as const;