dsh-agent-plugins-market 0.5.2 → 0.6.0

package/lib/runtime/mcp-client/connection.js

@@ -0,0 +1,380 @@
+/**
+ * Connection supervisor: owns the MCP client/transport generations for one
+ * bridge instance, keeps the harness tool registry in sync with the live
+ * generation, and — when the connection drops — restarts the configured
+ * server with bounded exponential backoff.
+ *
+ * One outage shares one attempt budget (`maxAttempts` consecutive failed
+ * attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+ * connection that stays up past the stability window closes the outage, so
+ * the next disconnect starts a fresh budget while a crash-looping server —
+ * even one whose connects briefly succeed — still exhausts the cap instead of
+ * restarting forever. Exhaustion unregisters the server's tools and stops;
+ * disposal (including HMR) is the only way back from that state.
+ *
+ * Ported from the harness `dsh-mcp-client` supervisor (including the OAuth
+ * browser-leg hold: a failed initialize during a pending browser
+ * authorization holds the generation open — up to the loopback callback
+ * budget — instead of tearing down the authorization the user is mid-way
+ * through approving).
+ *
+ * @module runtime/mcp-client/connection
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+import { MAX_TIMER_DELAY_MS } from './host-seams.js';
+import { createTransport } from './transport.js';
+import { syncTools } from './tools.js';
+/** Defaults shared by the config and {@link resolveReconnectPolicy}. */
+export const RECONNECT_DEFAULTS = Object.freeze({
+    enabled: true,
+    initialDelayMs: 500,
+    maxDelayMs: 30_000,
+    maxAttempts: 10
+});
+// The SDK's stdio transport owns two two-second termination grace periods.
+// Keep one additional second for the process-close event that proves the old
+// generation is gone; timing out fails closed instead of overlapping children.
+const GENERATION_CLOSE_TIMEOUT_MS = 5_000;
+/**
+ * The one explicit resolve step from raw reconnect config to the policy the
+ * supervisor runs. Programmatic construction bypasses any schema layer, so
+ * every default and bound is re-judged here — misconfiguration fails the
+ * bridge instance at load.
+ *
+ * @param config - Raw `reconnect` config; omission uses the defaults.
+ * @param path - Diagnostic prefix naming the config location in thrown messages.
+ * @returns The frozen resolved policy.
+ */
+export function resolveReconnectPolicy(config, path) {
+    if (config !== undefined) {
+        for (const key of Object.keys(config)) {
+            if (!Object.hasOwn(RECONNECT_DEFAULTS, key))
+                throw new Error(`${path}.${key} is not a reconnect option`);
+        }
+    }
+    const enabled = config?.enabled ?? RECONNECT_DEFAULTS.enabled;
+    const initialDelayMs = config?.initialDelayMs ?? RECONNECT_DEFAULTS.initialDelayMs;
+    const maxDelayMs = config?.maxDelayMs ?? RECONNECT_DEFAULTS.maxDelayMs;
+    const maxAttempts = config?.maxAttempts ?? RECONNECT_DEFAULTS.maxAttempts;
+    if (!Number.isFinite(initialDelayMs) || initialDelayMs <= 0 || initialDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.initialDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (!Number.isFinite(maxDelayMs) || maxDelayMs <= 0 || maxDelayMs > MAX_TIMER_DELAY_MS) {
+        throw new Error(`${path}.maxDelayMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+    }
+    if (initialDelayMs > maxDelayMs) {
+        throw new Error(`${path}.initialDelayMs must be less than or equal to maxDelayMs`);
+    }
+    if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+        throw new Error(`${path}.maxAttempts must be a positive integer`);
+    }
+    return Object.freeze({ enabled, initialDelayMs, maxDelayMs, maxAttempts });
+}
+/**
+ * Start the supervised connection for one MCP server and keep it alive per
+ * the reconnect policy.
+ *
+ * @param host - The bridge host providing the tool registry and logger.
+ * @param config - Resolved bridge config selecting the transport and server identity.
+ * @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+ * @param credentials - The composition's credential store, when mounted; OAuth
+ *   state persists only when it is.
+ * @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+ */
+export function startConnection(host, config, policy, credentials) {
+    const label = `mcp-client(${config.serverName})`;
+    const opts = {
+        registrationFailure: 'contain',
+        serverName: config.serverName,
+        toolCallTimeoutMs: config.toolCallTimeoutMs
+    };
+    // The initial sync uses 'throw' when failOnStartupError is configured, so
+    // a registration conflict propagates to the startup-await path. Re-syncs
+    // and reconnect syncs always contain conflicts.
+    const startupOpts = config.failOnStartupError ? { ...opts, registrationFailure: 'throw' } : opts;
+    let disposed = false;
+    /** Current generation: the connecting or connected client; undefined during backoff waits and after final failure. */
+    let client;
+    /** Close signal paired with {@link client}; captured by dispose before current ownership is cleared. */
+    let clientClosed;
+    /** Live tool registrations owned by this server; only {@link enqueueSync} and dispose swap it. */
+    let disposers = new Map();
+    let reconnectTimer;
+    /** Consecutive failed connection attempts within the current outage. */
+    let failedAttempts = 0;
+    /** When the current generation finished connect + initial sync; undefined while down. */
+    let connectedAt;
+    /** The real error from the first connection attempt, for startup-await diagnostics. */
+    let firstAttemptError;
+    /** A generation may act only while it is the current one on a live bridge. */
+    const isCurrent = (generation) => !disposed && client === generation;
+    /**
+     * Serializes every syncTools call — initial syncs and notification re-syncs
+     * across all generations — so two syncs can never interleave their
+     * dispose-previous/register-next swap (which would double-dispose one
+     * generation and leak another).
+     */
+    let syncChain = Promise.resolve();
+    function enqueueSync(generation, syncOpts = opts) {
+        const run = syncChain.then(async () => {
+            if (!isCurrent(generation))
+                return;
+            disposers = await syncTools(generation, host, syncOpts, disposers);
+        });
+        // The chain tail must survive a failed sync; the enqueuing caller owns reporting.
+        syncChain = run.catch(() => { });
+        return run;
+    }
+    /** One disconnect decision per generation: the isCurrent guard makes racing close/error signals idempotent. */
+    function generationDown(generation) {
+        if (!isCurrent(generation))
+            return;
+        client = undefined;
+        clientClosed = undefined;
+        scheduleReconnect();
+    }
+    /** Wait for the transport-owned close signal without letting a broken transport wedge teardown forever. */
+    function waitForClose(closed) {
+        return new Promise(resolve => {
+            const timeout = setTimeout(() => {
+                resolve(false);
+            }, GENERATION_CLOSE_TIMEOUT_MS);
+            timeout.unref();
+            void closed.then(() => {
+                clearTimeout(timeout);
+                resolve(true);
+            });
+        });
+    }
+    function scheduleReconnect() {
+        const lostEstablishedConnection = connectedAt !== undefined;
+        if (!policy.enabled) {
+            const message = lostEstablishedConnection
+                ? 'connection lost and reconnect is disabled — registered tools will fail until an HMR reload or Host restart'
+                : 'connection failed and reconnect is disabled — no tools were registered; reload the plugin or restart the Host to connect';
+            host.logger.error(`${label}: ${message}`);
+            return;
+        }
+        // A connection that stayed up past the stability window (= maxDelayMs, the
+        // longest backoff spacing) ended the previous outage: start a fresh budget.
+        if (connectedAt !== undefined && Date.now() - connectedAt >= policy.maxDelayMs)
+            failedAttempts = 0;
+        connectedAt = undefined;
+        failedAttempts += 1;
+        if (failedAttempts > policy.maxAttempts) {
+            // Enqueue the give-up disposal so it cannot race an in-flight sync's
+            // phase-2 swap (which checks isCurrent inside the queue).
+            syncChain = syncChain.then(() => {
+                for (const dispose of disposers.values())
+                    dispose();
+                disposers = new Map();
+            });
+            host.logger.error(`${label}: giving up after ${policy.maxAttempts} consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect`);
+            return;
+        }
+        const delayMs = Math.min(policy.maxDelayMs, policy.initialDelayMs * 2 ** (failedAttempts - 1));
+        const action = lostEstablishedConnection ? 'connection lost; reconnecting' : 'connection failed; retrying';
+        host.logger.warn(`${label}: ${action} in ${delayMs}ms (attempt ${failedAttempts}/${policy.maxAttempts})`);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = undefined;
+            settling = connectGeneration(false);
+        }, delayMs);
+        // An armed reconnect timer must never hold the process open on its own.
+        reconnectTimer.unref();
+    }
+    /**
+     * One connection attempt: fresh transport + client (the MCP SDK binds a
+     * Protocol to one transport for life), connect, then queue the initial tool
+     * sync. The startup flag belongs to the attempt rather than the shared sync
+     * queue, so an early notification cannot consume strict startup semantics.
+     * Every failure funnels through {@link generationDown}; success arms the
+     * onclose-driven disconnect path. Never rejects.
+     *
+     * @param startup - Whether this is the bridge's activation attempt.
+     */
+    async function connectGeneration(startup) {
+        const generation = new Client({ name: 'dsh-agent-plugins-market', version: '0.1.0' }, { capabilities: {} });
+        const closed = Promise.withResolvers();
+        let attemptSettled = false;
+        let closeObserved = false;
+        const hasClosed = () => closeObserved;
+        client = generation;
+        clientClosed = closed.promise;
+        generation.onclose = () => {
+            closeObserved = true;
+            closed.resolve();
+            // A failed connect owns its close barrier in the catch path below. An
+            // established generation can transition down directly from this signal.
+            if (attemptSettled)
+                generationDown(generation);
+        };
+        // Registered before connect so a list change during the initial sync is
+        // queued behind it rather than dropped.
+        generation.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+            if (!isCurrent(generation))
+                return;
+            host.logger.info(`${label}: tool list changed, re-syncing`);
+            try {
+                await enqueueSync(generation);
+            }
+            catch (error) {
+                // Fetch-phase failure: the previous generation is still registered
+                // and `disposers` still owns it — keep serving the last good list.
+                if (!disposed)
+                    host.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
+            }
+        });
+        const { transport, oauthProvider } = createTransport(config, credentials, (message) => {
+            host.logger.info(message);
+        });
+        try {
+            await generation.connect(transport);
+            if (hasClosed()) {
+                attemptSettled = true;
+                generationDown(generation);
+                return;
+            }
+            await enqueueSync(generation, startup ? startupOpts : opts);
+        }
+        catch (error) {
+            if (firstAttemptError === undefined)
+                firstAttemptError = error;
+            // Disposal clears current ownership before it closes the generation, so
+            // only a live supervisor reports an attempt failure.
+            if (isCurrent(generation))
+                host.logger.warn(`${label}: connection attempt failed: ${String(error)}`);
+            // A pending browser leg outlives the initialize timeout: the human is
+            // mid-approval. Hold this generation open — transport and loopback
+            // listener stay alive — until the leg settles; abandoning it would
+            // discard the very authorization the user is completing.
+            const leg = oauthProvider?.browserLeg;
+            if (leg !== undefined) {
+                host.logger.warn(`${label}: waiting for browser authorization (up to 5 minutes) — approve access in the page that opened`);
+                const legSettled = await leg;
+                attemptSettled = true;
+                if (!isCurrent(generation))
+                    return;
+                if (hasClosed()) {
+                    generationDown(generation);
+                    return;
+                }
+                if (!legSettled) {
+                    generationDown(generation);
+                    return;
+                }
+                // The exchange succeeded inside this generation: finish establishing
+                // it (tool sync + connected bookkeeping) instead of respawning.
+                try {
+                    await enqueueSync(generation, startup ? startupOpts : opts);
+                }
+                catch (syncError) {
+                    if (isCurrent(generation))
+                        host.logger.warn(`${label}: tool sync after authorization failed: ${String(syncError)}`);
+                    try {
+                        await generation.close();
+                    }
+                    catch {
+                        /* transport already gone */
+                    }
+                    const quiescedSync = hasClosed() || (await waitForClose(closed.promise));
+                    if (!quiescedSync) {
+                        client = undefined;
+                        clientClosed = undefined;
+                        host.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes`);
+                        return;
+                    }
+                    generationDown(generation);
+                    return;
+                }
+                if (hasClosed()) {
+                    generationDown(generation);
+                    return;
+                }
+                if (!isCurrent(generation))
+                    return;
+                connectedAt = Date.now();
+                if (failedAttempts > 0)
+                    host.logger.info(`${label}: authorized and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
+                return;
+            }
+            try {
+                await generation.close();
+            }
+            catch {
+                /* transport already gone */
+            }
+            const quiesced = hasClosed() || (await waitForClose(closed.promise));
+            attemptSettled = true;
+            if (!isCurrent(generation))
+                return;
+            if (!quiesced) {
+                client = undefined;
+                clientClosed = undefined;
+                host.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+                return;
+            }
+            generationDown(generation);
+            return;
+        }
+        attemptSettled = true;
+        if (hasClosed()) {
+            generationDown(generation);
+            return;
+        }
+        if (!isCurrent(generation))
+            return;
+        connectedAt = Date.now();
+        if (failedAttempts > 0)
+            host.logger.info(`${label}: reconnected and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
+    }
+    /** The in-flight (or last settled) connection attempt; dispose awaits it for quiescence. */
+    let settling = connectGeneration(true);
+    // The ready promise settles when the first attempt finishes (regardless of
+    // success). If the first attempt fails and reconnect is enabled, the
+    // supervisor is already scheduling a retry — ready just reports the outcome.
+    const ready = settling.then(() => {
+        // After settling: if client is set the initial connect+sync succeeded.
+        // If not, the supervisor either scheduled a retry (error logged) or gave
+        // up (error logged). Either way the outcome is reported with the real error.
+        // Note: settling.then() is a microtask; stdio onclose is a macrotask — so
+        // a server that crashes AFTER a successful initial sync cannot flip client
+        // to undefined before this continuation runs.
+        if (client !== undefined)
+            return {};
+        /* v8 ignore next -- defensive: firstAttemptError is always set when connect/sync fails */
+        return { error: firstAttemptError ?? new Error(`${label}: initial connection failed`) };
+    });
+    return {
+        ready,
+        async dispose() {
+            disposed = true;
+            if (reconnectTimer !== undefined) {
+                clearTimeout(reconnectTimer);
+                reconnectTimer = undefined;
+            }
+            const current = client;
+            const currentClosed = clientClosed;
+            client = undefined;
+            clientClosed = undefined;
+            if (current !== undefined) {
+                try {
+                    await current.close();
+                }
+                catch {
+                    /* transport already gone */
+                }
+                if (currentClosed !== undefined && !(await waitForClose(currentClosed))) {
+                    host.logger.error(`${label}: generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms during disposal — server shutdown may be incomplete`);
+                }
+            }
+            // Quiesce, don't just request it: the in-flight attempt enqueues its
+            // sync before settling, so awaiting both leaves `disposers` final.
+            await settling;
+            await syncChain;
+            for (const dispose of disposers.values())
+                dispose();
+            disposers = new Map();
+        }
+    };
+}

