@neurcode-ai/contracts 0.1.3 → 0.2.1

package/src/status-vocabulary.ts

@@ -1,125 +0,0 @@
-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;

package/src/verification/canonical-finding.ts

@@ -1,196 +0,0 @@
-import type {
-  DeterminismClassification,
-  GovernanceFindingCategory,
-  GovernanceSourceSystem,
-} from './taxonomy';
-import { GOVERNANCE_FINDINGS_SCHEMA_VERSION } from './taxonomy';
-import type { GovernancePipelineSummary } from './pipeline';
-
-export type GovernanceSeverity = 'BLOCKING' | 'ADVISORY' | 'INFO';
-
-export interface GovernanceEvidence {
-  /** Human-readable excerpt (code, diff line, policy excerpt). */
-  excerpt: string;
-  /** Stable machine hint: AST path, regex id, policy rule type, etc. */
-  structuralHint?: string;
-  line?: number;
-  column?: number;
-  filePath?: string;
-}
-
-export interface GovernanceReplayMetadata {
-  evidenceArtifactRef?: string;
-  executionRecordRef?: string;
-  snapshotIds?: string[];
-  /** True when replay used only immutable artifacts with matching digests. */
-  reconstructedExactly?: boolean;
-  /** Present when bounded degradation occurred (truncation, missing artifact, etc.). */
-  boundedDegradation?: string[];
-}
-
-export interface GovernanceProvenanceMetadata {
-  runId?: string;
-  planId?: string | null;
-  verificationSource?: string;
-  policyLockFingerprint?: string | null;
-  compiledPolicyFingerprint?: string | null;
-  generatedAt?: string;
-  /**
-   * Canonical pipeline stage that emitted this finding. Additive lineage —
-   * never participates in the finding identity or the replay checksum, but
-   * threads governance computation provenance through to dashboards and audit.
-   */
-  producedByStage?: string;
-}
-
-export interface GovernanceSuppressionMetadata {
-  suppressed: boolean;
-  directive?: string;
-  exceptionId?: string;
-  reason?: string;
-}
-
-export interface GovernanceGraphMetadata {
-  edgeVia?: string;
-  fromRepo?: string;
-  toRepo?: string;
-  confidence?: 'high' | 'medium' | 'low';
-  traversalDepth?: number;
-  /** Explicit incompleteness — never omit when graph was capped. */
-  truncated?: boolean;
-  truncationReason?: string;
-}
-
-export interface GovernanceSemanticMetadata {
-  retrievalMethod?: 'deterministic-graph' | 'deterministic-tfidf' | 'heuristic-expansion';
-  matchedTerms?: string[];
-  tfidfScore?: number;
-  corpusCoverageRatio?: number;
-  indexTruncated?: boolean;
-  documentsIndexed?: number;
-  documentsCap?: number;
-}
-
-export interface GovernanceStructuralMetadata {
-  ruleId: string;
-  ruleName?: string;
-  policyRef?: string;
-  language?: string;
-  astNodeType?: string;
-}
-
-/**
- * Canonical normalized finding — single source of truth across CLI, CI, replay, dashboards.
- */
-export interface GovernanceFinding {
-  /** Deterministic id: sha256-128 of stable fields, or caller-supplied stable id. */
-  id: string;
-  category: GovernanceFindingCategory;
-  sourceSystem: GovernanceSourceSystem;
-  determinismClassification: DeterminismClassification;
-  severity: GovernanceSeverity;
-  /** 0–1; structural deterministic often 0.85–1.0; heuristics lower. */
-  confidence: number;
-  title: string;
-  evidence: GovernanceEvidence;
-  operationalImplication: string;
-  remediation: string;
-  replayMetadata?: GovernanceReplayMetadata;
-  provenanceMetadata?: GovernanceProvenanceMetadata;
-  suppressionMetadata?: GovernanceSuppressionMetadata;
-  graphMetadata?: GovernanceGraphMetadata;
-  semanticMetadata?: GovernanceSemanticMetadata;
-  structuralMetadata?: GovernanceStructuralMetadata;
-  /**
-   * When multiple raw signals were merged for reviewer compression.
-   * Primary finding keeps merged* fields; sources list contributing ids.
-   */
-  mergedFrom?: string[];
-}
-
-/**
- * Replay reconstruction status.
- *
- * exact              - checksums match, identical governance output
- * bounded-degradation - minor mismatch (e.g. missing artifact) but not a hard failure
- * drift-detected     - HARD FAILURE: same commit + diff + rules produced different output.
- *                      Checksum mismatch. Must be investigated before any governance trust.
- */
-export type ReplayReconstructionStatus = 'exact' | 'bounded-degradation' | 'drift-detected';
-
-/**
- * Phase 2: Typed drift reason taxonomy for replay integrity analysis.
- *
- * Each reason maps to a specific class of replay failure:
- *   finding-order-drift   - findings appear in different canonical order
- *   severity-drift        - a finding changed severity between runs
- *   determinism-drift     - a finding changed determinismClassification
- *   provenance-drift      - provenance metadata differs between runs
- *   suppression-drift     - suppression state changed between runs
- *   checksum-drift        - top-level replayChecksum mismatch (composite signal)
- *   missing-finding       - finding present in baseline but absent in replay
- *   extra-finding         - finding present in replay but absent in baseline
- */
-export type ReplayIntegrityDriftReason =
-  | 'finding-order-drift'
-  | 'severity-drift'
-  | 'determinism-drift'
-  | 'provenance-drift'
-  | 'suppression-drift'
-  | 'checksum-drift'
-  | 'missing-finding'
-  | 'extra-finding';
-
-export interface GovernanceReplayIntegrity {
-  status: ReplayReconstructionStatus;
-  missingArtifacts: string[];
-  provenanceMismatches: string[];
-  graphMismatches: string[];
-  semanticTruncationMismatches: string[];
-  notes: string[];
-  /** Phase 2: Typed drift reasons — empty if status === 'exact'. */
-  driftReasons?: ReplayIntegrityDriftReason[];
-}
-
-export interface GovernanceVerificationEnvelope {
-  schemaVersion: typeof GOVERNANCE_FINDINGS_SCHEMA_VERSION;
-  generatedAt: string;
-  findings: GovernanceFinding[];
-  /** Count of raw findings folded into merged clusters. */
-  compressedDuplicateCount: number;
-  /**
-   * Phase 6: Total count of cross-source-system duplicates absorbed into
-   * canonical finding identities. Equals compressedDuplicateCount but named
-   * explicitly for telemetry readability.
-   */
-  deduplicatedFindingCount?: number;
-  /**
-   * Phase 2: Count of findings demoted from BLOCKING to ADVISORY because they
-   * exist on unmodified (historical) lines. Visible for CI reporting.
-   */
-  legacyDebtFindingCount?: number;
-  /**
-   * Phase 3: Deterministic replay checksum.
-   * SHA-256 over the canonically sorted finding set (id + severity + determinism + file + line).
-   * Same commit + same diff + same rules MUST produce the same checksum.
-   * A mismatch between two runs with identical inputs indicates replay drift (trust failure).
-   */
-  replayChecksum?: string;
-  replayIntegrity?: GovernanceReplayIntegrity;
-  /** Pilot / operational summary lines (high-signal, not verbose). */
-  reviewerSummary?: string[];
-  /**
-   * Canonical governance pipeline summary — stage execution ledger surface.
-   *
-   * Additive observability. Excluded by design from:
-   *   - `replayChecksum` (computed only from finding-set fields)
-   *   - finding identity (`GovernanceFinding.id`)
-   *   - canonical sort order
-   *
-   * Present when verify ran with the staged pipeline runtime. Consumers
-   * (dashboards, audit replay, SLO gates) read this to explain HOW
-   * governance computation occurred. Absent on legacy / older-CLI envelopes.
-   */
-  pipelineSummary?: GovernancePipelineSummary;
-}
-

