@neurcode-ai/contracts 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,137 @@
+export declare const CLI_JSON_CONTRACT_VERSION = "2026-04-04";
+export declare const RUNTIME_COMPATIBILITY_CONTRACT_ID = "neurcode-runtime-compatibility";
+export declare const RUNTIME_COMPATIBILITY_CONTRACT_VERSION = "2026-04-04";
+export declare const RUNTIME_COMPATIBILITY_MANIFEST_VERSION = "2026-04-04.1";
+export declare const RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION = 1;
+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;
+    minimumPeerVersions: Record<RuntimeComponent, RuntimeMinimumPeerVersions>;
+    validatedTriplets: RuntimeCompatibilityTriplet[];
+}
+export declare function getRuntimeCompatibilityManifest(): RuntimeCompatibilityManifest;
+export interface RuntimeCompatibilityDescriptor {
+    contractId: string;
+    runtimeContractVersion: string;
+    cliJsonContractVersion: string;
+    manifestVersion?: 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 interface CliVerifyJsonPayload extends CliContractBase {
+    grade: string;
+    score: number;
+    verdict: string;
+    violations: unknown[];
+    message: string;
+    scopeGuardPassed: boolean;
+    verificationSource?: 'api' | 'local_fallback' | 'policy_only' | string;
+    policyCompilation?: Record<string, unknown>;
+    changeContract?: Record<string, unknown>;
+}
+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;
+    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;
+}
+export declare function compareSemver(left: string, right: string): number | null;
+export declare function isSemverAtLeast(actual: string, minimum: string): boolean | null;
+export declare function getMinimumCompatiblePeerVersion(component: RuntimeComponent, peer: RuntimeComponent): string | undefined;
+export declare function getRuntimeMinimumPeerVersionMatrix(): Record<RuntimeComponent, RuntimeMinimumPeerVersions>;
+export declare function buildRuntimeCompatibilityDescriptor(component: RuntimeComponent, componentVersion: string): RuntimeCompatibilityDescriptor;
+export interface RuntimePeerCompatibilityIssue {
+    component: RuntimeComponent;
+    peer: RuntimeComponent;
+    required: string;
+    actual: string;
+    code: 'UNPARSABLE_VERSION' | 'VERSION_BELOW_MINIMUM';
+}
+export declare function evaluateRuntimePeerCompatibility(versions: Record<RuntimeComponent, string>): RuntimePeerCompatibilityIssue[];
+export declare function parseCliPlanJsonPayload(value: unknown, label?: string): CliPlanJsonPayload;
+export declare function parseCliApplyJsonPayload(value: unknown, label?: string): CliApplyJsonPayload;
+export declare function parseCliVerifyJsonPayload(value: unknown, label?: string): CliVerifyJsonPayload;
+export declare function parseCliPromptJsonPayload(value: unknown, label?: string): CliPromptJsonPayload;
+export declare function parseCliContractImportJsonPayload(value: unknown, label?: string): CliContractImportJsonPayload;
+export declare function parseCliShipJsonPayload(value: unknown, label?: string): CliShipJsonPayload;
+export declare function parseCliShipRunsJsonPayload(value: unknown, label?: string): CliShipRunsJsonPayload;
+export declare function parseCliShipResumeJsonPayload(value: unknown, label?: string): CliShipResumeJsonPayload;
+export declare function parseCliShipAttestationVerifyJsonPayload(value: unknown, label?: string): CliShipAttestationVerifyJsonPayload;
+export declare function parseCliCompatJsonPayload(value: unknown, label?: string): CliCompatJsonPayload;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,419 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION = exports.RUNTIME_COMPATIBILITY_MANIFEST_VERSION = exports.RUNTIME_COMPATIBILITY_CONTRACT_VERSION = exports.RUNTIME_COMPATIBILITY_CONTRACT_ID = exports.CLI_JSON_CONTRACT_VERSION = void 0;
+exports.getRuntimeCompatibilityManifest = getRuntimeCompatibilityManifest;
+exports.compareSemver = compareSemver;
+exports.isSemverAtLeast = isSemverAtLeast;
+exports.getMinimumCompatiblePeerVersion = getMinimumCompatiblePeerVersion;
+exports.getRuntimeMinimumPeerVersionMatrix = getRuntimeMinimumPeerVersionMatrix;
+exports.buildRuntimeCompatibilityDescriptor = buildRuntimeCompatibilityDescriptor;
+exports.evaluateRuntimePeerCompatibility = evaluateRuntimePeerCompatibility;
+exports.parseCliPlanJsonPayload = parseCliPlanJsonPayload;
+exports.parseCliApplyJsonPayload = parseCliApplyJsonPayload;
+exports.parseCliVerifyJsonPayload = parseCliVerifyJsonPayload;
+exports.parseCliPromptJsonPayload = parseCliPromptJsonPayload;
+exports.parseCliContractImportJsonPayload = parseCliContractImportJsonPayload;
+exports.parseCliShipJsonPayload = parseCliShipJsonPayload;
+exports.parseCliShipRunsJsonPayload = parseCliShipRunsJsonPayload;
+exports.parseCliShipResumeJsonPayload = parseCliShipResumeJsonPayload;
+exports.parseCliShipAttestationVerifyJsonPayload = parseCliShipAttestationVerifyJsonPayload;
+exports.parseCliCompatJsonPayload = parseCliCompatJsonPayload;
+exports.CLI_JSON_CONTRACT_VERSION = '2026-04-04';
+exports.RUNTIME_COMPATIBILITY_CONTRACT_ID = 'neurcode-runtime-compatibility';
+exports.RUNTIME_COMPATIBILITY_CONTRACT_VERSION = '2026-04-04';
+exports.RUNTIME_COMPATIBILITY_MANIFEST_VERSION = '2026-04-04.1';
+exports.RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION = 1;
+const RUNTIME_COMPATIBILITY_MANIFEST = {
+    schemaVersion: exports.RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
+    manifestVersion: exports.RUNTIME_COMPATIBILITY_MANIFEST_VERSION,
+    contractId: exports.RUNTIME_COMPATIBILITY_CONTRACT_ID,
+    runtimeContractVersion: exports.RUNTIME_COMPATIBILITY_CONTRACT_VERSION,
+    cliJsonContractVersion: exports.CLI_JSON_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.9.36',
+                action: '0.2.2',
+                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 = RUNTIME_COMPATIBILITY_MANIFEST.minimumPeerVersions;
+function getRuntimeCompatibilityManifest() {
+    return {
+        ...RUNTIME_COMPATIBILITY_MANIFEST,
+        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 },
+        })),
+    };
+}
+function asRecord(value, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`${label}: expected object`);
+    }
+    return value;
+}
+function asBoolean(record, key, label) {
+    if (typeof record[key] !== 'boolean') {
+        throw new Error(`${label}: expected ${key}:boolean`);
+    }
+    return record[key];
+}
+function asNumber(record, key, label) {
+    if (typeof record[key] !== 'number' || Number.isNaN(record[key])) {
+        throw new Error(`${label}: expected ${key}:number`);
+    }
+    return record[key];
+}
+function asString(record, key, label) {
+    if (typeof record[key] !== 'string') {
+        throw new Error(`${label}: expected ${key}:string`);
+    }
+    return record[key];
+}
+function asNullableString(record, key, label) {
+    const value = record[key];
+    if (value === null || typeof value === 'string') {
+        return value;
+    }
+    throw new Error(`${label}: expected ${key}:string|null`);
+}
+function asArray(record, key, label) {
+    if (!Array.isArray(record[key])) {
+        throw new Error(`${label}: expected ${key}:array`);
+    }
+    return record[key];
+}
+function asOptionalRecord(record, key, label) {
+    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;
+}
+function asOptionalString(record, key, label) {
+    const value = record[key];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string') {
+        throw new Error(`${label}: expected ${key}:string`);
+    }
+    return value;
+}
+function asContractVersion(record) {
+    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, key, label) {
+    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, label) {
+    if (value === undefined || value === null)
+        return {};
+    const record = asRecord(value, `${label}.minimumPeerVersions`);
+    const next = {};
+    for (const component of ['cli', 'action', 'api']) {
+        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, label) {
+    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`),
+        component: asRuntimeComponent(record, 'component', `${label}.compatibility`),
+        componentVersion: asString(record, 'componentVersion', `${label}.compatibility`),
+        minimumPeerVersions: parseRuntimeMinimumPeerVersions(record.minimumPeerVersions, `${label}.compatibility`),
+    };
+}
+function parseSemver(value) {
+    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];
+}
+function compareSemver(left, right) {
+    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;
+}
+function isSemverAtLeast(actual, minimum) {
+    const compare = compareSemver(actual, minimum);
+    if (compare === null)
+        return null;
+    return compare >= 0;
+}
+function getMinimumCompatiblePeerVersion(component, peer) {
+    return RUNTIME_MINIMUM_PEER_VERSIONS[component][peer];
+}
+function getRuntimeMinimumPeerVersionMatrix() {
+    return {
+        cli: { ...RUNTIME_MINIMUM_PEER_VERSIONS.cli },
+        action: { ...RUNTIME_MINIMUM_PEER_VERSIONS.action },
+        api: { ...RUNTIME_MINIMUM_PEER_VERSIONS.api },
+    };
+}
+function buildRuntimeCompatibilityDescriptor(component, componentVersion) {
+    return {
+        contractId: exports.RUNTIME_COMPATIBILITY_CONTRACT_ID,
+        runtimeContractVersion: exports.RUNTIME_COMPATIBILITY_CONTRACT_VERSION,
+        cliJsonContractVersion: exports.CLI_JSON_CONTRACT_VERSION,
+        manifestVersion: exports.RUNTIME_COMPATIBILITY_MANIFEST_VERSION,
+        component,
+        componentVersion,
+        minimumPeerVersions: { ...RUNTIME_MINIMUM_PEER_VERSIONS[component] },
+    };
+}
+function evaluateRuntimePeerCompatibility(versions) {
+    const issues = [];
+    for (const component of ['cli', 'action', 'api']) {
+        for (const peer of ['cli', 'action', 'api']) {
+            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;
+}
+function parseCliPlanJsonPayload(value, label = 'plan') {
+    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),
+    };
+}
+function parseCliApplyJsonPayload(value, label = 'apply') {
+    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),
+    };
+}
+function parseCliVerifyJsonPayload(value, label = 'verify') {
+    const record = asRecord(value, label);
+    const verificationSourceRaw = record.verificationSource;
+    const verificationSource = verificationSourceRaw === undefined
+        ? undefined
+        : asString(record, 'verificationSource', label);
+    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,
+    };
+}
+function parseCliPromptJsonPayload(value, label = 'prompt') {
+    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),
+    };
+}
+function parseCliContractImportJsonPayload(value, label = 'contract-import') {
+    const record = asRecord(value, label);
+    const parseModeRaw = record.parseMode;
+    let parseMode = 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;
+    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),
+    };
+}
+function parseCliShipJsonPayload(value, label = 'ship') {
+    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),
+    };
+}
+function parseCliShipRunsJsonPayload(value, label = 'ship-runs') {
+    const record = asRecord(value, label);
+    return {
+        ...record,
+        contractVersion: asContractVersion(record),
+        runs: asArray(record, 'runs', label),
+    };
+}
+function parseCliShipResumeJsonPayload(value, label = 'ship-resume') {
+    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),
+    };
+}
+function parseCliShipAttestationVerifyJsonPayload(value, label = 'ship-attestation-verify') {
+    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),
+    };
+}
+function parseCliCompatJsonPayload(value, label = 'compat') {
+    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),
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@neurcode-ai/contracts",
+  "version": "0.1.0",
+  "description": "Shared JSON contracts for Neurcode CLI, API, action, IDE, and MCP surfaces",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "tsx --test src/*.test.ts",
+    "prepare": "npm run build"
+  },
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.3.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,566 @@
+export const CLI_JSON_CONTRACT_VERSION = '2026-04-04';
+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_SCHEMA_VERSION = 1;
+
+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;
+  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,
+  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.9.36',
+        action: '0.2.2',
+        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,
+    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;
+  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 interface CliVerifyJsonPayload extends CliContractBase {
+  grade: string;
+  score: number;
+  verdict: string;
+  violations: unknown[];
+  message: string;
+  scopeGuardPassed: boolean;
+  verificationSource?: 'api' | 'local_fallback' | 'policy_only' | string;
+  policyCompilation?: Record<string, unknown>;
+  changeContract?: Record<string, unknown>;
+}
+
+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;
+  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 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`),
+    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,
+    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 {
+  const record = asRecord(value, label);
+  const verificationSourceRaw = record.verificationSource;
+  const verificationSource = verificationSourceRaw === undefined
+    ? undefined
+    : asString(record, 'verificationSource', label);
+  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,
+  };
+}
+
+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),
+  };
+}

