fix(schema): stop an unresolvable $ref silently disabling verb validation

`validateVerb('connect', {to, zzz_not_a_real_key})` returned
`{"valid":true,"errors":[]}` — a config nobody validated came back clean.

The bundled schema.json holds exactly one non-local `$ref`:
`$defs/SWMLAction.SWML -> "SWMLObject.json"`, a sibling spec file that is not
bundled. Ajv resolves refs EAGERLY, so compiling any verb whose `$defs` subtree
reaches `SWMLAction` threw `can't resolve reference SWMLObject.json from id #`.
`getVerbValidator`'s bare `catch` swallowed that and returned null, and
`validateVerb` then fell through to `validateVerbLightweight`, which only checks
required props — so a COMPILE FAILURE read as a PASS.

The blast radius was never just `connect`: 8 of 39 verbs degraded this way, all
via `... -> Action -> SWMLAction -> SWMLObject.json` —
ai, ai_sidecar, amazon_bedrock, cond, connect, execute, join_conference, switch.

Two independent fixes:

1. Ref policy (the root). Register a permissive placeholder for the schema's
   unbundled external ref on our own Ajv instance, so the ref RESOLVES and
   compilation succeeds. Every other constraint — crucially the
   `unevaluatedProperties` closure that rejects unknown keys — is then enforced
   normally; only the nested `SWML` payload goes unchecked. This is exactly how
   go's santhosh-tekuri validator already behaves, which is why go never showed
   the symptom. schema.json is NOT modified, vendored, or reinterpreted.

2. Loud degradation (the backstop). A compile failure is now recorded and
   reported as an error instead of falling through to the permissive lightweight
   check, so validation that did not happen can never again read as `valid:true`.
   New `compileFailedVerbs` / `precompileVerbValidators()` make the condition
   observable rather than silent.

Both directions covered by 9 regression tests: a forbidden key is rejected and a
legitimate config still passes on each of the 8 verbs, and the guard is proven by
reinstating the pre-fix Ajv instance and asserting a refusal rather than a pass.
Negative-controlled — with the ref policy disabled, 9 of them fail.

Full suite: 133 files / 2835 tests passed. SURFACE's DRIFT/SURFACE-FRESH/
SURFACE-DIFF failures reproduce identically on clean main and are unrelated.