package/src/verification/index.ts

@@ -1,41 +0,0 @@
-export type {
-  DeterminismClassification,
-  GovernanceFindingCategory,
-  GovernanceSourceSystem,
-} from './taxonomy';
-export {
-  GOVERNANCE_FINDINGS_SCHEMA_VERSION,
-  isDeterminismClassification,
-} from './taxonomy';
-export type {
-  GovernanceEvidence,
-  GovernanceFinding,
-  GovernanceGraphMetadata,
-  GovernanceProvenanceMetadata,
-  GovernanceReplayIntegrity,
-  GovernanceReplayMetadata,
-  GovernanceSemanticMetadata,
-  GovernanceSeverity,
-  GovernanceStructuralMetadata,
-  GovernanceSuppressionMetadata,
-  GovernanceVerificationEnvelope,
-  ReplayIntegrityDriftReason,
-  ReplayReconstructionStatus,
-} from './canonical-finding';
-export type {
-  GovernancePipelineSummary,
-  GovernanceStageBoundary,
-  GovernanceStageFailure,
-  GovernanceStageFailureCategory,
-  GovernanceStageId,
-  GovernanceStageMetrics,
-  GovernanceStageReplayMetadata,
-  GovernanceStageResult,
-  GovernanceStageStatus,
-  GovernanceStageSummary,
-} from './pipeline';
-export {
-  GOVERNANCE_PIPELINE_SCHEMA_VERSION,
-  GOVERNANCE_STAGE_ORDER,
-  isGovernanceStageId,
-} from './pipeline';