package/lib/runtime/mcp-client/host-seams.js

@@ -0,0 +1,88 @@
+/**
+ * Local ports of the tiny host seams the self-built MCP client needs.
+ *
+ * The market plugin must stay self-contained at runtime: it cannot import
+ * host-internal packages that are not published at compatible versions, and
+ * every one of these seams is a small pure function or constant. Each port
+ * below is copied verbatim (semantics, not prose) from the harness source at
+ * `0.1.1-rc.2` and carries the upstream reference it came from, so a future
+ * host change can be re-diffed against `~/workspace/deepseek-harness`.
+ *
+ * Anything larger than a handful of lines (the JSON Schema subset validator)
+ * lives in its own module.
+ *
+ * @module runtime/mcp-client/host-seams
+ */
+// ---- dsh-timeout: MAX_TIMER_DELAY_MS (packages/util/timeout/src/index.ts) ----
+/**
+ * The largest delay `setTimeout` accepts without overflowing to a 1ms clamp
+ * (2^31 - 1). Shared guard for reconnect and callback timers.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+// ---- dsh-subprocess: scrubbedParentEnv (packages/subprocess/subprocess/src/index.ts) ----
+/** `DSH_*` environment namespace owned by the harness. */
+export const DSH_ENV_PREFIX = 'DSH_';
+/**
+ * Credential-shaped environment names are NOT forwarded to MCP server child
+ * processes (the harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a
+ * spawned server implicitly). Deliberately supplied env entries survive
+ * because the config's explicit env merges after the scrub.
+ */
+export const SENSITIVE_ENV_PATTERN = /KEY|PASSWORD|SECRET|TOKEN/i;
+/**
+ * The ambient parent environment minus credential-shaped names and minus all
+ * `DSH_*` names — the canonical base every harness child starts from. `PATH`,
+ * `HOME`, locale, and proxy variables survive, so child CLIs run normally;
+ * harness identity never leaks implicitly. Both scrubs match case-insensitively:
+ * Windows environment names are case-insensitive, so a parent `dsh_*` entry
+ * would otherwise survive and read back as `$env:DSH_*` in the child.
+ * @returns a fresh environment object safe to hand to a child spawn.
+ */
+export function scrubbedParentEnv() {
+    const env = {};
+    for (const [key, value] of Object.entries(process.env)) {
+        if (value !== undefined && !SENSITIVE_ENV_PATTERN.test(key) && !key.toUpperCase().startsWith(DSH_ENV_PREFIX))
+            env[key] = value;
+    }
+    return env;
+}
+/** Key segments are lowercase hyphenated identifiers. */
+const KEY_SEGMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name (here: the `mcp-auth` record scope).
+ * @param id - the plugin's own addressing unit (here: the folded serverName).
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export function credentialKey(scope, id) {
+    for (const segment of [scope, id]) {
+        if (!KEY_SEGMENT_PATTERN.test(segment)) {
+            throw new TypeError(`credential key segment "${segment}" must match ${String(KEY_SEGMENT_PATTERN)}`);
+        }
+    }
+    return `${scope}/${id}`;
+}
+// ---- dsh-attachment: image admission error routing (packages/attachment/attachment/src/error.ts) ----
+/** Caller-correctable attachment failure codes raised while admitting image input. */
+const IMAGE_ADMISSION_ERROR_CODES = [
+    'TOO_MANY_IMAGES',
+    'IMAGES_TOO_LARGE',
+    'UNSUPPORTED_IMAGE_TYPE',
+    'INVALID_IMAGE_BASE64',
+    'INVALID_IMAGE',
+    'IMAGE_TYPE_MISMATCH',
+    'IMAGE_TOO_LARGE',
+    'IMAGE_TOO_MANY_PIXELS',
+    'IMAGE_DIMENSION_TOO_LARGE'
+];
+/** Runtime membership for structurally compatible errors crossing package boundaries. */
+const IMAGE_ADMISSION_ERROR_CODE_SET = new Set(IMAGE_ADMISSION_ERROR_CODES);
+/**
+ * Distinguish caller-correctable image admission failures from storage faults,
+ * so an admission refusal projects text diagnostics while a storage fault is
+ * reported as such.
+ */
+export function isImageAdmissionError(error) {
+    return error instanceof Error && 'code' in error && typeof error.code === 'string' && IMAGE_ADMISSION_ERROR_CODE_SET.has(error.code);
+}