package/src/runtime-compatibility-manifest.test.ts

@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import {
+  buildRuntimeCompatibilityDescriptor,
+  CLI_JSON_CONTRACT_VERSION,
+  evaluateRuntimePeerCompatibility,
+  getRuntimeCompatibilityManifest,
+  RUNTIME_COMPATIBILITY_CONTRACT_ID,
+  RUNTIME_COMPATIBILITY_CONTRACT_VERSION,
+  RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION,
+} from './index';
+
+test('runtime compatibility manifest envelope is aligned', () => {
+  const manifest = getRuntimeCompatibilityManifest();
+
+  assert.equal(manifest.schemaVersion, RUNTIME_COMPATIBILITY_MANIFEST_SCHEMA_VERSION);
+  assert.equal(manifest.contractId, RUNTIME_COMPATIBILITY_CONTRACT_ID);
+  assert.equal(manifest.runtimeContractVersion, RUNTIME_COMPATIBILITY_CONTRACT_VERSION);
+  assert.equal(manifest.cliJsonContractVersion, CLI_JSON_CONTRACT_VERSION);
+  assert.equal(typeof manifest.manifestVersion, 'string');
+  assert.equal(manifest.manifestVersion.length > 0, true);
+});
+
+test('validated runtime triplets are internally compatible', () => {
+  const manifest = getRuntimeCompatibilityManifest();
+  assert.equal(manifest.validatedTriplets.length > 0, true);
+
+  for (const triplet of manifest.validatedTriplets) {
+    const issues = evaluateRuntimePeerCompatibility(triplet.versions);
+    assert.deepEqual(
+      issues,
+      [],
+      `Triplet ${triplet.id} should be compatible but has issues: ${JSON.stringify(issues)}`
+    );
+  }
+});
+
+test('runtime compatibility descriptor includes manifest version', () => {
+  const manifest = getRuntimeCompatibilityManifest();
+  const descriptor = buildRuntimeCompatibilityDescriptor('cli', '0.9.36');
+  assert.equal(descriptor.manifestVersion, manifest.manifestVersion);
+});

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "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"]
+}