package/src/verification/pipeline.ts

@@ -1,199 +0,0 @@
-/**
- * Canonical Governance Pipeline Contracts
- * ----------------------------------------
- * Shared, immutable types describing the staged decomposition of the verify runtime.
- *
- * These contracts are ADDITIVE. They do not replace, mutate, or re-encode the canonical
- * governance envelope (`GovernanceVerificationEnvelope`), the finding identity scheme,
- * or the replay checksum. Stage metadata flows alongside the envelope as an
- * out-of-band observability + replay-reconstruction surface.
- *
- * Design invariants:
- *   - Stage IDs are a closed set. Adding a new stage requires bumping the schema version.
- *   - Stage metadata never carries excerpts, file content, or PII.
- *   - Stage fingerprints are computed from stable identifiers — never wall-clock timestamps.
- *   - A stage's `replay.outputFingerprint` is independent of `replayChecksum`; the two
- *     are consistent but serve different audiences (stage lineage vs. envelope identity).
- */
-
-import type { DeterminismClassification } from './taxonomy';
-
-/**
- * Closed set of canonical governance pipeline stage identifiers.
- *
- * The order of declaration is the canonical execution order. Consumers MUST treat
- * this list as the authoritative pipeline definition for replay reconstruction
- * and explainability dashboards.
- */
-export type GovernanceStageId =
-  | 'diff-normalization'
-  | 'plan-sync'
-  | 'policy-lock'
-  | 'compiled-policy'
-  | 'policy-exceptions'
-  | 'structural-analysis'
-  | 'runtime-guard'
-  | 'intent-evaluation'
-  | 'semantic-analysis'
-  | 'policy-evaluation'
-  | 'suppression-evaluation'
-  | 'advisory-signals'
-  | 'change-contract'
-  | 'ai-debt-budget'
-  | 'governance-synthesis'
-  | 'provenance-generation'
-  | 'replay-integrity'
-  | 'remediation-export-preparation'
-  | 'evidence-generation'
-  | 'telemetry-harvest'
-  | 'ci-shaping'
-  | 'output-rendering';
-
-/**
- * Terminal state for a stage execution. `degraded` means the stage produced output
- * but a non-fatal anomaly was observed (e.g. truncation, partial dependency).
- */
-export type GovernanceStageStatus = 'succeeded' | 'skipped' | 'degraded' | 'failed';
-
-/**
- * Stage failure category. Maps to operator-visible runbooks and replay annotations.
- */
-export type GovernanceStageFailureCategory =
-  | 'timeout'
-  | 'exception'
-  | 'invariant-violation'
-  | 'degraded-dependency'
-  | 'aborted-precondition';
-
-export interface GovernanceStageMetrics {
-  /** Stage wall-clock duration in milliseconds. */
-  durationMs: number;
-  /** Size of the stage input as a stable item count (e.g. diff files, rules). Optional. */
-  inputItemCount?: number;
-  /** Size of the stage output as a stable item count (e.g. findings produced). Optional. */
-  outputItemCount?: number;
-  /** Delta of `process.memoryUsage().heapUsed` across the stage. Optional. */
-  memoryDeltaBytes?: number;
-}
-
-export interface GovernanceStageReplayMetadata {
-  stageId: GovernanceStageId;
-  /** Determinism classification of the stage itself (matches the most-deterministic finding it can emit). */
-  determinism: DeterminismClassification;
-  /** SHA-256 fingerprint of stage input, computed from stable identifiers only. */
-  inputFingerprint?: string;
-  /** SHA-256 fingerprint of stage output, computed from stable identifiers only. */
-  outputFingerprint?: string;
-  /** Stage IDs whose successful completion was a precondition for this stage. */
-  dependsOn: GovernanceStageId[];
-  /** Stage start time as an ISO-8601 timestamp. NOT included in fingerprints. */
-  startedAt: string;
-  /** Stage finish time as an ISO-8601 timestamp. NOT included in fingerprints. */
-  finishedAt: string;
-}
-
-export interface GovernanceStageFailure {
-  category: GovernanceStageFailureCategory;
-  /** Stable, PII-free message. Never includes source excerpts. */
-  message: string;
-  /** True when the rest of the pipeline can proceed in a degraded mode. */
-  recoverable: boolean;
-}
-
-/**
- * Boundary policy declared by a stage. The pipeline runtime uses this to decide
- * how to respond to failure (abort vs. degrade) and which stages must run first.
- */
-export interface GovernanceStageBoundary {
-  /** When true, the stage failing is reported but does NOT abort downstream stages. */
-  isolateFailure: boolean;
-  /** When true, the stage is required for governance correctness. */
-  required: boolean;
-  /** Stage IDs whose successful completion is required before this stage may execute. */
-  dependencies: GovernanceStageId[];
-}
-
-/**
- * Single-stage execution receipt. Persisted alongside the canonical envelope and
- * consumed by replay reconstruction, observability dashboards, and SLO gates.
- *
- * `output` is the typed stage payload; consumers MUST treat it as immutable.
- */
-export interface GovernanceStageResult<T = unknown> {
-  stageId: GovernanceStageId;
-  status: GovernanceStageStatus;
-  /** Stage output. `null` when status is 'failed' or 'skipped'. */
-  output: T | null;
-  metrics: GovernanceStageMetrics;
-  replay: GovernanceStageReplayMetadata;
-  failure?: GovernanceStageFailure;
-  /** Stage-emitted observability notes (PII-free, bounded). */
-  notes?: string[];
-}
-
-/**
- * Compact, replay-friendly summary of a stage. Embedded into telemetry and the
- * pipeline-level summary surface.
- */
-export interface GovernanceStageSummary {
-  stageId: GovernanceStageId;
-  status: GovernanceStageStatus;
-  determinism: DeterminismClassification;
-  durationMs: number;
-  inputFingerprint?: string;
-  outputFingerprint?: string;
-  dependsOn: GovernanceStageId[];
-  failureCategory?: GovernanceStageFailureCategory;
-}
-
-/**
- * Pipeline-level summary. Pinned across replays. The `pipelineFingerprint` is
- * a stable SHA-256 over the ordered (stageId, outputFingerprint, status) tuple
- * and is independent of `GovernanceVerificationEnvelope.replayChecksum`.
- */
-export interface GovernancePipelineSummary {
-  schemaVersion: typeof GOVERNANCE_PIPELINE_SCHEMA_VERSION;
-  pipelineFingerprint: string;
-  stages: GovernanceStageSummary[];
-  totalDurationMs: number;
-  degradedStages: GovernanceStageId[];
-  failedStages: GovernanceStageId[];
-}
-
-export const GOVERNANCE_PIPELINE_SCHEMA_VERSION = '2026-05-14.1' as const;
-
-/**
- * Type guard: is the given string a known stage identifier?
- */
-export function isGovernanceStageId(value: string): value is GovernanceStageId {
-  return GOVERNANCE_STAGE_ORDER.includes(value as GovernanceStageId);
-}
-
-/**
- * Canonical execution order. Mirror of the union above — exported as a runtime
- * value for iteration, indexing, and stage-ordering invariants.
- */
-export const GOVERNANCE_STAGE_ORDER: readonly GovernanceStageId[] = [
-  'diff-normalization',
-  'plan-sync',
-  'policy-lock',
-  'compiled-policy',
-  'policy-exceptions',
-  'structural-analysis',
-  'runtime-guard',
-  'intent-evaluation',
-  'semantic-analysis',
-  'policy-evaluation',
-  'suppression-evaluation',
-  'advisory-signals',
-  'change-contract',
-  'ai-debt-budget',
-  'governance-synthesis',
-  'provenance-generation',
-  'replay-integrity',
-  'remediation-export-preparation',
-  'evidence-generation',
-  'telemetry-harvest',
-  'ci-shaping',
-  'output-rendering',
-] as const;

