@ornexus/neocortex 4.60.66 → 4.60.68

package/packages/client/dist/commands/doctor.js

@@ -0,0 +1,635 @@
+/**
+ * Read-only compatibility and release doctor (P223.02).
+ *
+ * The release contract is owned by P223.01. This command intentionally loads
+ * that authority through a narrow adapter instead of copying its validator.
+ * The dynamic boundary keeps this dependent story buildable while P223.01 is
+ * integrated in parallel.
+ */
+import { Buffer } from 'node:buffer';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { COMMAND_REGISTRY_CHECKSUM, COMMAND_REGISTRY_VERSION, } from '../generated/command-registry.generated.js';
+import { DEFAULT_SERVER_URL } from '../constants.js';
+import { getClientVersion } from '../version.js';
+export const DOCTOR_SCHEMA_VERSION = 'CompatibilityReleaseDoctor/1.0';
+export const DOCTOR_RESPONSE_SCHEMA_VERSION = 'CompatibilityDoctorResponse/1.0';
+export const DOCTOR_EXIT_CODES = Object.freeze({
+    SUCCESS: 0,
+    BLOCKED: 1,
+    USAGE: 2,
+});
+export const DOCTOR_REASON_CODES = Object.freeze({
+    HEALTHY: 'doctor-healthy',
+    OFFLINE: 'doctor-offline',
+    SERVER_UNREACHABLE: 'server-unreachable',
+    CLIENT_TOO_OLD: 'client-too-old',
+    SERVER_TOO_OLD: 'server-too-old',
+    PROTOCOL_MISMATCH: 'protocol-mismatch',
+    SCHEMA_MISMATCH: 'schema-mismatch',
+    CAPABILITY_MISMATCH: 'capability-mismatch',
+    REGISTRY_DRIFT: 'registry-drift',
+    MALFORMED_RESPONSE: 'malformed-response',
+    AUTHORITY_UNAVAILABLE: 'compatibility-authority-unavailable',
+    RELEASE_LIFECYCLE_UNAVAILABLE: 'release-lifecycle-unavailable',
+    REQUIRED_DIMENSION_BLOCKED: 'required-release-dimension-blocked',
+});
+const DIMENSIONS = Object.freeze([
+    'implementationComplete',
+    'betaOperable',
+    'releaseReady',
+    'productionPromoted',
+]);
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const MAX_FINDINGS = 32;
+const DEFAULT_TIMEOUT_MS = 5_000;
+const SAFE_REASON = /^[a-z][a-z0-9-]{0,63}$/u;
+const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,79}$/u;
+const SAFE_VERSION = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:[-+][A-Za-z0-9.-]{1,40})?$/u;
+const SAFE_REGISTRY_VERSION = /^[A-Za-z0-9][A-Za-z0-9._-]{0,31}$/u;
+const SHA256 = /^[a-f0-9]{64}$/u;
+const PROJECT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{15,127}$/u;
+const GIT_OBJECT_ID = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/u;
+const SAFE_EVIDENCE_REF = /^(?:local-gate|beta-receipt|release-gate|promotion-receipt|sha256):[a-f0-9]{64}$/u;
+const REMEDIATION = Object.freeze({
+    healthy: 'No compatibility remediation is required.',
+    offline: 'Rerun without --offline when read-only server evidence is available.',
+    unreachable: 'Check read-only server reachability, then rerun doctor.',
+    clientTooOld: 'Run a separately authorized client update, then rerun doctor.',
+    serverTooOld: 'Ask an authorized server operator to update the server, then rerun doctor.',
+    protocol: 'Align client and server protocol releases before invoking protected operations.',
+    schema: 'Use a client and server pair that supports the required public schemas.',
+    capability: 'Enable no feature here; use a release pair with the required capability set.',
+    registry: 'Install an exact release pair with the same command-registry checksum.',
+    malformed: 'Contact support with the reason code only; do not attach raw response data.',
+    authority: 'Integrate the P223.01 shared compatibility authority, then rerun doctor.',
+    lifecycle: 'Obtain bounded physical release evidence through separately authorized operations.',
+    required: 'Satisfy and verify the required physical release dimension through a separately authorized operation.',
+});
+const REASON_ORDER = new Map([
+    [DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 0],
+    [DOCTOR_REASON_CODES.AUTHORITY_UNAVAILABLE, 1],
+    [DOCTOR_REASON_CODES.CLIENT_TOO_OLD, 2],
+    [DOCTOR_REASON_CODES.SERVER_TOO_OLD, 3],
+    [DOCTOR_REASON_CODES.PROTOCOL_MISMATCH, 4],
+    [DOCTOR_REASON_CODES.SCHEMA_MISMATCH, 5],
+    [DOCTOR_REASON_CODES.CAPABILITY_MISMATCH, 6],
+    [DOCTOR_REASON_CODES.REGISTRY_DRIFT, 7],
+    [DOCTOR_REASON_CODES.SERVER_UNREACHABLE, 8],
+    [DOCTOR_REASON_CODES.OFFLINE, 9],
+    [DOCTOR_REASON_CODES.RELEASE_LIFECYCLE_UNAVAILABLE, 10],
+    [DOCTOR_REASON_CODES.REQUIRED_DIMENSION_BLOCKED, 11],
+    [DOCTOR_REASON_CODES.HEALTHY, 100],
+]);
+function unknownDimensions(reasonCode = 'release-evidence-unavailable') {
+    const dimension = () => Object.freeze({
+        value: 'unknown',
+        freshness: 'unknown',
+        reasonCodes: Object.freeze([reasonCode]),
+        evidenceRefs: Object.freeze([]),
+    });
+    return Object.freeze({
+        implementationComplete: dimension(),
+        betaOperable: dimension(),
+        releaseReady: dimension(),
+        productionPromoted: dimension(),
+    });
+}
+function parseRequiredDimension(value) {
+    const aliases = Object.freeze({
+        implementation: 'implementationComplete',
+        'implementation-complete': 'implementationComplete',
+        beta: 'betaOperable',
+        'beta-operable': 'betaOperable',
+        release: 'releaseReady',
+        'release-ready': 'releaseReady',
+        production: 'productionPromoted',
+        'production-promoted': 'productionPromoted',
+    });
+    return value ? aliases[value] ?? null : null;
+}
+export function parseDoctorArgs(args, env = process.env) {
+    let mode = 'online';
+    let json = false;
+    let serverUrl = env.NEOCORTEX_SERVER_URL ?? DEFAULT_SERVER_URL;
+    let serverUrlExplicit = false;
+    let requiredDimension = null;
+    let projectRoot = process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === '--offline') {
+            mode = 'offline';
+        }
+        else if (arg === '--json') {
+            json = true;
+        }
+        else if (arg === '--server-url') {
+            const value = args[index + 1];
+            if (!value)
+                throw new Error('doctor-server-url-required');
+            serverUrl = value;
+            serverUrlExplicit = true;
+            index += 1;
+        }
+        else if (arg === '--require') {
+            const value = args[index + 1];
+            const parsed = parseRequiredDimension(value);
+            if (!value || !parsed)
+                throw new Error('doctor-required-dimension-invalid');
+            requiredDimension = parsed;
+            index += 1;
+        }
+        else if (arg === '--project-root') {
+            const value = args[index + 1];
+            if (!value || value.length > 4_096 || value.includes('\0'))
+                throw new Error('doctor-project-root-invalid');
+            projectRoot = resolve(value);
+            index += 1;
+        }
+        else {
+            throw new Error('doctor-argument-invalid');
+        }
+    }
+    if (mode === 'offline' && serverUrlExplicit)
+        throw new Error('doctor-offline-server-url-conflict');
+    if (mode === 'offline') {
+        return Object.freeze({ mode, json, serverUrl: DEFAULT_SERVER_URL, requiredDimension, projectRoot });
+    }
+    if (serverUrl.length > 2_048)
+        throw new Error('doctor-server-url-invalid');
+    try {
+        const parsed = new URL(serverUrl);
+        if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            || parsed.username || parsed.password || parsed.search || parsed.hash)
+            throw new Error('url');
+    }
+    catch {
+        throw new Error('doctor-server-url-invalid');
+    }
+    return Object.freeze({ mode, json, serverUrl: serverUrl.replace(/\/+$/u, ''), requiredDimension, projectRoot });
+}
+function isCompatibilityAuthority(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return typeof candidate.createCompatibilityOffer === 'function'
+        && typeof candidate.isCompatibilityResultV1 === 'function'
+        && typeof candidate.validateReleaseLifecycle === 'function';
+}
+/** P223.01 integration seam. No fallback validator is maintained here. */
+export async function loadSharedCompatibilityAuthority() {
+    const candidates = [
+        '@neocortex/shared/compatibility',
+        '../../../shared/dist/compatibility/index.js',
+    ];
+    for (const specifier of candidates) {
+        try {
+            const moduleValue = await import(specifier);
+            if (isCompatibilityAuthority(moduleValue))
+                return moduleValue;
+        }
+        catch {
+            // P223.02 can be built before P223.01 lands. Online diagnosis fails closed;
+            // offline diagnosis remains useful and reports all remote truth as unknown.
+        }
+    }
+    return null;
+}
+/**
+ * Resolve the current project to an opaque selector without repairing or
+ * writing state. Git output is consumed locally and only domain-separated
+ * hashes plus the already-public project ID cross the network boundary.
+ */
+export function collectLocalReleaseLifecycleContext(projectRoot, authority) {
+    if (typeof authority.createReleaseLifecycleContext !== 'function')
+        return null;
+    try {
+        const statePath = join(projectRoot, '.neocortex', 'state.json');
+        const stat = statSync(statePath);
+        if (!stat.isFile() || stat.size <= 0 || stat.size > 1024 * 1024)
+            return null;
+        const state = JSON.parse(readFileSync(statePath, 'utf8'));
+        const config = state.config && typeof state.config === 'object' && !Array.isArray(state.config)
+            ? state.config
+            : state.project && typeof state.project === 'object' && !Array.isArray(state.project)
+                ? state.project
+                : null;
+        const projectId = config?.project_id;
+        if (typeof projectId !== 'string' || !PROJECT_ID.test(projectId))
+            return null;
+        const head = execFileSync('git', ['rev-parse', '--verify', 'HEAD'], {
+            cwd: projectRoot,
+            encoding: 'utf8',
+            timeout: 2_000,
+            maxBuffer: 1_024,
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim().toLowerCase();
+        if (!GIT_OBJECT_ID.test(head))
+            return null;
+        const lineageSha256 = createHash('sha256').update('git-lineage-v1\0').update(head).digest('hex');
+        const candidateId = `candidate-${createHash('sha256')
+            .update('release-candidate-v1\0').update(projectId).update('\0').update(head).digest('hex').slice(0, 32)}`;
+        return authority.createReleaseLifecycleContext({ projectId, candidateId, lineageSha256 });
+    }
+    catch {
+        return null;
+    }
+}
+function finding(severity, reasonCode, affectedDimension, remediation, evidenceRef = null) {
+    return Object.freeze({ severity, reasonCode, affectedDimension, evidenceRef, remediation });
+}
+function compareVersions(left, right) {
+    if (!SAFE_VERSION.test(left) || !SAFE_VERSION.test(right))
+        return null;
+    const numeric = (value) => value
+        .split(/[-+]/u, 1)[0]
+        .split('.')
+        .map(Number);
+    const leftParts = numeric(left);
+    const rightParts = numeric(right);
+    for (let index = 0; index < 3; index += 1) {
+        if (leftParts[index] === rightParts[index])
+            continue;
+        return leftParts[index] < rightParts[index] ? -1 : 1;
+    }
+    return 0;
+}
+function safeReasons(value) {
+    return Object.freeze([...new Set(value.filter((reason) => SAFE_REASON.test(reason)))].slice(0, 8).sort());
+}
+function safeIdentifiers(value) {
+    return Object.freeze([...new Set(value.filter((item) => SAFE_IDENTIFIER.test(item)))].slice(0, 32).sort());
+}
+function safeEvidenceRefs(value) {
+    return Object.freeze([...new Set(value.filter((item) => SAFE_EVIDENCE_REF.test(item)))].slice(0, 8).sort());
+}
+function asCompatibilityBoundary(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const candidate = value;
+    const registry = candidate.commandRegistry;
+    if (!['compatible', 'degraded', 'incompatible'].includes(String(candidate.status))
+        || typeof candidate.clientVersion !== 'string' || !SAFE_VERSION.test(candidate.clientVersion)
+        || typeof candidate.serverVersion !== 'string' || !SAFE_VERSION.test(candidate.serverVersion)
+        || !(candidate.protocolVersion === null || typeof candidate.protocolVersion === 'string' && SAFE_IDENTIFIER.test(candidate.protocolVersion))
+        || !Array.isArray(candidate.schemaVersions) || !candidate.schemaVersions.every((item) => typeof item === 'string')
+        || !Array.isArray(candidate.capabilityIds) || !candidate.capabilityIds.every((item) => typeof item === 'string')
+        || !Array.isArray(candidate.reasonCodes) || !candidate.reasonCodes.every((item) => typeof item === 'string')
+        || !registry || typeof registry.version !== 'string' || !SAFE_REGISTRY_VERSION.test(registry.version)
+        || typeof registry.checksum !== 'string' || !SHA256.test(registry.checksum)
+        || !['matched', 'mismatched', 'unknown'].includes(String(registry.status)))
+        return null;
+    return candidate;
+}
+function asLifecycleProjection(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const candidate = value;
+    if (typeof candidate.candidateId !== 'string' || !SAFE_IDENTIFIER.test(candidate.candidateId)
+        || typeof candidate.lineageSha256 !== 'string' || !SHA256.test(candidate.lineageSha256))
+        return null;
+    for (const name of DIMENSIONS) {
+        const dimension = candidate[name];
+        if (!dimension || typeof dimension !== 'object' || Array.isArray(dimension))
+            return null;
+        const record = dimension;
+        if (!(typeof record.value === 'boolean' || record.value === 'unknown')
+            || !['fresh', 'stale', 'unknown'].includes(String(record.freshness))
+            || !Array.isArray(record.reasonCodes) || !record.reasonCodes.every((item) => typeof item === 'string')
+            || !Array.isArray(record.evidenceRefs) || !record.evidenceRefs.every((item) => typeof item === 'string'))
+            return null;
+    }
+    return candidate;
+}
+function sortedFindings(findings) {
+    const severityOrder = { error: 0, warning: 1, info: 2 };
+    const dimensionOrder = new Map([
+        ['compatibility', 0], ['releaseLifecycle', 1],
+        ['implementationComplete', 2], ['betaOperable', 3], ['releaseReady', 4], ['productionPromoted', 5],
+    ]);
+    return Object.freeze([...findings]
+        .sort((left, right) => severityOrder[left.severity] - severityOrder[right.severity]
+        || (REASON_ORDER.get(left.reasonCode) ?? 50) - (REASON_ORDER.get(right.reasonCode) ?? 50)
+        || (dimensionOrder.get(left.affectedDimension) ?? 99) - (dimensionOrder.get(right.affectedDimension) ?? 99)
+        || left.reasonCode.localeCompare(right.reasonCode))
+        .slice(0, MAX_FINDINGS));
+}
+function compatibilityShell(clientVersion) {
+    return Object.freeze({
+        status: 'unknown',
+        clientVersion,
+        serverVersion: null,
+        protocolVersion: null,
+        schemaVersions: Object.freeze([]),
+        capabilityIds: Object.freeze([]),
+        registry: Object.freeze({
+            localVersion: COMMAND_REGISTRY_VERSION,
+            localChecksum: COMMAND_REGISTRY_CHECKSUM,
+            remoteVersion: null,
+            remoteChecksum: null,
+            status: 'unknown',
+        }),
+    });
+}
+function finalizeReport(input) {
+    const findings = [...input.findings];
+    const dimensions = input.dimensions ?? unknownDimensions();
+    let blocked = input.incompatible;
+    if (input.requiredDimension && dimensions[input.requiredDimension].value !== true) {
+        blocked = true;
+        findings.push(finding('error', DOCTOR_REASON_CODES.REQUIRED_DIMENSION_BLOCKED, input.requiredDimension, REMEDIATION.required, dimensions[input.requiredDimension].evidenceRefs[0] ?? null));
+    }
+    const ordered = sortedFindings(findings);
+    const overall = blocked
+        ? 'incompatible'
+        : ordered.some((item) => item.severity === 'warning') ? 'degraded' : 'healthy';
+    return Object.freeze({
+        schemaVersion: DOCTOR_SCHEMA_VERSION,
+        publicSafe: true,
+        readOnly: true,
+        mode: input.mode,
+        overall,
+        exitCode: blocked ? DOCTOR_EXIT_CODES.BLOCKED : DOCTOR_EXIT_CODES.SUCCESS,
+        compatibility: input.compatibility ?? compatibilityShell(input.clientVersion),
+        release: Object.freeze({
+            candidateId: input.candidateId ?? null,
+            lineageSha256: input.lineageSha256 ?? null,
+            requiredDimension: input.requiredDimension,
+            dimensions,
+        }),
+        findings: ordered,
+    });
+}
+function responseEnvelope(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const candidate = value;
+    if ('compatibility' in candidate) {
+        if (candidate.schemaVersion !== undefined && candidate.schemaVersion !== DOCTOR_RESPONSE_SCHEMA_VERSION)
+            return null;
+        return { compatibility: candidate.compatibility, ...(candidate.releaseLifecycle !== undefined ? { releaseLifecycle: candidate.releaseLifecycle } : {}) };
+    }
+    // A bare P223.01 compatibility result is accepted as a reduced projection.
+    return { compatibility: value };
+}
+async function fetchDoctorResponse(fetcher, serverUrl, offer, releaseContext) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    try {
+        const encodedOffer = Buffer.from(JSON.stringify(offer), 'utf8').toString('base64url');
+        if (encodedOffer.length > 8_192)
+            return { kind: 'malformed' };
+        const encodedContext = releaseContext === null
+            ? null
+            : Buffer.from(JSON.stringify(releaseContext), 'utf8').toString('base64url');
+        if (encodedContext && encodedContext.length > 2_048)
+            return { kind: 'malformed' };
+        const response = await fetcher(`${serverUrl}/api/v1/compatibility`, {
+            method: 'GET',
+            headers: Object.freeze({
+                Accept: 'application/json',
+                'Cache-Control': 'no-store',
+                'X-Neocortex-Compatibility-Offer': encodedOffer,
+                ...(encodedContext ? { 'X-Neocortex-Release-Context': encodedContext } : {}),
+            }),
+            signal: controller.signal,
+        });
+        if (response.status === 404 || response.status === 405 || response.status === 426)
+            return { kind: 'server-too-old' };
+        if (!response.ok)
+            return response.status >= 500 ? { kind: 'unreachable' } : { kind: 'malformed' };
+        const body = await response.text();
+        if (Buffer.byteLength(body, 'utf8') > MAX_RESPONSE_BYTES)
+            return { kind: 'malformed' };
+        try {
+            return { kind: 'ok', value: JSON.parse(body) };
+        }
+        catch {
+            return { kind: 'malformed' };
+        }
+    }
+    catch {
+        return { kind: 'unreachable' };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function offlineReport(clientVersion, requiredDimension) {
+    return finalizeReport({
+        mode: 'offline',
+        clientVersion,
+        requiredDimension,
+        incompatible: false,
+        findings: [
+            finding('warning', DOCTOR_REASON_CODES.OFFLINE, 'compatibility', REMEDIATION.offline),
+            finding('warning', DOCTOR_REASON_CODES.RELEASE_LIFECYCLE_UNAVAILABLE, 'releaseLifecycle', REMEDIATION.lifecycle),
+        ],
+    });
+}
+export async function runDoctor(options, dependencies = {}) {
+    const clientVersion = (dependencies.getClientVersion ?? getClientVersion)();
+    if (options.mode === 'offline')
+        return offlineReport(clientVersion, options.requiredDimension);
+    const authority = await (dependencies.loadCompatibilityAuthority ?? loadSharedCompatibilityAuthority)();
+    if (!authority) {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [finding('error', DOCTOR_REASON_CODES.AUTHORITY_UNAVAILABLE, 'compatibility', REMEDIATION.authority)],
+        });
+    }
+    let offer;
+    try {
+        offer = authority.createCompatibilityOffer({
+            clientVersion,
+            registryVersion: COMMAND_REGISTRY_VERSION,
+            registryChecksum: COMMAND_REGISTRY_CHECKSUM,
+        });
+    }
+    catch {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [finding('error', DOCTOR_REASON_CODES.AUTHORITY_UNAVAILABLE, 'compatibility', REMEDIATION.authority)],
+        });
+    }
+    const releaseContext = (dependencies.collectReleaseContext ?? collectLocalReleaseLifecycleContext)(options.projectRoot, authority);
+    const fetcher = dependencies.fetch ?? globalThis.fetch;
+    const remote = await fetchDoctorResponse(fetcher, options.serverUrl, offer, releaseContext);
+    if (remote.kind === 'unreachable') {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: false,
+            findings: [
+                finding('warning', DOCTOR_REASON_CODES.SERVER_UNREACHABLE, 'compatibility', REMEDIATION.unreachable),
+                finding('warning', DOCTOR_REASON_CODES.RELEASE_LIFECYCLE_UNAVAILABLE, 'releaseLifecycle', REMEDIATION.lifecycle),
+            ],
+        });
+    }
+    if (remote.kind === 'server-too-old') {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [
+                finding('error', DOCTOR_REASON_CODES.SERVER_TOO_OLD, 'compatibility', REMEDIATION.serverTooOld),
+                finding('warning', DOCTOR_REASON_CODES.RELEASE_LIFECYCLE_UNAVAILABLE, 'releaseLifecycle', REMEDIATION.lifecycle),
+            ],
+        });
+    }
+    if (remote.kind === 'malformed') {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [finding('error', DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 'compatibility', REMEDIATION.malformed)],
+        });
+    }
+    const envelope = responseEnvelope(remote.value);
+    if (!envelope || !authority.isCompatibilityResultV1(envelope.compatibility)) {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [finding('error', DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 'compatibility', REMEDIATION.malformed)],
+        });
+    }
+    const result = asCompatibilityBoundary(envelope.compatibility);
+    if (!result || result.clientVersion !== clientVersion) {
+        return finalizeReport({
+            mode: 'online', clientVersion, requiredDimension: options.requiredDimension, incompatible: true,
+            findings: [finding('error', DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 'compatibility', REMEDIATION.malformed)],
+        });
+    }
+    const compatibility = Object.freeze({
+        status: result.status,
+        clientVersion,
+        serverVersion: result.serverVersion,
+        protocolVersion: result.protocolVersion,
+        schemaVersions: safeIdentifiers(result.schemaVersions),
+        capabilityIds: safeIdentifiers(result.capabilityIds),
+        registry: Object.freeze({
+            localVersion: COMMAND_REGISTRY_VERSION,
+            localChecksum: COMMAND_REGISTRY_CHECKSUM,
+            remoteVersion: result.commandRegistry.version,
+            remoteChecksum: result.commandRegistry.checksum,
+            status: result.commandRegistry.status,
+        }),
+    });
+    const findings = [];
+    const resultReasons = safeReasons(result.reasonCodes);
+    const versionOrder = compareVersions(clientVersion, result.serverVersion);
+    if (result.status === 'incompatible' && versionOrder === -1) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.CLIENT_TOO_OLD, 'compatibility', REMEDIATION.clientTooOld, `client-version:${clientVersion}`));
+    }
+    else if (result.status === 'incompatible' && versionOrder === 1) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.SERVER_TOO_OLD, 'compatibility', REMEDIATION.serverTooOld, `server-version:${result.serverVersion}`));
+    }
+    if (resultReasons.some((reason) => reason.includes('protocol'))) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.PROTOCOL_MISMATCH, 'compatibility', REMEDIATION.protocol));
+    }
+    if (resultReasons.some((reason) => reason.includes('schema'))) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.SCHEMA_MISMATCH, 'compatibility', REMEDIATION.schema));
+    }
+    if (resultReasons.some((reason) => reason.includes('capability'))) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.CAPABILITY_MISMATCH, 'compatibility', REMEDIATION.capability));
+    }
+    if (result.commandRegistry.status === 'mismatched'
+        || result.commandRegistry.version !== COMMAND_REGISTRY_VERSION
+        || result.commandRegistry.checksum !== COMMAND_REGISTRY_CHECKSUM) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.REGISTRY_DRIFT, 'compatibility', REMEDIATION.registry, `sha256:${result.commandRegistry.checksum}`));
+    }
+    if (result.status === 'incompatible' && findings.length === 0) {
+        findings.push(finding('error', DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 'compatibility', REMEDIATION.malformed));
+    }
+    else if (result.status === 'degraded') {
+        for (const reason of resultReasons)
+            findings.push(finding('warning', reason, 'compatibility', REMEDIATION.lifecycle));
+    }
+    let dimensions = unknownDimensions();
+    let candidateId = null;
+    let lineageSha256 = null;
+    let lifecycleMalformed = false;
+    if (envelope.releaseLifecycle === undefined) {
+        findings.push(finding('warning', DOCTOR_REASON_CODES.RELEASE_LIFECYCLE_UNAVAILABLE, 'releaseLifecycle', REMEDIATION.lifecycle));
+    }
+    else {
+        const validation = authority.validateReleaseLifecycle(envelope.releaseLifecycle);
+        const projection = validation.accepted ? asLifecycleProjection(validation.projection) : null;
+        if (!projection) {
+            lifecycleMalformed = true;
+            findings.push(finding('error', DOCTOR_REASON_CODES.MALFORMED_RESPONSE, 'releaseLifecycle', REMEDIATION.malformed));
+            for (const reason of safeReasons(validation.reasonCodes)) {
+                findings.push(finding('error', reason, 'releaseLifecycle', REMEDIATION.lifecycle));
+            }
+        }
+        else {
+            candidateId = projection.candidateId;
+            lineageSha256 = projection.lineageSha256;
+            const mapped = {};
+            for (const name of DIMENSIONS) {
+                const source = projection[name];
+                mapped[name] = Object.freeze({
+                    value: source.value,
+                    freshness: source.freshness,
+                    reasonCodes: safeReasons(source.reasonCodes),
+                    evidenceRefs: safeEvidenceRefs(source.evidenceRefs),
+                });
+                if (source.value !== true || source.freshness !== 'fresh') {
+                    for (const reason of safeReasons(source.reasonCodes)) {
+                        findings.push(finding('warning', reason, name, REMEDIATION.lifecycle, safeEvidenceRefs(source.evidenceRefs)[0] ?? null));
+                    }
+                }
+            }
+            dimensions = Object.freeze(mapped);
+        }
+    }
+    if (findings.length === 0)
+        findings.push(finding('info', DOCTOR_REASON_CODES.HEALTHY, 'compatibility', REMEDIATION.healthy));
+    return finalizeReport({
+        mode: 'online',
+        clientVersion,
+        compatibility,
+        dimensions,
+        candidateId,
+        lineageSha256,
+        requiredDimension: options.requiredDimension,
+        findings,
+        incompatible: result.status === 'incompatible' || lifecycleMalformed,
+    });
+}
+export function renderDoctorReport(report) {
+    const lines = [
+        'Neocortex compatibility and release doctor (read-only)',
+        `Result: ${report.overall} (exit ${report.exitCode})`,
+        `Mode: ${report.mode}`,
+        `Compatibility: ${report.compatibility.status}`,
+        `Client: ${report.compatibility.clientVersion}`,
+        `Server: ${report.compatibility.serverVersion ?? 'unknown'}`,
+        `Registry: ${report.compatibility.registry.status}`,
+        '',
+        'Release lifecycle:',
+    ];
+    for (const name of DIMENSIONS) {
+        const dimension = report.release.dimensions[name];
+        lines.push(`  ${name}: ${String(dimension.value)} (${dimension.freshness}) [${dimension.reasonCodes.join(',') || 'none'}]`);
+    }
+    lines.push('', 'Ordered findings:');
+    for (const item of report.findings) {
+        lines.push(`  ${item.severity.toUpperCase()} ${item.reasonCode} dimension=${item.affectedDimension} evidence=${item.evidenceRef ?? 'none'}`);
+        lines.push(`    ${item.remediation}`);
+    }
+    lines.push('', 'Doctor made no repairs or state changes.');
+    return lines.join('\n');
+}
+export async function doctorCliHandler(args, dependencies = {}) {
+    const stdout = dependencies.stdout ?? console.log;
+    const stderr = dependencies.stderr ?? console.error;
+    let options;
+    try {
+        options = parseDoctorArgs(args, dependencies.env ?? process.env);
+    }
+    catch (error) {
+        const reasonCode = error instanceof Error && SAFE_REASON.test(error.message)
+            ? error.message : 'doctor-argument-invalid';
+        stderr(`Error: ${reasonCode}`);
+        return DOCTOR_EXIT_CODES.USAGE;
+    }
+    const report = await runDoctor(options, dependencies);
+    stdout(options.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report));
+    return report.exitCode;
+}