@vizejs/plugin-sdk 0.515.0 → 0.516.0

package/README.md

@@ -1,10 +1,59 @@
 # @vizejs/plugin-sdk
 
 Author synchronous rules, fact providers, native template transforms and compiled
-output hooks. Install `@vizejs/native` **0.515.0 or newer** to execute plugins.
+output hooks. Install `@vizejs/native` **0.516.0 or newer** to execute plugins.
 The optional native peer lets this package install independently for authoring;
 its helpers alone do not compile or lint Vue files. Node 22 or newer is required.
 
+## Typed visitor capability descriptors
+
+`@vizejs/plugin-sdk/visitor` defines the stable versioned descriptor boundary for
+visitor-style plugins. The v1 capability vocabulary covers SFC, template,
+script, style, virtual TypeScript, diagnostics, lint, format and devtools trace
+events. Each declared capability requires a matching synchronous callback, and
+TypeScript narrows the callback payload to that capability.
+
+```ts
+import {
+  VISITOR_API_VERSION,
+  defineVisitorPlugin,
+  negotiateVisitorPlugin,
+} from "@vizejs/plugin-sdk/visitor";
+
+const observer = defineVisitorPlugin({
+  apiVersion: VISITOR_API_VERSION,
+  name: "virtual-ts-observer",
+  version: "1.0.0",
+  capabilities: ["virtual-ts", "diagnostics"] as const,
+  cacheInputs: [],
+  visitors: {
+    "virtual-ts"(event) {
+      console.log(event.payload.virtualFile, event.payload.mappings.length);
+    },
+    diagnostics(event) {
+      console.log(event.payload.diagnostics.length);
+    },
+  },
+});
+
+negotiateVisitorPlugin(observer, {
+  apiVersion: VISITOR_API_VERSION,
+  capabilities: ["virtual-ts", "diagnostics"],
+});
+```
+
+Definitions fail closed on unknown or duplicate capabilities, missing or
+undeclared callbacks, asynchronous functions, reserved cache-input names and API
+version mismatches. `runVisitorFixture` freezes one authored event and enforces
+the synchronous return contract for package tests.
+
+This module only creates immutable descriptors and author fixtures. It does not
+register callbacks in the native compiler, linter or language server, so importing
+it adds no work to those paths. A production host must explicitly negotiate the
+descriptor and owns cancellation, deadlines, isolation and event construction.
+Virtual TypeScript and devtools trace observers use separate opt-in host
+entrypoints; importing this module never registers either callback globally.
+
 ## Lint rules and autofixes
 
 ```js
@@ -222,3 +271,80 @@ synchronously in the calling Node process and have no execution deadline.
 Freezing batches and auditing output do not isolate those callbacks. The measured
 proxy handle remains for spike compatibility. `@vizejs/extension-sdk` is the
 separate versioned WIT guest interface.
+
+## Virtual TypeScript visitors
+
+`defineVisitorPlugin` descriptors with only the `virtual-ts` capability can be
+negotiated for the native type-check host. The ordinary `typeCheck` entrypoint
+remains plugin-free; callers opt in through the separate visitor entrypoint.
+
+```js
+import { typeCheckWithVirtualTsVisitors } from "@vizejs/native";
+import {
+  VISITOR_API_VERSION,
+  createVirtualTsVisitorHost,
+  defineVisitorPlugin,
+} from "@vizejs/plugin-sdk/visitor";
+
+const observer = defineVisitorPlugin({
+  apiVersion: VISITOR_API_VERSION,
+  name: "virtual-ts-observer",
+  version: "1",
+  capabilities: ["virtual-ts"],
+  cacheInputs: [],
+  visitors: {
+    "virtual-ts"({ payload }) {
+      console.log(payload.virtualFile, payload.code, payload.mappings);
+    },
+  },
+});
+
+typeCheckWithVirtualTsVisitors(source, [createVirtualTsVisitorHost(observer)], {
+  filename: "src/App.vue",
+});
+```
+
+The callback receives immutable generated code and source/generated UTF-8 byte
+ranges after the real type-check projection is built. Returning a value,
+requesting another capability, or forging an incomplete host identity refuses
+the invocation.
+
+## Devtools trace visitors
+
+`devtools-trace` descriptors attach explicitly to a request-local
+`@vizejs/devtools` recorder. The recorder serializes each committed trace event
+through the negotiated adapter; disabled recorders do not invoke configured
+hosts, and ordinary recorders without `visitorHosts` do not inspect plugin
+descriptors.
+
+```js
+import { createDevtoolsTraceRecorder } from "@vizejs/devtools";
+import {
+  VISITOR_API_VERSION,
+  createDevtoolsTraceVisitorHost,
+  defineVisitorPlugin,
+} from "@vizejs/plugin-sdk/visitor";
+
+const observer = defineVisitorPlugin({
+  apiVersion: VISITOR_API_VERSION,
+  name: "trace-observer",
+  version: "1",
+  capabilities: ["devtools-trace"],
+  cacheInputs: [],
+  visitors: {
+    "devtools-trace"({ file, payload }) {
+      console.log(file, payload.events);
+    },
+  },
+});
+
+const trace = createDevtoolsTraceRecorder({
+  sessionId: "request-1",
+  visitorHosts: [createDevtoolsTraceVisitorHost(observer)],
+});
+```
+
+Every delivered event has a deterministic session/sequence ID, a stage derived
+from its trace kind, millisecond timestamps normalized to nanoseconds, and the
+remaining recorder fields in immutable `data`. A visitor exception or non-void
+result refuses the record before it enters the snapshot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vizejs/plugin-sdk",
-  "version": "0.515.0",
+  "version": "0.516.0",
   "description": "Deterministic authoring and isolated execution for Vize JavaScript plugins",
   "homepage": "https://github.com/ubugeeei-prod/vize",
   "bugs": {
@@ -24,7 +24,9 @@
     "README.md",
     "sandbox.js",
     "sandbox-worker.js",
-    "sandbox.d.ts"
+    "sandbox.d.ts",
+    "visitor.js",
+    "visitor.d.ts"
   ],
   "type": "module",
   "sideEffects": false,
@@ -41,13 +43,17 @@
     "./sandbox": {
       "types": "./sandbox.d.ts",
       "default": "./sandbox.js"
+    },
+    "./visitor": {
+      "types": "./visitor.d.ts",
+      "default": "./visitor.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@vizejs/native": "0.515.0"
+    "@vizejs/native": "0.516.0"
   },
   "peerDependencies": {
     "@vizejs/native": ">=0.429.0"

package/visitor.d.ts

@@ -0,0 +1,213 @@
+import type { PluginNode } from "./index.js";
+import type { JsonValue } from "./stages.js";
+
+export declare const VISITOR_API_VERSION: 1;
+export declare const VISITOR_CAPABILITIES: readonly [
+  "sfc",
+  "template",
+  "script",
+  "style",
+  "virtual-ts",
+  "diagnostics",
+  "lint",
+  "format",
+  "devtools-trace",
+];
+export type VisitorCapability = (typeof VISITOR_CAPABILITIES)[number];
+export type VisitorErrorCode =
+  | "invalid-definition"
+  | "invalid-name"
+  | "invalid-version"
+  | "unsupported-api-version"
+  | "invalid-capabilities"
+  | "unknown-capability"
+  | "duplicate-capability"
+  | "invalid-visitors"
+  | "missing-visitor"
+  | "undeclared-visitor"
+  | "async-visitor"
+  | "invalid-cache-inputs"
+  | "invalid-plugin"
+  | "invalid-host-contract"
+  | "unsupported-capability"
+  | "undeclared-capability"
+  | "invalid-event"
+  | "invalid-visitor-result";
+
+export declare class VisitorPluginValidationError extends TypeError {
+  readonly code: VisitorErrorCode;
+  readonly field: string;
+}
+
+export interface VisitorRange {
+  readonly start: number;
+  readonly end: number;
+  readonly encoding: "utf8";
+}
+export interface VisitorDiagnostic {
+  readonly code: string;
+  readonly message: string;
+  readonly severity: "error" | "warning" | "information" | "hint";
+  readonly range: VisitorRange;
+  readonly source?: string;
+}
+export interface VisitorFix {
+  readonly range: VisitorRange;
+  readonly text: string;
+}
+export interface VisitorSfcBlock {
+  readonly kind: "template" | "script" | "script-setup" | "style" | "custom";
+  readonly language: string | null;
+  readonly range: VisitorRange;
+  readonly attributes: Readonly<Record<string, string | null>>;
+}
+export interface VisitorSfcPayload {
+  readonly source: string;
+  readonly blocks: readonly VisitorSfcBlock[];
+}
+export interface VisitorTemplatePayload {
+  readonly nodes: readonly PluginNode[];
+}
+export interface VisitorScriptPayload {
+  readonly source: string;
+  readonly language: "js" | "jsx" | "ts" | "tsx";
+  /** Host-owned serialized syntax data. Its schema belongs to the negotiated host. */
+  readonly syntax?: JsonValue;
+}
+export interface VisitorStylePayload {
+  readonly source: string;
+  readonly language: string;
+  readonly scoped: boolean;
+  readonly module: boolean | string;
+}
+export interface VisitorVirtualTsMapping {
+  readonly source: VisitorRange;
+  readonly generated: VisitorRange;
+}
+export interface VisitorVirtualTsPayload {
+  readonly sourceFile: string;
+  readonly virtualFile: string;
+  readonly code: string;
+  readonly mappings: readonly VisitorVirtualTsMapping[];
+}
+export interface VisitorDiagnosticsPayload {
+  readonly diagnostics: readonly VisitorDiagnostic[];
+}
+export interface VisitorLintPayload extends VisitorDiagnosticsPayload {
+  readonly fixes: readonly VisitorFix[];
+}
+export interface VisitorFormatPayload {
+  readonly source: string;
+  readonly formatted: string;
+}
+export interface VisitorDevtoolsTraceEvent {
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly name: string;
+  readonly stage: string;
+  readonly startNs: number;
+  readonly durationNs: number;
+  readonly data?: JsonValue;
+}
+export interface VisitorDevtoolsTracePayload {
+  readonly events: readonly VisitorDevtoolsTraceEvent[];
+}
+export interface VisitorPayloads {
+  readonly sfc: VisitorSfcPayload;
+  readonly template: VisitorTemplatePayload;
+  readonly script: VisitorScriptPayload;
+  readonly style: VisitorStylePayload;
+  readonly "virtual-ts": VisitorVirtualTsPayload;
+  readonly diagnostics: VisitorDiagnosticsPayload;
+  readonly lint: VisitorLintPayload;
+  readonly format: VisitorFormatPayload;
+  readonly "devtools-trace": VisitorDevtoolsTracePayload;
+}
+export interface VisitorEvent<C extends VisitorCapability = VisitorCapability> {
+  readonly apiVersion: 1;
+  readonly capability: C;
+  readonly file: string;
+  readonly payload: VisitorPayloads[C];
+}
+export type VisitorHandler<C extends VisitorCapability> = (event: VisitorEvent<C>) => void;
+export type VisitorHandlers<C extends readonly VisitorCapability[]> = {
+  readonly [K in C[number]]: VisitorHandler<K>;
+};
+export interface VisitorCacheInput {
+  readonly name: string;
+  readonly value: string;
+}
+export interface VisitorPluginDefinition<C extends readonly VisitorCapability[]> {
+  readonly apiVersion: 1;
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities: C;
+  /** Explicit list of every captured configuration or ambient input. */
+  readonly cacheInputs: readonly VisitorCacheInput[];
+  readonly visitors: VisitorHandlers<C>;
+}
+export interface VisitorPlugin<
+  C extends readonly VisitorCapability[] = readonly VisitorCapability[],
+> {
+  readonly kind: "vize.visitor-plugin";
+  readonly apiVersion: 1;
+  readonly name: string;
+  readonly version: string;
+  readonly capabilities: C;
+  readonly cacheInputs: readonly VisitorCacheInput[];
+  readonly visitors: VisitorHandlers<C>;
+  readonly fingerprint: string;
+}
+export interface VisitorHostContract<
+  C extends readonly VisitorCapability[] = readonly VisitorCapability[],
+> {
+  readonly apiVersion: 1;
+  readonly capabilities: C;
+}
+export interface NegotiatedVisitorContract<C extends readonly VisitorCapability[]> {
+  readonly apiVersion: 1;
+  readonly capabilities: C;
+}
+export interface VirtualTsVisitorHostPlugin {
+  readonly name: string;
+  readonly version: string;
+  readonly fingerprint: string;
+  /** Host-only serialized boundary consumed by `typeCheckWithVirtualTsVisitors`. */
+  readonly run: (eventJson: string) => string;
+}
+export interface DevtoolsTraceVisitorHostPlugin {
+  readonly name: string;
+  readonly version: string;
+  readonly fingerprint: string;
+  /** Host-only serialized boundary consumed by `createDevtoolsTraceRecorder`. */
+  readonly run: (deliveryJson: string) => string;
+}
+
+/** Define an immutable descriptor. This does not register a runtime hook. */
+export declare function defineVisitorPlugin<const C extends readonly VisitorCapability[]>(
+  definition: VisitorPluginDefinition<C>,
+): VisitorPlugin<C>;
+/** Fail closed unless the host provides the exact API version and every declared capability. */
+export declare function negotiateVisitorPlugin<const C extends readonly VisitorCapability[]>(
+  plugin: VisitorPlugin<C>,
+  host: VisitorHostContract,
+): NegotiatedVisitorContract<C>;
+/** Invoke one visitor in an author fixture; production lifecycle remains host-owned. */
+export declare function runVisitorFixture<
+  C extends readonly VisitorCapability[],
+  K extends C[number],
+>(plugin: VisitorPlugin<C>, capability: K, event: VisitorEvent<K>): void;
+/**
+ * Negotiate a virtual-TypeScript-only descriptor and adapt it to the native
+ * type-check visitor boundary. Descriptors with any unsupported capability fail closed.
+ */
+export declare function createVirtualTsVisitorHost(
+  plugin: VisitorPlugin<readonly ["virtual-ts"]>,
+): VirtualTsVisitorHostPlugin;
+/**
+ * Negotiate a devtools-trace-only descriptor and adapt it to the opt-in
+ * `@vizejs/devtools` recorder boundary. Mixed-capability descriptors fail closed.
+ */
+export declare function createDevtoolsTraceVisitorHost(
+  plugin: VisitorPlugin<readonly ["devtools-trace"]>,
+): DevtoolsTraceVisitorHostPlugin;

package/visitor.js

@@ -0,0 +1,370 @@
+// Capability-only visitor authoring contracts. Native pipeline registration is
+// deliberately separate so importing this module cannot affect compiler paths.
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { SDK_FINGERPRINT } from "./identity.js";
+
+export const VISITOR_API_VERSION = 1;
+export const VISITOR_CAPABILITIES = Object.freeze([
+  "sfc",
+  "template",
+  "script",
+  "style",
+  "virtual-ts",
+  "diagnostics",
+  "lint",
+  "format",
+  "devtools-trace",
+]);
+
+const CAPABILITY_ORDER = new Map(
+  VISITOR_CAPABILITIES.map((capability, index) => [capability, index]),
+);
+const VISITOR_RUNTIME_FINGERPRINT = createHash("sha256")
+  .update(readFileSync(new URL("visitor.js", import.meta.url)))
+  .digest("hex");
+const plugins = new WeakSet();
+
+export class VisitorPluginValidationError extends TypeError {
+  constructor(code, field, message) {
+    super(`[visitor/${code}] ${field}: ${message}`);
+    this.name = "VisitorPluginValidationError";
+    this.code = code;
+    this.field = field;
+  }
+}
+
+/**
+ * Define an immutable v1 visitor descriptor without registering it in a Vize
+ * runtime. A host must explicitly negotiate the descriptor before invocation.
+ */
+export function defineVisitorPlugin(definition) {
+  record(definition, "definition", "invalid-definition");
+  const name = nonempty(definition.name, "name", "invalid-name");
+  const version = nonempty(definition.version, "version", "invalid-version");
+  apiVersion(definition.apiVersion, "apiVersion");
+  const capabilities = capabilitiesOf(definition.capabilities, "capabilities", true);
+  const visitors = visitorsOf(definition.visitors, capabilities);
+  const cacheInputs = cacheInputsOf(definition.cacheInputs);
+  const callbacks = capabilities.map((capability) => [capability, String(visitors[capability])]);
+  const fingerprint = createHash("sha256")
+    .update(
+      JSON.stringify([
+        SDK_FINGERPRINT,
+        VISITOR_RUNTIME_FINGERPRINT,
+        VISITOR_API_VERSION,
+        name,
+        version,
+        capabilities,
+        cacheInputs,
+        callbacks,
+      ]),
+    )
+    .digest("hex");
+  const plugin = immutable({
+    kind: "vize.visitor-plugin",
+    apiVersion: VISITOR_API_VERSION,
+    name,
+    version,
+    capabilities,
+    cacheInputs,
+    visitors,
+    fingerprint,
+  });
+  plugins.add(plugin);
+  return plugin;
+}
+
+/** Validate a host contract and fail closed when any requested capability is absent. */
+export function negotiateVisitorPlugin(plugin, host) {
+  if (!plugins.has(plugin)) {
+    fail("invalid-plugin", "plugin", "must be created by defineVisitorPlugin");
+  }
+  record(host, "host", "invalid-host-contract");
+  apiVersion(host.apiVersion, "host.apiVersion");
+  const available = capabilitiesOf(host.capabilities, "host.capabilities", false);
+  const supported = new Set(available);
+  const missing = plugin.capabilities.filter((capability) => !supported.has(capability));
+  if (missing.length > 0) {
+    fail(
+      "unsupported-capability",
+      "host.capabilities",
+      `missing ${missing.map((capability) => JSON.stringify(capability)).join(", ")}`,
+    );
+  }
+  return immutable({ apiVersion: VISITOR_API_VERSION, capabilities: [...plugin.capabilities] });
+}
+
+/**
+ * Invoke one negotiated visitor in an author fixture. This is not a compiler or
+ * linter registration path; production hosts own cancellation and isolation.
+ */
+export function runVisitorFixture(plugin, capability, event) {
+  if (!plugins.has(plugin)) {
+    fail("invalid-plugin", "plugin", "must be created by defineVisitorPlugin");
+  }
+  if (!CAPABILITY_ORDER.has(capability)) {
+    fail("unknown-capability", "capability", `${JSON.stringify(capability)} is not supported`);
+  }
+  if (!plugin.capabilities.includes(capability)) {
+    fail(
+      "undeclared-capability",
+      "capability",
+      `${JSON.stringify(capability)} is not declared by ${JSON.stringify(plugin.name)}`,
+    );
+  }
+  record(event, "event", "invalid-event");
+  apiVersion(event.apiVersion, "event.apiVersion");
+  if (event.capability !== capability) {
+    fail(
+      "invalid-event",
+      "event.capability",
+      `expected ${JSON.stringify(capability)}, received ${JSON.stringify(event.capability)}`,
+    );
+  }
+  nonempty(event.file, "event.file", "invalid-event");
+  if (!("payload" in event)) fail("invalid-event", "event.payload", "is required");
+  const result = plugin.visitors[capability](immutable(event));
+  if (result?.then) {
+    fail(
+      "async-visitor",
+      `visitors.${capability}`,
+      "returned a Promise; asynchronous visitors are unsupported",
+    );
+  }
+  if (result !== undefined) {
+    fail("invalid-visitor-result", `visitors.${capability}`, "must return undefined");
+  }
+}
+
+/** Adapt one negotiated virtual-TypeScript-only descriptor to the native host boundary. */
+export function createVirtualTsVisitorHost(plugin) {
+  negotiateVisitorPlugin(plugin, {
+    apiVersion: VISITOR_API_VERSION,
+    capabilities: ["virtual-ts"],
+  });
+  return immutable({
+    name: plugin.name,
+    version: plugin.version,
+    fingerprint: plugin.fingerprint,
+    run(eventJson) {
+      if (typeof eventJson !== "string") {
+        fail("invalid-event", "event", "must be serialized JSON");
+      }
+      let event;
+      try {
+        event = JSON.parse(eventJson);
+      } catch {
+        fail("invalid-event", "event", "must be valid JSON");
+      }
+      runVisitorFixture(plugin, "virtual-ts", event);
+      return "";
+    },
+  });
+}
+
+/** Adapt one negotiated devtools-trace-only descriptor to the recorder boundary. */
+export function createDevtoolsTraceVisitorHost(plugin) {
+  negotiateVisitorPlugin(plugin, {
+    apiVersion: VISITOR_API_VERSION,
+    capabilities: ["devtools-trace"],
+  });
+  return immutable({
+    name: plugin.name,
+    version: plugin.version,
+    fingerprint: plugin.fingerprint,
+    run(deliveryJson) {
+      if (typeof deliveryJson !== "string") {
+        fail("invalid-event", "delivery", "must be serialized JSON");
+      }
+      let delivery;
+      try {
+        delivery = JSON.parse(deliveryJson);
+      } catch {
+        fail("invalid-event", "delivery", "must be valid JSON");
+      }
+      record(delivery, "delivery", "invalid-event");
+      if (delivery.schemaVersion !== 1) {
+        fail("invalid-event", "delivery.schemaVersion", "must equal 1");
+      }
+      const sessionId = nonempty(delivery.sessionId, "delivery.sessionId", "invalid-event");
+      record(delivery.event, "delivery.event", "invalid-event");
+      const { event } = delivery;
+      if (!Number.isInteger(event.sequence) || event.sequence < 1) {
+        fail("invalid-event", "delivery.event.sequence", "must be a positive integer");
+      }
+      if (
+        typeof event.timestamp !== "number" ||
+        !Number.isFinite(event.timestamp) ||
+        event.timestamp < 0
+      ) {
+        fail("invalid-event", "delivery.event.timestamp", "must be a non-negative finite number");
+      }
+      const kind = nonempty(event.kind, "delivery.event.kind", "invalid-event");
+      const durationMs = event.durationMs ?? 0;
+      if (typeof durationMs !== "number" || !Number.isFinite(durationMs) || durationMs < 0) {
+        fail("invalid-event", "delivery.event.durationMs", "must be a non-negative finite number");
+      }
+      const { sequence, timestamp } = event;
+      const startNs = timestamp * 1_000_000;
+      const durationNs = durationMs * 1_000_000;
+      if (!Number.isFinite(startNs) || !Number.isFinite(durationNs)) {
+        fail("invalid-event", "delivery.event", "cannot be represented in nanoseconds");
+      }
+      const data = Object.fromEntries(
+        Object.entries(event).filter(
+          ([key]) =>
+            key !== "sequence" && key !== "timestamp" && key !== "kind" && key !== "durationMs",
+        ),
+      );
+      const source =
+        typeof event.source === "string" && event.source.trim() !== ""
+          ? event.source
+          : `vize-devtools://${encodeURIComponent(sessionId)}`;
+      const separator = kind.indexOf(":");
+      runVisitorFixture(plugin, "devtools-trace", {
+        apiVersion: VISITOR_API_VERSION,
+        capability: "devtools-trace",
+        file: source,
+        payload: {
+          events: [
+            {
+              id: `${sessionId}:${sequence}`,
+              parentId: null,
+              name: kind,
+              stage: separator === -1 ? kind : kind.slice(0, separator),
+              startNs,
+              durationNs,
+              data,
+            },
+          ],
+        },
+      });
+      return "";
+    },
+  });
+}
+
+function capabilitiesOf(value, field, requireNonempty) {
+  if (!Array.isArray(value) || (requireNonempty && value.length === 0)) {
+    fail(
+      "invalid-capabilities",
+      field,
+      requireNonempty ? "must be a non-empty array" : "must be an array",
+    );
+  }
+  const seen = new Set();
+  for (const [index, capability] of value.entries()) {
+    if (typeof capability !== "string" || !CAPABILITY_ORDER.has(capability)) {
+      fail(
+        "unknown-capability",
+        `${field}[${index}]`,
+        `${JSON.stringify(capability)} is not supported`,
+      );
+    }
+    if (seen.has(capability)) {
+      fail(
+        "duplicate-capability",
+        field,
+        `${JSON.stringify(capability)} is declared more than once`,
+      );
+    }
+    seen.add(capability);
+  }
+  return Object.freeze([...seen]);
+}
+
+function visitorsOf(value, capabilities) {
+  record(value, "visitors", "invalid-visitors");
+  const declared = new Set(capabilities);
+  for (const capability of Object.keys(value)) {
+    if (!CAPABILITY_ORDER.has(capability)) {
+      fail(
+        "unknown-capability",
+        `visitors.${capability}`,
+        `${JSON.stringify(capability)} is not supported`,
+      );
+    }
+    if (!declared.has(capability)) {
+      fail(
+        "undeclared-visitor",
+        `visitors.${capability}`,
+        "has no matching capability declaration",
+      );
+    }
+  }
+  const visitors = {};
+  for (const capability of capabilities) {
+    const callback = value[capability];
+    if (typeof callback !== "function") {
+      fail("missing-visitor", `visitors.${capability}`, "must be a synchronous function");
+    }
+    if (callback.constructor?.name === "AsyncFunction") {
+      fail("async-visitor", `visitors.${capability}`, "asynchronous visitors are unsupported");
+    }
+    visitors[capability] = callback;
+  }
+  return Object.freeze(visitors);
+}
+
+function cacheInputsOf(value) {
+  if (!Array.isArray(value)) {
+    fail("invalid-cache-inputs", "cacheInputs", "must be an explicit array");
+  }
+  const inputs = [];
+  const names = new Set();
+  for (const [index, input] of value.entries()) {
+    record(input, `cacheInputs[${index}]`, "invalid-cache-inputs");
+    const name = nonempty(input.name, `cacheInputs[${index}].name`, "invalid-cache-inputs");
+    if (name.startsWith("@vize/")) {
+      fail("invalid-cache-inputs", `cacheInputs[${index}].name`, "uses a reserved host prefix");
+    }
+    if (names.has(name)) {
+      fail(
+        "invalid-cache-inputs",
+        "cacheInputs",
+        `contains duplicate name ${JSON.stringify(name)}`,
+      );
+    }
+    if (typeof input.value !== "string") {
+      fail("invalid-cache-inputs", `cacheInputs[${index}].value`, "must be a string");
+    }
+    names.add(name);
+    inputs.push(Object.freeze({ name, value: input.value }));
+  }
+  return Object.freeze(inputs.sort((left, right) => left.name.localeCompare(right.name)));
+}
+
+function apiVersion(value, field) {
+  if (value !== VISITOR_API_VERSION) {
+    fail(
+      "unsupported-api-version",
+      field,
+      `${JSON.stringify(value)} is unsupported; expected ${VISITOR_API_VERSION}`,
+    );
+  }
+}
+
+function nonempty(value, field, code) {
+  if (typeof value !== "string" || value.trim() === "")
+    fail(code, field, "must be a non-empty string");
+  return value;
+}
+
+function record(value, field, code) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    fail(code, field, "must be an object");
+  }
+}
+
+function fail(code, field, message) {
+  throw new VisitorPluginValidationError(code, field, message);
+}
+
+function immutable(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) immutable(child);
+    Object.freeze(value);
+  }
+  return value;
+}