package/src/verification/taxonomy.ts

@@ -1,46 +0,0 @@
-/**
- * Canonical determinism taxonomy — every governance finding MUST map to exactly one.
- * Do not blur or infer across these buckets in consumer UIs.
- */
-
-export type DeterminismClassification =
-  | 'deterministic-structural'
-  | 'deterministic-semantic'
-  | 'heuristic-advisory'
-  | 'llm-assisted-planning';
-
-export type GovernanceFindingCategory =
-  | 'structural'
-  | 'semantic-advisory'
-  | 'policy-engine'
-  | 'governance-constraint'
-  | 'intent-conditioned'
-  | 'flow-connectivity'
-  | 'regression'
-  | 'scope'
-  | 'replay'
-  | 'ci'
-  | 'pilot-metric'
-  | 'workspace-federation';
-
-export type GovernanceSourceSystem =
-  | 'structural-rules'
-  | 'policy-engine'
-  | 'governance-runtime'
-  | 'intent-engine'
-  | 'semantic-index'
-  | 'workspace-federation'
-  | 'replay-runtime'
-  | 'ci-adapter'
-  | 'pilot-metrics';
-
-export const GOVERNANCE_FINDINGS_SCHEMA_VERSION = '2026-05-11.1' as const;
-
-export function isDeterminismClassification(value: string): value is DeterminismClassification {
-  return (
-    value === 'deterministic-structural'
-    || value === 'deterministic-semantic'
-    || value === 'heuristic-advisory'
-    || value === 'llm-assisted-planning'
-  );
-}

package/tsconfig.json

@@ -1,19 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "commonjs",
-    "lib": ["ES2022"],
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "strict": true,
-    "esModuleInterop": true,
-    "skipLibCheck": true,
-    "forceConsistentCasingInFileNames": true,
-    "declaration": true,
-    "declarationMap": true,
-    "sourceMap": true,
-    "resolveJsonModule": true
-  },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
-}