semantic-js-mcp 0.8.1 → 0.9.0

package/scripts/generate-protocol-reference.mjs

@@ -12,13 +12,18 @@ import {
   CLI_ARGUMENT,
   CLI_COMMAND,
   CLI_MESSAGE,
+  COMMON_VALUE,
   CONFIGURATION_FILE,
   CONTENT_FRESHNESS,
   DEFAULT,
   DEFINITION_MATCH,
   DEFINITION_RESOLUTION_METHOD,
+  DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_EVIDENCE_REASON,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_LANGUAGE,
+  DIAGNOSTIC_PROVIDER,
+  DIAGNOSTIC_REGION,
   DIAGNOSTIC_SEVERITY,
   DOCTOR_CHECK,
   DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
@@ -29,10 +34,12 @@ import {
   ERROR_CODE,
   EVIDENCE_TYPE,
   FINGERPRINT_ALGORITHM,
+  FINGERPRINT_FORMAT,
   FORBIDDEN_PUBLIC_FIELD,
   INTERNAL_RESOLUTION_SOURCE,
   LANGUAGE_ID,
   LIMIT_MODE,
+  LSP_METHOD,
   NODE_EVENT,
   PRESENTATION_MODE,
   PACKAGE_PATH,
@@ -41,14 +48,17 @@ import {
   REFERENCE_SET_CHANGE_TYPE,
   REQUIRED_RUNTIME_COMPONENT,
   RUNTIME_COMMAND,
+  RUNTIME_PACKAGE,
   RUNTIME_REQUIREMENT,
   RUNTIME_REQUIREMENT_KIND,
   RESULT_SCHEMA,
   SERVER_VERSION,
+  SEARCH_SCOPE,
   SIGNATURE_SOURCE,
   PROCESS_EXIT_CODE,
   RUNTIME_STATUS,
   TOOL_ORDER,
+  TOOL_DESCRIPTION,
   TYPESCRIPT_PROJECT_KIND,
   SOURCE_EXCLUDED_GLOBS,
   SOURCE_EXTENSION,
@@ -81,12 +91,15 @@ const content =
     "",
     "Generated from `protocol.mjs`. Do not edit this file directly.",
     "",
-    `Server version: \`${SERVER_VERSION}\``,
-    `Server name: \`${PRODUCT.NAME}\``,
+    `Producer: \`${PRODUCT.NAME}\` version \`${SERVER_VERSION}\``,
     `Display name: \`${PRODUCT.DISPLAY_NAME}\``,
-    `Result schema: \`${RESULT_SCHEMA.NAME}\` version \`${RESULT_SCHEMA.VERSION}\``,
+    `Result schema version: \`${RESULT_SCHEMA.VERSION}\``,
     "",
     section("Tool Order", Object.fromEntries(TOOL_ORDER.map((tool) => [tool, tool]))),
+    section("Common Values", COMMON_VALUE),
+    section("Search Scope", SEARCH_SCOPE),
+    section("Runtime Packages", RUNTIME_PACKAGE),
+    namedSection("Tool Descriptions", TOOL_DESCRIPTION),
     section("Workspace Configuration File Names", Object.fromEntries(WORKSPACE_CONFIGURATION_FILE_NAMES.map((name) => [name, name]))),
     section("Configuration Files", CONFIGURATION_FILE),
     section("Workspace Root Marker File Names", Object.fromEntries(WORKSPACE_ROOT_MARKER_FILE_NAMES.map((name) => [name, name]))),
@@ -98,10 +111,15 @@ const content =
     section("Collection Status", COLLECTION_STATUS),
     section("Presentation Mode", PRESENTATION_MODE),
     section("Limit Mode", LIMIT_MODE),
+    section("LSP Methods", LSP_METHOD),
     section("Accounting Status", ACCOUNTING_STATUS),
     section("Definition Match", DEFINITION_MATCH),
+    section("Definition Selection Status", DEFINITION_SELECTION_STATUS),
     section("Signature Source", SIGNATURE_SOURCE),
     section("Diagnostic Freshness", DIAGNOSTIC_FRESHNESS),
+    section("Diagnostic Provider", DIAGNOSTIC_PROVIDER),
+    section("Diagnostic Region", DIAGNOSTIC_REGION),
+    section("Diagnostic Language", DIAGNOSTIC_LANGUAGE),
     section("Diagnostic Severity", DIAGNOSTIC_SEVERITY),
     section("Diagnostic Evidence Reason", DIAGNOSTIC_EVIDENCE_REASON),
     section("Evidence Status", EVIDENCE_STATUS),
@@ -109,6 +127,7 @@ const content =
     section("Error Code", ERROR_CODE),
     section("Evidence Type", EVIDENCE_TYPE),
     section("Fingerprint Algorithm", FINGERPRINT_ALGORITHM),
+    section("Fingerprint Format", FINGERPRINT_FORMAT),
     section("Reference Discovery Method", REFERENCE_DISCOVERY_METHOD),
     section("Reference Set Change Type", REFERENCE_SET_CHANGE_TYPE),
     section("Definition Resolution Method", DEFINITION_RESOLUTION_METHOD),

package/scripts/postpublication-smoke.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+import {spawn} from "node:child_process";
+import {mkdtemp, mkdir, readFile, realpath, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import path from "node:path";
+import {
+  CI_EXIT_CODE,
+  CI_STATUS,
+  CLI_ARGUMENT,
+  CLI_COMMAND,
+  CONFIGURATION_FILE,
+  DOCTOR_CHECK,
+  DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
+  NODE_EVENT,
+  PRODUCT,
+} from "../protocol.mjs";
+import {verifyCodexPlugin} from "./codex-plugin-verification.mjs";
+import {NPM_DISTRIBUTION, npmExecutableName} from "./distribution-policy.mjs";
+import {RELEASE_ARGUMENT, RELEASE_CHECK, RELEASE_MODE, RELEASE_REASON, releaseStatus} from "./release-contract.mjs";
+
+const POSTPUBLICATION_PATH = Object.freeze({
+  NPM_CACHE: "npm-cache",
+  CONSUMER: "consumer",
+  DEPENDENCY_DIRECTORY: "node_modules",
+  BINARY_DIRECTORY: ".bin",
+});
+
+const NPM_COMMAND = Object.freeze({
+  VIEW: "view",
+  INSTALL: "install",
+  VERSION: "version",
+});
+
+const NPM_ARGUMENT = Object.freeze({
+  JSON: "--json",
+  IGNORE_SCRIPTS: "--ignore-scripts",
+  NO_AUDIT: "--no-audit",
+  NO_FUND: "--no-fund",
+  SAVE_EXACT: "--save-exact",
+});
+
+const requestedVersion = process.argv[RELEASE_ARGUMENT.PACKAGE_VERSION_OFFSET];
+const npmCli = process.env.npm_execpath;
+const checks = [];
+let workspace;
+
+function run(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {stdio: ["ignore", "pipe", "pipe"], ...options});
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on(NODE_EVENT.ERROR, (error) => resolve({exitCode: undefined, stdout: "", stderr: error.message}));
+    child.on(NODE_EVENT.CLOSE, (exitCode) =>
+      resolve({exitCode, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8")}),
+    );
+  });
+}
+
+function runNpm(args, cwd, environment) {
+  if (npmCli) return run(process.execPath, [npmCli, ...args], {cwd, env: environment});
+  return run("npm", args, {cwd, env: environment});
+}
+
+function check(name, status, reason, details) {
+  return {name, status, reason, ...(details ? {details} : {})};
+}
+
+function resultMessage(result) {
+  return result.stderr.trim() || result.stdout.trim();
+}
+
+function registryFailure(result) {
+  const message = `${result.stdout}\n${result.stderr}`;
+  if (message.includes("E404")) {
+    return check(RELEASE_CHECK.REGISTRY, CI_STATUS.FAIL, RELEASE_REASON.VERSION_NOT_PUBLISHED, {
+      packageVersion: requestedVersion,
+    });
+  }
+  return check(RELEASE_CHECK.REGISTRY, CI_STATUS.BLOCKED, RELEASE_REASON.REGISTRY_UNAVAILABLE, {
+    packageVersion: requestedVersion,
+    message: resultMessage(result),
+  });
+}
+
+async function verifyRegistry(context) {
+  const registry = await runNpm(
+    [NPM_COMMAND.VIEW, context.packageVersion, NPM_COMMAND.VERSION, NPM_ARGUMENT.JSON],
+    context.consumer,
+    context.environment,
+  );
+  if (registry.exitCode !== CI_EXIT_CODE.PASS) return registryFailure(registry);
+  let publishedVersion;
+  try {
+    publishedVersion = JSON.parse(registry.stdout);
+  } catch {
+    return check(RELEASE_CHECK.REGISTRY, CI_STATUS.FAIL, RELEASE_REASON.REGISTRY_RESPONSE_INVALID, {
+      packageVersion: requestedVersion,
+      message: resultMessage(registry),
+    });
+  }
+  const matches = publishedVersion === requestedVersion;
+  return check(
+    RELEASE_CHECK.REGISTRY,
+    matches ? CI_STATUS.PASS : CI_STATUS.FAIL,
+    matches ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.VERSION_NOT_PUBLISHED,
+    {packageVersion: requestedVersion},
+  );
+}
+
+async function verifyInstallation(context) {
+  const installed = await runNpm(
+    [
+      NPM_COMMAND.INSTALL,
+      NPM_ARGUMENT.IGNORE_SCRIPTS,
+      NPM_ARGUMENT.NO_AUDIT,
+      NPM_ARGUMENT.NO_FUND,
+      NPM_ARGUMENT.SAVE_EXACT,
+      context.packageVersion,
+    ],
+    context.consumer,
+    context.environment,
+  );
+  const passed = installed.exitCode === CI_EXIT_CODE.PASS;
+  return check(
+    RELEASE_CHECK.INSTALLATION,
+    passed ? CI_STATUS.PASS : CI_STATUS.FAIL,
+    passed ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.INSTALLATION_FAILED,
+    passed ? undefined : {message: resultMessage(installed)},
+  );
+}
+
+async function verifyInstalledVersion(context) {
+  const installedRoot = await realpath(path.join(context.consumer, POSTPUBLICATION_PATH.DEPENDENCY_DIRECTORY, PRODUCT.NAME));
+  const installedManifest = JSON.parse(await readFile(path.join(installedRoot, CONFIGURATION_FILE.PACKAGE), "utf8"));
+  const binary = path.join(
+    context.consumer,
+    POSTPUBLICATION_PATH.DEPENDENCY_DIRECTORY,
+    POSTPUBLICATION_PATH.BINARY_DIRECTORY,
+    npmExecutableName(PRODUCT.NAME),
+  );
+  const version = await run(binary, [CLI_ARGUMENT.VERSION], {cwd: context.consumer, env: context.environment});
+  const passed =
+    version.exitCode === CI_EXIT_CODE.PASS && version.stdout.trim() === requestedVersion && installedManifest.version === requestedVersion;
+  return {
+    binary,
+    result: check(
+      RELEASE_CHECK.INSTALLED_VERSION,
+      passed ? CI_STATUS.PASS : CI_STATUS.FAIL,
+      passed ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.INSTALLED_VERSION_DIFFERENT,
+      {packageVersion: requestedVersion},
+    ),
+  };
+}
+
+async function verifyInstalledDoctor(context, binary) {
+  const doctor = await run(binary, [CLI_COMMAND.DOCTOR], {cwd: context.consumer, env: context.environment});
+  let doctorResult;
+  try {
+    doctorResult = JSON.parse(doctor.stdout);
+  } catch {
+    doctorResult = undefined;
+  }
+  const requiredDoctorChecks = new Set([
+    DOCTOR_CHECK.MCP_STARTUP,
+    DOCTOR_CHECK.TOOL_DISCOVERY,
+    DOCTOR_CHECK.TYPESCRIPT_SYMBOLS,
+    DOCTOR_CHECK.TYPESCRIPT_REFERENCES,
+    DOCTOR_CHECK.VUE_SYMBOLS,
+    DOCTOR_CHECK.VUE_TEMPLATE_DEFINITION,
+  ]);
+  const completedDoctorChecks = new Set(
+    (doctorResult?.checks || []).filter((item) => item.status === CI_STATUS.PASS).map((item) => item.name),
+  );
+  const passed =
+    DOCTOR_DISTRIBUTION_ACCEPTED_STATUS.includes(doctorResult?.status) &&
+    [...requiredDoctorChecks].every((name) => completedDoctorChecks.has(name));
+  return check(
+    RELEASE_CHECK.INSTALLED_DOCTOR,
+    passed ? CI_STATUS.PASS : CI_STATUS.FAIL,
+    passed ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.DOCTOR_REJECTED_INSTALLATION,
+    passed
+      ? {doctorStatus: doctorResult.status, semanticChecks: requiredDoctorChecks.size}
+      : {doctorStatus: doctorResult?.status, message: resultMessage(doctor)},
+  );
+}
+
+async function runVerification() {
+  if (!requestedVersion) {
+    checks.push(check(RELEASE_CHECK.REGISTRY, CI_STATUS.BLOCKED, RELEASE_REASON.VERSION_REQUIRED));
+    return;
+  }
+
+  workspace = await mkdtemp(path.join(tmpdir(), `${PRODUCT.NAME}-postpublication-`));
+  const npmCache = path.join(workspace, POSTPUBLICATION_PATH.NPM_CACHE);
+  const consumer = path.join(workspace, POSTPUBLICATION_PATH.CONSUMER);
+  await mkdir(npmCache, {recursive: true});
+  await mkdir(consumer, {recursive: true});
+  await writeFile(path.join(consumer, CONFIGURATION_FILE.PACKAGE), JSON.stringify({private: true}));
+  const context = {
+    consumer,
+    environment: {...process.env, [NPM_DISTRIBUTION.CACHE_ENVIRONMENT_VARIABLE]: npmCache},
+    packageVersion: `${PRODUCT.NAME}@${requestedVersion}`,
+  };
+
+  const registry = await verifyRegistry(context);
+  checks.push(registry);
+  if (registry.status !== CI_STATUS.PASS) return;
+
+  const installation = await verifyInstallation(context);
+  checks.push(installation);
+  if (installation.status !== CI_STATUS.PASS) return;
+
+  const installedVersion = await verifyInstalledVersion(context);
+  checks.push(installedVersion.result);
+  if (installedVersion.result.status !== CI_STATUS.PASS) return;
+
+  checks.push(await verifyInstalledDoctor(context, installedVersion.binary));
+  checks.push(...(await verifyCodexPlugin({version: requestedVersion, workspace, spawn})));
+}
+
+try {
+  await runVerification();
+} catch (error) {
+  checks.push(
+    check(RELEASE_CHECK.POSTPUBLICATION_ENVIRONMENT, CI_STATUS.BLOCKED, RELEASE_REASON.VERIFICATION_ENVIRONMENT_UNAVAILABLE, {
+      message: error instanceof Error ? error.message : String(error),
+    }),
+  );
+} finally {
+  if (workspace) await rm(workspace, {recursive: true, force: true});
+}
+
+const status = releaseStatus(checks);
+const output = {
+  product: {name: PRODUCT.NAME, version: requestedVersion},
+  mode: RELEASE_MODE.PUBLISHED,
+  status,
+  exitCode: CI_EXIT_CODE[status.toUpperCase()],
+  checks,
+};
+
+process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+process.exitCode = output.exitCode;

package/scripts/release-contract.mjs

@@ -0,0 +1,70 @@
+import {CI_STATUS} from "../protocol.mjs";
+
+export const RELEASE_MODE = Object.freeze({
+  LOCAL: "local",
+  PUBLISHED: "published",
+});
+
+export const RELEASE_CHECK = Object.freeze({
+  STATIC: "static",
+  RUNTIME: "runtime",
+  CI_POLICY: "ci-policy",
+  TYPESCRIPT_SMOKE: "typescript-smoke",
+  VUE_SMOKE: "vue-smoke",
+  RELEASE_CONTRACT_SMOKE: "release-contract-smoke",
+  AGENT_EVALUATION_SMOKE: "agent-evaluation-smoke",
+  REPOSITORY_MATRIX_SMOKE: "repository-matrix-smoke",
+  DISTRIBUTION_SMOKE: "distribution-smoke",
+  BENCHMARK: "benchmark",
+  REGISTRY: "registry",
+  INSTALLATION: "installation",
+  INSTALLED_VERSION: "installed-version",
+  INSTALLED_DOCTOR: "installed-doctor",
+  CODEX_MARKETPLACE: "codex-marketplace",
+  CODEX_PLUGIN_INSTALLATION: "codex-plugin-installation",
+  POSTPUBLICATION_ENVIRONMENT: "postpublication-environment",
+});
+
+export const RELEASE_REASON = Object.freeze({
+  CHECK_COMPLETED: "check-completed",
+  CHECK_FAILED: "check-failed",
+  VERSION_REQUIRED: "version-required",
+  REGISTRY_UNAVAILABLE: "registry-unavailable",
+  VERSION_NOT_PUBLISHED: "version-not-published",
+  INSTALLATION_FAILED: "installation-failed",
+  INSTALLED_VERSION_DIFFERENT: "installed-version-different",
+  DOCTOR_REJECTED_INSTALLATION: "doctor-rejected-installation",
+  CODEX_CLI_UNAVAILABLE: "codex-cli-unavailable",
+  CODEX_MARKETPLACE_UNAVAILABLE: "codex-marketplace-unavailable",
+  CODEX_MARKETPLACE_FAILED: "codex-marketplace-installation-failed",
+  CODEX_PLUGIN_SOURCE_UNAVAILABLE: "codex-plugin-source-unavailable",
+  CODEX_PLUGIN_INSTALLATION_FAILED: "codex-plugin-installation-failed",
+  CODEX_PLUGIN_VERSION_DIFFERENT: "codex-plugin-version-different",
+  REGISTRY_RESPONSE_INVALID: "registry-response-invalid",
+  VERIFICATION_ENVIRONMENT_UNAVAILABLE: "verification-environment-unavailable",
+});
+
+export const RELEASE_ARGUMENT = Object.freeze({
+  PACKAGE_VERSION_OFFSET: 2,
+});
+
+export const RELEASE_LOCAL_CHECKS = Object.freeze([
+  Object.freeze({name: RELEASE_CHECK.STATIC, npmScript: "check"}),
+  Object.freeze({name: RELEASE_CHECK.RUNTIME, npmScript: "check:runtime"}),
+  Object.freeze({name: RELEASE_CHECK.CI_POLICY, npmScript: "smoke:ci"}),
+  Object.freeze({name: RELEASE_CHECK.TYPESCRIPT_SMOKE, npmScript: "smoke"}),
+  Object.freeze({name: RELEASE_CHECK.VUE_SMOKE, npmScript: "smoke:vue"}),
+  Object.freeze({name: RELEASE_CHECK.RELEASE_CONTRACT_SMOKE, npmScript: "smoke:release"}),
+  Object.freeze({name: RELEASE_CHECK.AGENT_EVALUATION_SMOKE, npmScript: "smoke:evaluation"}),
+  Object.freeze({name: RELEASE_CHECK.REPOSITORY_MATRIX_SMOKE, npmScript: "smoke:matrix"}),
+  Object.freeze({name: RELEASE_CHECK.DISTRIBUTION_SMOKE, npmScript: "smoke:distribution"}),
+  Object.freeze({name: RELEASE_CHECK.BENCHMARK, npmScript: "benchmark"}),
+]);
+
+export function releaseStatus(checks) {
+  if (checks.length === 0) return CI_STATUS.BLOCKED;
+  if (checks.some((check) => check.status === CI_STATUS.BLOCKED)) return CI_STATUS.BLOCKED;
+  if (checks.some((check) => check.status === CI_STATUS.FAIL)) return CI_STATUS.FAIL;
+  if (checks.some((check) => check.status === CI_STATUS.UNTRUSTED)) return CI_STATUS.UNTRUSTED;
+  return CI_STATUS.PASS;
+}

package/scripts/release-smoke.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import {spawn} from "node:child_process";
+import {mkdtemp, rm} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {fileURLToPath} from "node:url";
+import path from "node:path";
+import {CI_EXIT_CODE, CI_STATUS, NODE_EVENT, PRODUCT} from "../protocol.mjs";
+import {verifyCodexPlugin} from "./codex-plugin-verification.mjs";
+import {CODEX_DISTRIBUTION} from "./distribution-policy.mjs";
+import {RELEASE_MODE, RELEASE_REASON, releaseStatus} from "./release-contract.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+function run(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {stdio: ["ignore", "pipe", "pipe"], ...options});
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on(NODE_EVENT.ERROR, (error) => resolve({exitCode: undefined, stdout: "", stderr: error.message}));
+    child.on(NODE_EVENT.CLOSE, (exitCode) =>
+      resolve({exitCode, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8")}),
+    );
+  });
+}
+
+assert(releaseStatus([]) === CI_STATUS.BLOCKED, "Empty release check set was not blocked");
+assert(releaseStatus([{status: CI_STATUS.UNTRUSTED}]) === CI_STATUS.UNTRUSTED, "Untrusted release state was not preserved");
+assert(
+  releaseStatus([{status: CI_STATUS.UNTRUSTED}, {status: CI_STATUS.FAIL}]) === CI_STATUS.FAIL,
+  "Release failure did not outrank untrusted evidence",
+);
+assert(
+  releaseStatus([{status: CI_STATUS.FAIL}, {status: CI_STATUS.BLOCKED}]) === CI_STATUS.BLOCKED,
+  "Release blocker did not outrank a failed check",
+);
+
+const scriptRoot = path.dirname(fileURLToPath(import.meta.url));
+const postpublication = await run(process.execPath, [path.join(scriptRoot, "postpublication-smoke.mjs")]);
+assert(postpublication.exitCode === CI_EXIT_CODE.BLOCKED, "Postpublication verification without a version used the wrong exit code");
+const postpublicationResult = JSON.parse(postpublication.stdout);
+assert(postpublicationResult.mode === RELEASE_MODE.PUBLISHED, "Postpublication result omitted its mode");
+assert(postpublicationResult.status === CI_STATUS.BLOCKED, "Missing version was not blocked");
+assert(postpublicationResult.checks[0]?.reason === RELEASE_REASON.VERSION_REQUIRED, "Missing version omitted its literal reason");
+
+const codexWorkspace = await mkdtemp(path.join(tmpdir(), "semantic-js-mcp-codex-release-smoke-"));
+try {
+  const version = "1.2.3";
+  const calls = [];
+  const runCommand = async (command, args, options) => {
+    calls.push({command, args, options});
+    if (args.includes(CODEX_DISTRIBUTION.LIST_COMMAND)) {
+      return {
+        exitCode: CI_EXIT_CODE.PASS,
+        stdout: JSON.stringify({
+          installed: [
+            {
+              name: PRODUCT.NAME,
+              marketplaceName: CODEX_DISTRIBUTION.MARKETPLACE_NAME,
+              version,
+              enabled: true,
+            },
+          ],
+        }),
+        stderr: "",
+      };
+    }
+    return {exitCode: CI_EXIT_CODE.PASS, stdout: "{}", stderr: ""};
+  };
+  const codexChecks = await verifyCodexPlugin({version, workspace: codexWorkspace, runCommand});
+  assert(codexChecks.length === 2, "Codex verification omitted a dependent check");
+  assert(
+    codexChecks.every((item) => item.status === CI_STATUS.PASS),
+    "Codex verification rejected valid installation evidence",
+  );
+  assert(
+    calls[0].args.includes(`${CODEX_DISTRIBUTION.VERSION_REF_PREFIX}${version}`),
+    "Codex marketplace verification did not use an immutable version ref",
+  );
+  assert(calls[1].args.includes(CODEX_DISTRIBUTION.PLUGIN_SELECTOR), "Codex verification used the wrong plugin selector");
+  assert(
+    calls.every((call) => call.options.env[CODEX_DISTRIBUTION.HOME_ENVIRONMENT_VARIABLE].startsWith(codexWorkspace)),
+    "Codex verification did not isolate its state under the temporary workspace",
+  );
+
+  const unavailableChecks = await verifyCodexPlugin({
+    version,
+    workspace: codexWorkspace,
+    runCommand: async () => ({exitCode: undefined, stdout: "", stderr: "missing codex"}),
+  });
+  assert(unavailableChecks[0].status === CI_STATUS.BLOCKED, "Missing Codex CLI was not blocked");
+  assert(unavailableChecks[0].reason === RELEASE_REASON.CODEX_CLI_UNAVAILABLE, "Missing Codex CLI used the wrong reason");
+
+  const networkChecks = await verifyCodexPlugin({
+    version,
+    workspace: codexWorkspace,
+    runCommand: async () => ({exitCode: CI_EXIT_CODE.FAIL, stdout: "", stderr: "Could not resolve host"}),
+  });
+  assert(networkChecks[0].status === CI_STATUS.BLOCKED, "Unavailable Codex marketplace network was not blocked");
+  assert(
+    networkChecks[0].reason === RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE,
+    "Unavailable Codex marketplace network used the wrong reason",
+  );
+} finally {
+  await rm(codexWorkspace, {recursive: true, force: true});
+}
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      releaseStatusPriority: "ok",
+      missingPublishedVersion: "blocked",
+      isolatedCodexPluginInstallation: "ok",
+      unavailableCodexMarketplace: "blocked",
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/release-verify.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import {spawn} from "node:child_process";
+import {performance} from "node:perf_hooks";
+import {CI_EXIT_CODE, CI_STATUS, NODE_EVENT, PRODUCT, SERVER_VERSION} from "../protocol.mjs";
+import {RELEASE_LOCAL_CHECKS, RELEASE_MODE, RELEASE_REASON, releaseStatus} from "./release-contract.mjs";
+
+const npmCli = process.env.npm_execpath;
+
+function runNpmScript(npmScript) {
+  const command = npmCli ? process.execPath : "npm";
+  const args = npmCli ? [npmCli, "run", npmScript] : ["run", npmScript];
+  return new Promise((resolve) => {
+    const startedAt = performance.now();
+    const child = spawn(command, args, {cwd: process.cwd(), env: process.env, stdio: ["ignore", "pipe", "pipe"]});
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on(NODE_EVENT.ERROR, (error) =>
+      resolve({
+        exitCode: undefined,
+        message: error.message,
+        durationMilliseconds: Math.round(performance.now() - startedAt),
+      }),
+    );
+    child.on(NODE_EVENT.CLOSE, (exitCode) =>
+      resolve({
+        exitCode,
+        stdout: Buffer.concat(stdout).toString("utf8"),
+        stderr: Buffer.concat(stderr).toString("utf8"),
+        durationMilliseconds: Math.round(performance.now() - startedAt),
+      }),
+    );
+  });
+}
+
+const checks = [];
+for (const configuredCheck of RELEASE_LOCAL_CHECKS) {
+  process.stderr.write(`[${PRODUCT.NAME}:release] ${configuredCheck.name}\n`);
+  const result = await runNpmScript(configuredCheck.npmScript);
+  const passed = result.exitCode === CI_EXIT_CODE.PASS;
+  checks.push({
+    name: configuredCheck.name,
+    npmScript: configuredCheck.npmScript,
+    status: passed ? CI_STATUS.PASS : CI_STATUS.FAIL,
+    reason: passed ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.CHECK_FAILED,
+    exitCode: result.exitCode,
+    durationMilliseconds: result.durationMilliseconds,
+    ...(passed ? {} : {message: result.message || result.stderr.trim() || result.stdout.trim()}),
+  });
+}
+
+const status = releaseStatus(checks);
+const output = {
+  product: {name: PRODUCT.NAME, version: SERVER_VERSION},
+  mode: RELEASE_MODE.LOCAL,
+  status,
+  exitCode: CI_EXIT_CODE[status.toUpperCase()],
+  checks,
+};
+
+process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+process.exitCode = output.exitCode;

package/scripts/repository-matrix-contract.mjs

@@ -0,0 +1,80 @@
+import {CI_EXIT_CODE, CI_STATUS, COLLECTION_STATUS, DEFINITION_SELECTION_STATUS, EVIDENCE_STATUS} from "../protocol.mjs";
+
+export const REPOSITORY_MATRIX_ARGUMENT = Object.freeze({
+  CONFIGURATION_OFFSET: 2,
+});
+
+export const REPOSITORY_MATRIX_MODE = "repository-matrix";
+
+export const REPOSITORY_MATRIX_PROBE_KIND = Object.freeze({
+  NAMED_SYMBOL: "named-symbol",
+  DIAGNOSTICS: "diagnostics",
+});
+
+export const REPOSITORY_MATRIX_REASON = Object.freeze({
+  CHECK_COMPLETED: "check-completed",
+  CONFIGURATION_REQUIRED: "configuration-required",
+  CONFIGURATION_INVALID: "configuration-invalid",
+  REPOSITORY_UNAVAILABLE: "repository-unavailable",
+  MCP_STARTUP_FAILED: "mcp-startup-failed",
+  TOOL_EXECUTION_FAILED: "tool-execution-failed",
+  COLLECTION_INCOMPLETE: "collection-is-limited-or-partial",
+  DEFINITION_SELECTION_AMBIGUOUS: "definition-selection-is-not-exactly-one",
+  DIAGNOSTICS_UNTRUSTED: "diagnostics-for-current-document-are-untrusted",
+});
+
+const STATUS_PRIORITY = Object.freeze({
+  [CI_STATUS.PASS]: 0,
+  [CI_STATUS.UNTRUSTED]: 1,
+  [CI_STATUS.FAIL]: 2,
+  [CI_STATUS.BLOCKED]: 3,
+});
+
+export function repositoryMatrixStatus(items) {
+  if (items.length === 0) return CI_STATUS.BLOCKED;
+  return items.reduce((current, item) => (STATUS_PRIORITY[item.status] > STATUS_PRIORITY[current] ? item.status : current), CI_STATUS.PASS);
+}
+
+export function repositoryMatrixExitCode(status) {
+  return CI_EXIT_CODE[status.toUpperCase()];
+}
+
+export function collectionEvaluation(collectionStatus) {
+  if (collectionStatus === COLLECTION_STATUS.COMPLETE) {
+    return {status: CI_STATUS.PASS, reason: REPOSITORY_MATRIX_REASON.CHECK_COMPLETED};
+  }
+  if (collectionStatus === COLLECTION_STATUS.LIMITED || collectionStatus === COLLECTION_STATUS.PARTIAL) {
+    return {status: CI_STATUS.UNTRUSTED, reason: REPOSITORY_MATRIX_REASON.COLLECTION_INCOMPLETE};
+  }
+  return {status: CI_STATUS.FAIL, reason: REPOSITORY_MATRIX_REASON.TOOL_EXECUTION_FAILED};
+}
+
+export function namedSymbolEvaluation(countResult, auditResult) {
+  const collection = repositoryMatrixStatus([
+    collectionEvaluation(countResult.collection.status),
+    collectionEvaluation(auditResult.collection.status),
+  ]);
+  if (collection !== CI_STATUS.PASS) {
+    return {
+      status: collection,
+      reason:
+        collection === CI_STATUS.UNTRUSTED
+          ? REPOSITORY_MATRIX_REASON.COLLECTION_INCOMPLETE
+          : REPOSITORY_MATRIX_REASON.TOOL_EXECUTION_FAILED,
+    };
+  }
+  const exactSelection =
+    countResult.result.definitionSelectionStatus === DEFINITION_SELECTION_STATUS.ONE &&
+    auditResult.result.definitionSelectionStatus === DEFINITION_SELECTION_STATUS.ONE;
+  return exactSelection
+    ? {status: CI_STATUS.PASS, reason: REPOSITORY_MATRIX_REASON.CHECK_COMPLETED}
+    : {status: CI_STATUS.UNTRUSTED, reason: REPOSITORY_MATRIX_REASON.DEFINITION_SELECTION_AMBIGUOUS};
+}
+
+export function diagnosticEvaluation(result) {
+  const collection = collectionEvaluation(result.collection.status);
+  if (result.result.evidence?.status !== EVIDENCE_STATUS.VERIFIED) {
+    return {status: CI_STATUS.UNTRUSTED, reason: REPOSITORY_MATRIX_REASON.DIAGNOSTICS_UNTRUSTED};
+  }
+  return collection;
+}