Supplying the real SWMLObject.json remains an owner-held schema-artifact change
(held under #223); afterwards the placeholder in UNBUNDLED_EXTERNAL_REFS can be
dropped and the nested SWML payload becomes fully validated too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PbNcuqH8o9WEoEnT24q4wB

Author: mjerris

src/SchemaUtils.ts

@@ -10,6 +10,39 @@ import { createRequire } from 'module';
 import Ajv2020 from 'ajv/dist/2020.js';
 import type { ValidateFunction } from 'ajv';
 
+/** The subset of the Ajv instance surface this module uses. */
+interface AjvInstance {
+  compile: (s: object) => ValidateFunction;
+  addSchema: (s: object, key: string) => void;
+}
+
+/**
+ * External `$ref` targets the bundled schema names but does NOT bundle.
+ *
+ * The bundled `schema.json` contains exactly one non-local `$ref`:
+ * `$defs/SWMLAction.SWML -> "SWMLObject.json"`, a sibling spec file that is not
+ * part of the bundle. Ajv resolves refs EAGERLY at compile time, so ANY verb
+ * whose `$defs` subtree transitively reaches `SWMLAction` used to throw
+ * `can't resolve reference SWMLObject.json from id #` — 8 of 39 verbs
+ * (`ai`, `ai_sidecar`, `amazon_bedrock`, `cond`, `connect`, `execute`,
+ * `join_conference`, `switch`), all via
+ * `… -> Action -> SWMLAction -> SWMLObject.json`.
+ *
+ * Registering a permissive placeholder makes the ref RESOLVE to an
+ * always-accept schema, so compilation succeeds and every OTHER constraint in
+ * the verb — most importantly the `unevaluatedProperties` closure that rejects
+ * unknown/misspelled keys — is enforced normally. Only the contents of the
+ * nested `SWML` payload go unchecked, which is precisely the behaviour of go's
+ * santhosh-tekuri validator, which tolerates the unresolved ref and still
+ * rejects the surrounding unknown keys.
+ *
+ * This is an Ajv *ref-resolution policy* applied to our own Ajv instance. It
+ * does not modify, vendor, or reinterpret `schema.json`; supplying the real
+ * `SWMLObject.json` remains an owner-held schema-artifact change, after which
+ * this placeholder can simply be dropped.
+ */
+const UNBUNDLED_EXTERNAL_REFS = ['SWMLObject.json'] as const;
+
 /** Result of validating a SWML document. */
 export interface ValidationResult {
   /** Whether the document passed all validation checks. */
@@ -143,7 +176,10 @@ export class SchemaUtils {
    *  `null` entry means a validator couldn't be built for that verb (fall back
    *  to lightweight). Shared Ajv instance is created once. */
   private verbValidators: Map<string, ValidateFunction | null> = new Map();
-  private ajv: { compile: (s: object) => ValidateFunction } | null | undefined = undefined;
+  private ajv: AjvInstance | null | undefined = undefined;
+  /** Verb names whose validator FAILED TO COMPILE (as opposed to verbs for which
+   *  no full validator is applicable). See {@link compileFailedVerbs}. */
+  private compileFailures: Map<string, string> = new Map();
 
   /**
    * Create a SchemaUtils instance.
@@ -181,6 +217,7 @@ export class SchemaUtils {
   loadSchema(): Record<string, unknown> | null {
     // A (re)load may change the schema; drop any compiled verb validators.
     this.verbValidators.clear();
+    this.compileFailures.clear();
     this.ajv = undefined;
     // Try custom schema path first (mirrors Python's schema_path parameter)
     if (this._schemaPath) {
@@ -251,6 +288,37 @@ export class SchemaUtils {
     return true;
   }
 
+  /**
+   * The verbs whose full validator FAILED TO COMPILE, mapped to the compiler
+   * error — i.e. verbs for which {@link validateVerb} cannot actually validate.
+   *
+   * Only populated for verbs that have been validated at least once (validators
+   * compile lazily). It exists so a compile failure is OBSERVABLE rather than
+   * silent: previously such a failure fell through to the permissive lightweight
+   * check and the caller received `{valid: true, errors: []}` for a config
+   * nobody had validated.
+   *
+   * @returns A verb-name → compile-error map; empty when every compiled verb
+   *   validator built successfully.
+   */
+  get compileFailedVerbs(): Record<string, string> {
+    return Object.fromEntries(this.compileFailures);
+  }
+
+  /**
+   * Force every verb's full validator to compile, and report which ones failed.
+   *
+   * Validators are otherwise built lazily on first use, so a compile failure
+   * stays invisible until some caller happens to validate that verb. Calling
+   * this makes the whole set testable in one step.
+   *
+   * @returns A verb-name → compile-error map; empty when all verbs compile.
+   */
+  precompileVerbValidators(): Record<string, string> {
+    for (const verbName of this.verbs.keys()) this.getVerbValidator(verbName);
+    return this.compileFailedVerbs;
+  }
+
   /**
    * Get all verb names defined in the schema.
    * @returns Array of verb names (e.g. ["answer", "ai", "hangup", ...]).
@@ -388,6 +456,24 @@ export class SchemaUtils {
       };
     }
 
+    // No full validator. Distinguish the two very different reasons:
+    //  (a) the verb's schema FAILED TO COMPILE — validation did not happen, and
+    //      reporting `valid: true` here would be a false clean bill of health.
+    //      Refuse loudly instead.
+    //  (b) no full validator is applicable (partial/mocked schema, verb absent
+    //      from `$defs`) — the lightweight required-props check is the intended,
+    //      documented behaviour.
+    const compileError = this.compileFailures.get(verbName);
+    if (compileError !== undefined) {
+      return {
+        valid: false,
+        errors: [
+          `Schema validation unavailable for '${verbName}': its schema failed to compile ` +
+            `(${compileError}). The config was NOT validated; this is not a pass.`,
+        ],
+      };
+    }
+
     return this.validateVerbLightweight(verbName, config);
   }
 
@@ -397,7 +483,7 @@ export class SchemaUtils {
    * — a partial/mocked schema) so callers fall back to lightweight validation,
    * the TS mirror of Python's `_validate_verb_full` guard.
    */
-  private getAjv(): { compile: (s: object) => ValidateFunction } | null {
+  private getAjv(): AjvInstance | null {
     if (this.ajv !== undefined) return this.ajv;
     const props = (this.schema?.['properties'] as Record<string, unknown> | undefined) ?? {};
     if (!this.schema || !('sections' in props)) {
@@ -411,11 +497,24 @@ export class SchemaUtils {
     // stderr with one warning per field). We validate structure/keys, not
     // formats.
     const AjvCtor = (Ajv2020 as unknown as { default?: typeof Ajv2020 }).default ?? Ajv2020;
-    this.ajv = new (AjvCtor as new (o: object) => { compile: (s: object) => ValidateFunction })({
+    const ajv = new (AjvCtor as new (o: object) => AjvInstance)({
       allErrors: true,
       strict: false,
       logger: false,
     });
+    // Ref policy: resolve the schema's unbundled external `$ref`s to a
+    // permissive placeholder so eager resolution cannot make compilation throw.
+    // See UNBUNDLED_EXTERNAL_REFS for why this is a policy and not a schema edit.
+    for (const ref of UNBUNDLED_EXTERNAL_REFS) {
+      try {
+        ajv.addSchema({ $id: ref }, ref);
+      } catch {
+        // A duplicate/invalid registration must not disable validation wholesale;
+        // if the ref genuinely can't be satisfied the per-verb compile below will
+        // fail and be reported LOUDLY rather than degrading silently.
+      }
+    }
+    this.ajv = ajv;
     return this.ajv;
   }
 
@@ -444,8 +543,17 @@ export class SchemaUtils {
         // it the raw const-union is enforced and the validator rejects values
         // the platform accepts (see applyWiden's own comment).
         built = ajv.compile(applyWiden({ $defs: defs, ...(verb.definition as object) }) as object);
-      } catch {
+        this.compileFailures.delete(verbName);
+      } catch (e) {
+        // A COMPILE FAILURE IS NOT "NOTHING TO VALIDATE". Record it so the
+        // caller is never handed a silent pass for a verb nobody validated:
+        // `validateVerb` reports it as an error rather than falling through to
+        // the always-permissive lightweight check. (Regression guarded: the
+        // unresolved external `$ref` SWMLObject.json used to make 8 verbs —
+        // connect among them — accept arbitrary unknown keys with
+        // `{valid:true,errors:[]}`.)
         built = null;
+        this.compileFailures.set(verbName, (e as Error)?.message ?? String(e));
       }
     }
     this.verbValidators.set(verbName, built);

tests/SchemaUtils.verb.test.ts

@@ -2,6 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import Ajv2020 from 'ajv/dist/2020.js';
 import { SchemaUtils } from '../src/SchemaUtils.js';
 
 /**
@@ -31,6 +32,22 @@ function schemaDefKeyForVerb(schemaDoc: Record<string, unknown>, verbName: strin
   throw new Error(`no $defs entry declares verb '${verbName}'`);
 }
 
+/** Ajv's ESM/CJS interop default, as SchemaUtils itself resolves it. */
+const AjvCtor = ((Ajv2020 as unknown as { default?: typeof Ajv2020 }).default ??
+  Ajv2020) as unknown as new (o: object) => object;
+
+/** A minimal VALID config for each verb that reaches the unbundled external $ref. */
+const legitConfigs: Record<string, unknown> = {
+  ai: { prompt: { text: 'hello' } },
+  ai_sidecar: { prompt: { text: 'hello' }, lang: 'en' },
+  amazon_bedrock: { prompt: { text: 'hello' } },
+  cond: [{ when: 'x == 1', then: [{ hangup: {} }] }],
+  connect: { to: 'sip:alice@example.com' },
+  execute: { dest: 'main' },
+  join_conference: { name: 'room1' },
+  switch: { variable: 'x', case: { a: [{ hangup: {} }] } },
+};
+
 describe('SchemaUtils — verb extraction and validation', () => {
   let schema: SchemaUtils;
 
@@ -330,6 +347,89 @@ describe('SchemaUtils — verb extraction and validation', () => {
     });
   });
 
+  // A verb whose $defs subtree transitively reaches `SWMLAction` hits the
+  // schema's one unbundled external `$ref` (`SWMLObject.json`). Ajv resolves
+  // refs EAGERLY, so compiling those verbs used to THROW; `getVerbValidator`'s
+  // bare catch swallowed it and `validateVerb` fell through to the permissive
+  // lightweight check — so a config nobody validated came back
+  // `{valid: true, errors: []}`. Measured on main @6a2aa09:
+  //   validateVerb('connect', {to, zzz_not_a_real_key}) -> {"valid":true,"errors":[]}
+  // 8 of 39 verbs degraded this way, all via
+  // `… -> Action -> SWMLAction -> SWMLObject.json`.
+  describe('unbundled external $ref must not silently disable validation', () => {
+    // Every verb that reached SWMLAction, i.e. the full blast radius.
+    const previouslyDegraded = [
+      'ai',
+      'ai_sidecar',
+      'amazon_bedrock',
+      'cond',
+      'connect',
+      'execute',
+      'join_conference',
+      'switch',
+    ];
+
+    // Compiling all 39 verbs eagerly is a test-only sweep and costs ~2.5s: the 7
+    // verbs that recurse through `SWMLMethod` are ~200-400ms each (they were
+    // "free" before only because they threw immediately). Real callers compile
+    // lazily and cache — one cold verb is ~330ms, warm is ~0.02ms.
+    it('compiles a validator for EVERY verb in the schema', () => {
+      expect(schema.precompileVerbValidators()).toEqual({});
+    }, 30_000);
+
+    it('rejects an unknown key on connect (the reported case)', () => {
+      const result = schema.validateVerb('connect', {
+        to: 'sip:alice@example.com',
+        zzz_not_a_real_key: 1,
+      });
+      expect(result.valid).toBe(false);
+    });
+
+    it('still accepts a legitimate connect config', () => {
+      expect(schema.validateVerb('connect', { to: 'sip:alice@example.com' }).valid).toBe(true);
+    });
+
+    it.each(previouslyDegraded)('rejects an unknown key on %s', (verb) => {
+      // `cond` takes an ARRAY of CondParams; inject the bogus key into an element.
+      const config: Record<string, unknown> | unknown[] =
+        verb === 'cond'
+          ? [{ when: 'x == 1', then: [{ hangup: {} }], zzz_not_a_real_key: 1 }]
+          : { ...(legitConfigs[verb] as object), zzz_not_a_real_key: 1 };
+      expect(schema.validateVerb(verb, config).valid).toBe(false);
+    });
+
+    it.each(previouslyDegraded)('still accepts a legitimate %s config', (verb) => {
+      expect(schema.validateVerb(verb, legitConfigs[verb]).valid).toBe(true);
+    });
+
+    // The ref policy is the root fix; THIS is the backstop. Even if a verb's
+    // schema someday fails to compile for an unrelated reason, the caller must
+    // be told validation did not happen rather than handed a false pass.
+    it('reports a refusal, never `valid: true`, when a verb fails to compile', () => {
+      const su = new SchemaUtils();
+      su.getVerbNames();
+      // Reinstate the pre-fix condition: an Ajv instance with no placeholder
+      // registered for the unbundled external ref.
+      const internals = su as unknown as {
+        ajv: unknown;
+        verbValidators: Map<string, unknown>;
+        compileFailures: Map<string, string>;
+      };
+      internals.verbValidators.clear();
+      internals.compileFailures.clear();
+      internals.ajv = new AjvCtor({ allErrors: true, strict: false, logger: false });
+
+      const result = su.validateVerb('connect', {
+        to: 'sip:alice@example.com',
+        zzz_not_a_real_key: 1,
+      });
+      expect(result.valid).toBe(false);
+      expect(result.errors[0]).toContain('failed to compile');
+      expect(result.errors[0]).toContain('NOT validated');
+      expect(Object.keys(su.compileFailedVerbs)).toContain('connect');
+    });
+  });
+
   describe('SWML_SKIP_SCHEMA_VALIDATION', () => {
     it('skips validation when skipValidation is true', () => {
       const skipped = new SchemaUtils({ skipValidation: true });