package/lib/runtime/mcp-client/json-schema-subset.js

@@ -0,0 +1,181 @@
+/**
+ * Local port of the harness's enforced JSON Schema subset validator
+ * (`@deepseek-ai/dsh-tools` `json-schema.ts`, rc.2) — narrowed to the one use
+ * the MCP bridge has: deciding whether an MCP server's advertised
+ * `outputSchema` may ride a tool registration as a structured-output schema.
+ *
+ * The upstream validator is 656 lines with realm-safe JSON intrinsics; this
+ * port keeps the *contract* — a closed keyword table, one scalar `type`,
+ * nested structure, and "unsupported keywords reject rather than pass
+ * unenforced" — with a conservative structural check. A schema this check
+ * wrongly rejects only loses structured typing (the bridge falls back to
+ * untyped JSON, exactly the upstream failure mode); one it wrongly accepts
+ * would flow into the host registry, so every branch here fails closed.
+ *
+ * @module runtime/mcp-client/json-schema-subset
+ */
+/** Constraint keywords the subset enforces; anything else rejects. */
+const CONSTRAINT_KEYWORDS = new Set(['type', 'oneOf', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const']);
+/** Annotation keywords accepted but never enforced. */
+const ANNOTATION_KEYWORDS = new Set(['description', 'title', 'default', 'examples']);
+const SCHEMA_TYPES = ['object', 'array', 'string', 'number', 'integer', 'boolean', 'null'];
+/** Narrow a raw value to a plain string-keyed record. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether a value is a JSON scalar (the only `enum`/`const` vocabulary). */
+function isJsonScalar(value) {
+    return value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+}
+/** Whether a value is a lossless JSON composite (round-trip checked). */
+function isLosslessJson(value) {
+    if (!isRecord(value) && !Array.isArray(value))
+        return isJsonScalar(value);
+    try {
+        return JSON.parse(JSON.stringify(value)) !== undefined || value !== undefined;
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether one scalar satisfies a declared schema type (integers include whole numbers). */
+function scalarMatches(schemaType, value) {
+    if (schemaType === undefined)
+        return true;
+    switch (schemaType) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number';
+        case 'integer':
+            return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'null':
+            return value === null;
+        /* v8 ignore next -- scalar values never satisfy the container types */
+        case 'object':
+        case 'array':
+            return false;
+    }
+}
+/**
+ * Assert that a raw schema uses only the enforced subset. Annotation-only
+ * schemas are accepted as the standard unconstrained-JSON form.
+ * @param schema - untrusted raw JSON Schema.
+ * @throws Error listing every violation when the schema leaves the subset.
+ */
+export function assertSupportedJsonSchema(schema) {
+    const violations = [];
+    checkSchemaNode(schema, 'schema', violations, new Set());
+    if (violations.length > 0) {
+        throw new Error(`unsupported JSON schema: ${violations.join('; ')}`);
+    }
+}
+/** Depth-first walk of one schema node; violations accumulate in walk order. */
+function checkSchemaNode(node, path, violations, seen) {
+    if (seen.has(node)) {
+        violations.push(`${path} is recursive; the subset does not accept recursive schemas`);
+        return;
+    }
+    if (!isRecord(node)) {
+        violations.push(`${path} must be an object`);
+        return;
+    }
+    seen.add(node);
+    try {
+        for (const key of Object.keys(node)) {
+            if (!CONSTRAINT_KEYWORDS.has(key) && !ANNOTATION_KEYWORDS.has(key)) {
+                violations.push(`${path}.${key} is not part of the enforced subset`);
+            }
+        }
+        const hasType = Object.hasOwn(node, 'type');
+        const hasOneOf = Object.hasOwn(node, 'oneOf');
+        const type = hasType ? node.type : undefined;
+        if (hasType && !SCHEMA_TYPES.includes(type)) {
+            violations.push(`${path}.type must be one of ${SCHEMA_TYPES.join(', ')}`);
+        }
+        if (hasOneOf) {
+            if (hasType)
+                violations.push(`${path} must not declare both type and oneOf`);
+            const branches = node.oneOf;
+            if (!Array.isArray(branches) || branches.length < 2) {
+                violations.push(`${path}.oneOf requires at least two branches`);
+            }
+            else {
+                for (const [index, branch] of branches.entries()) {
+                    checkSchemaNode(branch, `${path}.oneOf[${index}]`, violations, seen);
+                }
+            }
+        }
+        if (Object.hasOwn(node, 'properties')) {
+            if (type !== 'object')
+                violations.push(`${path}.properties is only valid on an object schema`);
+            const properties = node.properties;
+            if (!isRecord(properties)) {
+                violations.push(`${path}.properties must be an object of schemas`);
+            }
+            else {
+                for (const [name, property] of Object.entries(properties)) {
+                    checkSchemaNode(property, `${path}.properties.${name}`, violations, seen);
+                }
+            }
+        }
+        if (Object.hasOwn(node, 'required')) {
+            if (type !== 'object')
+                violations.push(`${path}.required is only valid on an object schema`);
+            const required = node.required;
+            if (!Array.isArray(required) || !required.every(entry => typeof entry === 'string')) {
+                violations.push(`${path}.required must be an array of property names`);
+            }
+            else {
+                const properties = isRecord(node.properties) ? node.properties : undefined;
+                for (const name of required) {
+                    if (properties === undefined || !Object.hasOwn(properties, name)) {
+                        violations.push(`${path}.required lists "${name}" which has no declared property`);
+                    }
+                }
+            }
+        }
+        if (Object.hasOwn(node, 'additionalProperties')) {
+            if (type !== 'object')
+                violations.push(`${path}.additionalProperties is only valid on an object schema`);
+            if (typeof node.additionalProperties !== 'boolean') {
+                violations.push(`${path}.additionalProperties must be a boolean`);
+            }
+        }
+        if (Object.hasOwn(node, 'items')) {
+            if (type !== 'array')
+                violations.push(`${path}.items is only valid on an array schema`);
+            checkSchemaNode(node.items, `${path}.items`, violations, seen);
+        }
+        if (Object.hasOwn(node, 'enum')) {
+            const values = node.enum;
+            if (!Array.isArray(values) || values.length === 0 || !values.every(isJsonScalar)) {
+                violations.push(`${path}.enum must be a non-empty array of JSON scalars`);
+            }
+            else {
+                for (const value of values) {
+                    if (!scalarMatches(type, value)) {
+                        violations.push(`${path}.enum values must match the declared ${String(type)} type`);
+                        break;
+                    }
+                }
+            }
+        }
+        if (Object.hasOwn(node, 'const')) {
+            const value = node.const;
+            if (!isJsonScalar(value) || !scalarMatches(type, value)) {
+                violations.push(`${path}.const must be a scalar matching the declared schema type`);
+            }
+        }
+        for (const annotation of ['default', 'examples']) {
+            if (Object.hasOwn(node, annotation) && !isLosslessJson(node[annotation])) {
+                violations.push(`${path}.${annotation} must be lossless JSON`);
+            }
+        }
+    }
+    finally {
+        seen.delete(node);
+    }
+}