@aloma.io/integration-sdk 3.8.67 → 3.8.68

package/test/harness.test.mjs

@@ -0,0 +1,375 @@
+// Tests for the connector test harness (src/testing) and, through it, the SDK's
+// handshake, dispatch and result-return paths. No test reaches the network:
+// the only sockets are on 127.0.0.1 and vendor HTTP is mocked.
+import http from 'node:http';
+import {describe, it, afterEach} from 'mocha';
+import {expect} from 'chai';
+import {Transport} from '../build/internal/websocket/transport/index.mjs';
+import {Connector} from '../build/internal/connector/index.mjs';
+import Fetcher from '../build/internal/fetcher/fetcher.mjs';
+import {ConnectorHarness, FakeAloma, VendorMock} from '../build/testing/index.mjs';
+
+const VENDOR = 'https://api.vendor.example.test';
+
+// A tiny connector, wired the way the SDK wires a connector repo's controller.
+function exampleConnector(seen = {}) {
+  const connector = new Connector({id: 'example-connector', version: '1.2.3', name: 'Example Connector'});
+
+  connector
+    .configure()
+    .config({
+      fields: {
+        apiKey: {name: 'API Key', type: 'line'},
+        region: {name: 'Region', type: 'line', plain: true},
+      },
+    })
+    .types('type Query { echo: String }')
+    .resolvers({
+      echo: async (args) => args,
+      shout: async ({text}) => String(text).toUpperCase(),
+      whoami: async (_args, ctx) => ({ctx}),
+      nested: {deep: {method: async () => ({found: true})}},
+      getItem: async ({id}) => {
+        const client = seen.getClient({
+          baseUrl: VENDOR,
+          retry: 1,
+          customize: (o) => {
+            o.headers = {...o.headers, Authorization: `Bearer ${seen.config.apiKey}`};
+          },
+        });
+        return client.fetch(`/items/${id}`, {method: 'GET'});
+      },
+      createItem: async (body) => {
+        const client = seen.getClient({baseUrl: VENDOR, retry: 1});
+        return client.fetch('/items', {method: 'POST', body});
+      },
+      forgottenMock: async () => new Fetcher({retry: 1}).fetch('https://not-mocked.example.test/x'),
+      rawSocket: async () =>
+        new Promise((resolve, reject) => {
+          http.get('http://203.0.113.9/', () => resolve({reached: true})).on('error', reject);
+        }),
+      boom: async () => {
+        throw new Error('kaput');
+      },
+      makeBlob: async () => ({id: await seen.createBlob({name: 'a.txt'})}),
+    })
+    .main((arg) => {
+      seen.config = arg.config;
+      seen.getClient = arg.getClient;
+      seen.createBlob = arg.createBlob;
+      seen.starts = (seen.starts || 0) + 1;
+    });
+
+  return connector;
+}
+
+describe('connector test harness', function () {
+  this.timeout(15000);
+
+  let harness;
+  let seen;
+  const realFetch = globalThis.fetch;
+
+  const start = async (extra = {}) => {
+    seen = {};
+    harness = await ConnectorHarness.start({
+      connector: exampleConnector(seen),
+      config: {apiKey: 'fake-api-key-not-real', region: 'eu-test'},
+      ...extra,
+    });
+    return harness;
+  };
+
+  afterEach(async () => {
+    if (harness) await harness.stop({verify: false});
+    harness = undefined;
+  });
+
+  describe('handshake', () => {
+    it('registers, connects and opens the websocket', async () => {
+      await start();
+      const {aloma} = harness;
+
+      expect(aloma.connected).to.equal(true);
+      expect(aloma.registrations).to.have.length(1);
+      expect(aloma.protocolErrors).to.deep.equal([]);
+      // first connect has no token and is told to register (401), the second carries the issued token
+      expect(aloma.connects.map((c) => c.authorized)).to.deep.equal([false, true]);
+    });
+
+    it('registers id, version, name, a public key and the schema', async () => {
+      await start();
+      const body = harness.aloma.registration;
+
+      expect(body.id).to.equal('example-connector');
+      expect(body.version).to.equal('1.2.3');
+      expect(body.name).to.equal('Example Connector');
+      expect(body.publicKey).to.be.a('string').with.length.greaterThan(100);
+      expect(body.schema.configSchema.fields).to.have.keys('apiKey', 'region');
+      expect(body.schema.introspect).to.equal('type Query { echo: String }');
+      expect(harness.aloma.connects[1].headers['user-agent']).to.equal('example-connector/1.2.3');
+    });
+
+    it('delivers encrypted config decrypted and plain config as is, then runs main() once', async () => {
+      await start();
+
+      expect(seen.config).to.deep.equal({apiKey: 'fake-api-key-not-real', region: 'eu-test'});
+      expect(seen.starts).to.equal(1);
+    });
+
+    it('answers connector.introspect with the schema and types', async () => {
+      await start();
+      const answer = await harness.aloma.introspect();
+
+      expect(answer.introspect).to.equal('type Query { echo: String }');
+      expect(answer.configSchema.fields.apiKey.name).to.equal('API Key');
+    });
+
+    it('can be started and stopped repeatedly without leaking state', async () => {
+      for (let i = 0; i < 3; i++) {
+        await start();
+        expect(await harness.call('shout', {text: 'x'})).to.deep.equal({shout: 'X'});
+        await harness.stop();
+        harness = undefined;
+      }
+      expect(globalThis.fetch).to.equal(realFetch);
+    });
+  });
+
+  describe('method calls', () => {
+    it('round-trips an object result unchanged', async () => {
+      await start();
+      expect(await harness.call('echo', {a: 1, b: ['x']})).to.deep.equal({a: 1, b: ['x']});
+    });
+
+    it('wraps a non-object result under the method name', async () => {
+      await start();
+      expect(await harness.call('shout', {text: 'hello'})).to.deep.equal({shout: 'HELLO'});
+    });
+
+    it('resolves nested methods addressed by a path array', async () => {
+      await start();
+      expect(await harness.call(['nested', 'deep', 'method'])).to.deep.equal({found: true});
+    });
+
+    it('forwards taskId, namespace and sticky as ctx', async () => {
+      await start();
+      const answer = await harness.call('whoami', {}, {taskId: 't-1', namespace: 'ns', sticky: true});
+
+      expect(answer.ctx).to.deep.equal({taskId: 't-1', namespace: 'ns', sticky: true});
+    });
+
+    it('answers concurrent calls independently', async () => {
+      await start();
+      const results = await Promise.all([1, 2, 3, 4, 5].map((n) => harness.call('echo', {n})));
+
+      expect(results.map((r) => r.n)).to.deep.equal([1, 2, 3, 4, 5]);
+    });
+
+    it('serves connector-initiated requests through the fake endpoint (blobs)', async () => {
+      await start();
+      harness.aloma.handle('connector.blob.create', (args) => (args.name === 'a.txt' ? {id: 'blob-1'} : {error: 'bad'}));
+
+      expect(await harness.call('makeBlob')).to.deep.equal({id: 'blob-1'});
+    });
+  });
+
+  describe('vendor HTTP mock', () => {
+    it('answers the connector vendor call from a recorded response', async () => {
+      await start();
+      harness.vendor.get(`${VENDOR}/items/7`, {json: {id: 7, name: 'recorded'}});
+
+      expect(await harness.call('getItem', {id: 7})).to.deep.equal({id: 7, name: 'recorded'});
+      expect(harness.vendor.requests).to.have.length(1);
+      expect(harness.vendor.requests[0].headers.authorization).to.equal('Bearer fake-api-key-not-real');
+    });
+
+    it('lets a responder function see the request body and choose the reply', async () => {
+      await start();
+      harness.vendor.post(`${VENDOR}/items`, (req) => ({status: 201, json: {created: JSON.parse(req.body)}}));
+
+      expect(await harness.call('createItem', {name: 'new'})).to.deep.equal({created: {name: 'new'}});
+    });
+
+    it('records the url the Fetcher really sends', async () => {
+      await start();
+      harness.vendor.get(`${VENDOR}/items/1`, {json: {}});
+      await harness.call('getItem', {id: 1});
+
+      // PINS SUSPECT BEHAVIOUR: Fetcher joins baseUrl + path and then collapses every run of slashes with
+      // .replace(/\/\/+/g, '/'), so "https://host" becomes "https:/host". Node's URL parser repairs
+      // this for http(s), but the same replace would also damage a "//" inside a query value.
+      expect(harness.vendor.requests[0].url).to.equal('https://api.vendor.example.test/items/1');
+      expect(harness.vendor.requests[0].rawUrl).to.equal('https:/api.vendor.example.test/items/1');
+    });
+
+    it('turns a vendor error status into a method error', async () => {
+      await start();
+      harness.vendor.get(/\/items\/9$/, {status: 404, text: 'no such item'});
+
+      const answer = await harness.call('getItem', {id: 9});
+      expect(answer.error).to.match(/404 no such item/);
+    });
+
+    it('rejects an unmocked request, reports it to the connector and fails the test on stop()', async () => {
+      await start();
+      const answer = await harness.call('forgottenMock');
+
+      expect(answer.error).to.match(/UNMOCKED vendor request: GET https:\/\/not-mocked\.example\.test\/x/);
+      expect(harness.vendor.unmocked).to.have.length(1);
+
+      let failure;
+      try {
+        await harness.stop();
+      } catch (e) {
+        failure = e;
+      }
+      harness = undefined;
+      expect(failure, 'stop() must fail when an unmocked request happened').to.be.instanceOf(Error);
+      expect(failure.message).to.match(/UNMOCKED vendor requests/);
+    });
+
+    it('blocks raw sockets to non-loopback hosts even when fetch is bypassed', async () => {
+      await start();
+      const answer = await harness.call('rawSocket');
+
+      expect(answer.error).to.match(/NETWORK BLOCKED/);
+    });
+
+    it('restores fetch and the network guard on stop()', async () => {
+      await start();
+      expect(globalThis.fetch).to.not.equal(realFetch);
+      await harness.stop();
+      harness = undefined;
+
+      expect(globalThis.fetch).to.equal(realFetch);
+    });
+
+    it('limits a route with times and can assert every route was used', async () => {
+      const vendor = new VendorMock();
+      vendor.get('https://a.example.test/x', {json: {n: 1}}, {times: 1});
+      vendor.get('https://b.example.test/never', {json: {}});
+      vendor.install();
+      try {
+        const first = await globalThis.fetch('https://a.example.test/x');
+        expect(await first.json()).to.deep.equal({n: 1});
+
+        let failure;
+        try {
+          await globalThis.fetch('https://a.example.test/x');
+        } catch (e) {
+          failure = e;
+        }
+        expect(failure && failure.message).to.match(/UNMOCKED/);
+        expect(() => vendor.verifyAllRoutesUsed()).to.throw(/never called/);
+        expect(() => vendor.verify()).to.throw(/UNMOCKED/);
+      } finally {
+        vendor.uninstall();
+      }
+    });
+  });
+
+  describe('failing connectors', () => {
+    it('reports a throwing method as an error answer and keeps serving', async () => {
+      await start();
+
+      expect(await harness.call('boom')).to.deep.equal({error: 'Error: kaput'});
+      expect(await harness.call('shout', {text: 'still up'})).to.deep.equal({shout: 'STILL UP'});
+    });
+
+    it('reports an unknown method as an error answer', async () => {
+      await start();
+      const answer = await harness.call('doesNotExist');
+
+      expect(answer.error).to.match(/doesNotExist not found/);
+    });
+
+    it('callOk() throws when the connector answered with an error', async () => {
+      await start();
+      let failure;
+      try {
+        await harness.callOk('boom');
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure.message).to.match(/boom failed: Error: kaput/);
+    });
+
+    it('fails start() with the cause when main() throws', async () => {
+      const connector = new Connector({id: 'broken-main', version: '0.0.1', name: 'Broken'});
+      connector
+        .configure()
+        .config({fields: {k: {name: 'K', type: 'line'}}})
+        .types('type Query { x: String }')
+        .resolvers({x: async () => 1})
+        .main(() => {
+          throw new Error('cannot start');
+        });
+
+      let failure;
+      try {
+        await ConnectorHarness.start({connector, config: {k: 'v'}});
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure && failure.message).to.equal('cannot start');
+    });
+  });
+
+  describe('pinned SDK behaviour', () => {
+    it('Transport.close() never terminates the websocket', () => {
+      // PINS SUSPECT BEHAVIOUR: Transport.close() calls local.ws.terminate(), but `local` is not defined in
+      // close() (it is only defined in the other methods). The ReferenceError is swallowed by the try/catch,
+      // so close() clears its timers and flags but leaves the socket open. Today a closed connector relies on
+      // the server side (or process exit) to drop the connection.
+      const transport = new Transport({config: {}, onMessage() {}, onConnect() {}});
+      let terminated = false;
+      transport.ws = {terminate: () => (terminated = true)};
+
+      transport.close();
+
+      expect(transport.running).to.equal(false);
+      expect(transport.connected).to.equal(false);
+      expect(terminated).to.equal(false);
+    });
+  });
+
+  describe('fake ALOMA strictness', () => {
+    let aloma;
+    afterEach(async () => aloma && (await aloma.close()));
+
+    it('refuses registration with a wrong registration token and records it', async () => {
+      aloma = await FakeAloma.start();
+      const response = await fetch(`${aloma.url}register`, {
+        method: 'POST',
+        body: '{}',
+        headers: {Authorization: 'Connector wrong-token'},
+      });
+
+      expect(response.status).to.equal(401);
+      expect(aloma.protocolErrors.join()).to.match(/wrong registration token/);
+    });
+
+    it('answers /connect with 401 until a token was issued by registering', async () => {
+      aloma = await FakeAloma.start();
+      const response = await fetch(`${aloma.url}connect`, {
+        method: 'POST',
+        body: '{}',
+        headers: {Authorization: 'Connector null'},
+      });
+
+      expect(response.status).to.equal(401);
+    });
+
+    it('times out with a diagnostic when no connector connects', async () => {
+      aloma = await FakeAloma.start();
+      let failure;
+      try {
+        await aloma.waitForConnection(50);
+      } catch (e) {
+        failure = e;
+      }
+      expect(failure.message).to.match(/did not connect within 50ms/);
+    });
+  });
+});

package/test/openapi-to-connector.test.mts

@@ -141,7 +141,9 @@ paths:
     it('should reject invalid JSON/YAML', () => {
       expect(() => {
         OpenAPIToConnector.parseSpec('invalid json {');
-      }).to.throw('Failed to parse OpenAPI spec');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'Failed to parse OpenAPI spec'.
+      // 'invalid json {' is not JSON, but js-yaml loads it as a plain string, so it is rejected by the schema check.
+      }).to.throw('Invalid OpenAPI 3.x specification');
     });
   });
 
@@ -152,9 +154,12 @@ paths:
       
       expect(controllerCode).to.include('import {AbstractController}');
       expect(controllerCode).to.include('export default class Controller extends AbstractController');
-      expect(controllerCode).to.include('async getUsers(args: any)');
-      expect(controllerCode).to.include('async createUser(args: any)');
-      expect(controllerCode).to.include('async get_users_{id}(args: any)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getUsers(args: any)',
+      // 'async createUser(args: any)' and 'async get_users_{id}(args: any)' (an older args-object signature; the
+      // third name never matched the spec's operationId getUserById, path params are now positional).
+      expect(controllerCode).to.include('async getUsers(options?: {headers?: Record<string, string>})');
+      expect(controllerCode).to.include('async createUser(options');
+      expect(controllerCode).to.include('async getUserById(id: string, options?: {headers?: Record<string, string>})');
     });
 
     it('should generate proper JSDoc comments', () => {
@@ -163,8 +168,20 @@ paths:
       
       expect(controllerCode).to.include('* Get all users');
       expect(controllerCode).to.include('* Retrieve a list of all users');
-      expect(controllerCode).to.include('* @param args.body - Request body');
-      expect(controllerCode).to.include('* @param args.id - User ID');
+      // PINS: expectation updated to today's output on 24 Oct; original expected '* @param args.body - Request body'
+      // and '* @param args.id - User ID' (older args-object JSDoc; the object body is now expanded into its properties).
+      expect(controllerCode).to.include('* @param {string} options.name (required)');
+      expect(controllerCode).to.include('* @param {string} id User ID');
+    });
+
+    it('should substitute path parameters into the url', () => {
+      // Added on 24 Oct with the entry-point fix: nothing asserted the generated path parameter handling before.
+      const generator = new OpenAPIToConnector(validOpenAPISpec, 'Test Connector');
+      const controllerCode = generator.generateController();
+
+      expect(controllerCode).to.include("let url = '/users/{id}';");
+      expect(controllerCode).to.include('if (id) {');
+      expect(controllerCode).to.include("url = url.replace('{id}', id);");
     });
 
     it('should handle operations without operationId', () => {
@@ -187,7 +204,8 @@ paths:
       const generator = new OpenAPIToConnector(specWithoutOperationId, 'Test Connector');
       const controllerCode = generator.generateController();
       
-      expect(controllerCode).to.include('async get_test(args: any)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async get_test(args: any)'.
+      expect(controllerCode).to.include('async get_test(options?: {headers?: Record<string, string>})');
     });
 
     it('should throw error for empty spec', () => {

package/test/scenarios.test.mts

@@ -44,8 +44,13 @@ describe('Scenario Tests - Full Code Generation', () => {
       const actualOutput = generator.generateController();
       
       // Verify methods without options don't have unnecessary code
-      expect(actualOutput).to.include('async getProducts() {'); // No options parameter
-      expect(actualOutput).to.not.include('options = options || {}'); // No options initialization for getProducts
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getProducts() {'.
+      // Since the headers type fix (f2d55a0, Bug C) every method takes an optional options with headers.
+      expect(actualOutput).to.include('async getProducts(options?: {headers?: Record<string, string>}) {');
+      // PINS: expectation updated to today's output on 24 Oct; original asserted this on the whole output, which also
+      // contains createProduct's (legitimate) initialization, so it is now scoped to the getProducts method only.
+      const getProductsBody = actualOutput.slice(actualOutput.indexOf('async getProducts('), actualOutput.indexOf('async createProduct('));
+      expect(getProductsBody).to.not.include('options = options || {}'); // No options initialization for getProducts
       expect(actualOutput).to.include('async createProduct(options:'); // Has options parameter
       expect(actualOutput).to.include('options = options || {};'); // Has options initialization for createProduct
     });
@@ -163,13 +168,15 @@ describe('Scenario Tests - Full Code Generation', () => {
       const actualOutput = generator.generateResourceClass('OrdersResource');
       
       // Verify path parameters are handled correctly
-      expect(actualOutput).to.include('export function getOrder(this: any, orderId: string)');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'getOrder(this: any, orderId: string)'
+      // and 'cancelOrder(this: any, orderId: string)' with no trailing options (stale since the headers type fix, Bug C).
+      expect(actualOutput).to.include('export function getOrder(this: any, orderId: string, options?: {headers?: Record<string, string>})');
       expect(actualOutput).to.include('export function updateOrderStatus(this: any, orderId: string, options');
-      expect(actualOutput).to.include('export function cancelOrder(this: any, orderId: string)');
+      expect(actualOutput).to.include('export function cancelOrder(this: any, orderId: string, options?: {headers?: Record<string, string>})');
       
       // Verify methods without options don't have unnecessary code
-      expect(actualOutput).to.match(/export function getOrder\(this: any, orderId: string\) \{/);
-      expect(actualOutput).to.match(/export function cancelOrder\(this: any, orderId: string\) \{/);
+      expect(actualOutput).to.match(/export function getOrder\(this: any, orderId: string, options\?: \{headers\?: Record<string, string>\}\) \{/);
+      expect(actualOutput).to.match(/export function cancelOrder\(this: any, orderId: string, options\?: \{headers\?: Record<string, string>\}\) \{/);
     });
 
     it('should correctly expose resource methods in main controller', () => {
@@ -278,7 +285,8 @@ describe('Scenario Tests - Full Code Generation', () => {
       const output = generator.generateController();
       
       // Should not have options parameter or initialization
-      expect(output).to.include('async getSimple() {');
+      // PINS: expectation updated to today's output on 24 Oct; original expected 'async getSimple() {' (stale since Bug C).
+      expect(output).to.include('async getSimple(options?: {headers?: Record<string, string>}) {');
       expect(output).to.not.include('options = options || {}');
       expect(output).to.not.include('headers: options');
     });

package/tools/mutation-run-entry.mjs

@@ -0,0 +1,52 @@
+// Mutation check for the SDK tests that `yarn test` now runs (openapi-to-connector generator tests, scenarios).
+//
+//   yarn build && node tools/mutation-run-entry.mjs
+//
+// Applies each single-point bug to src/openapi-to-connector.mts, rebuilds, runs `yarn test` and expects it to FAIL.
+// The source file is restored after every mutant (and on exit). Prints a markdown table.
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const file = path.join(root, 'src/openapi-to-connector.mts');
+const original = fs.readFileSync(file, 'utf8');
+const restore = () => fs.writeFileSync(file, original);
+process.on('exit', restore);
+process.on('SIGINT', () => process.exit(130));
+
+// [id, exact text (must occur once), replacement, bug]
+const MUTANTS = [
+  ['E01', "method: method.toUpperCase(),\n          path,", "method: method.toLowerCase(),\n          path,", 'the HTTP verb is taken in lower case'],
+  ['E02', "lines.push(`    if (${paramName}) {`);\n        lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);\n        lines.push(`    }`);\n      }", "lines.push(`    if (!${paramName}) {`);\n        lines.push(`      url = url.replace('{${paramName}}', ${paramName});`);\n        lines.push(`    }`);\n      }", 'path parameter substitution is guarded by the wrong condition'],
+  ['E03', "return `${methodPrefix}_${pathSuffix}`;", "return `${methodPrefix}${pathSuffix}`;", 'fallback method name drops the separator'],
+  ['E04', "const requiredText = propRequired ? '(required)' : '(optional)';", "const requiredText = propRequired ? '(optional)' : '(required)';", 'body properties are documented with the wrong required flag'],
+  ['E05', "    // Always include headers in options type (generated code references options.headers)\n    optionProps.push('headers?: Record<string, string>');", "    // Always include headers in options type (generated code references options.headers)", 'headers are dropped from the generated options type'],
+  ['E06', "lines.push(`    options = options || {};`);", "lines.push(`    // no options default`);", 'options is not defaulted in generated methods'],
+  ['E07', "if (criticalErrors.length > 0) {", "if (false) {", 'invalid specs are no longer rejected'],
+  ['E08', "const propRequired = (schema.required && schema.required.includes(propName)) || requestBody.required;", "const propRequired = (schema.required && schema.required.includes(propName)) && requestBody.required;", 'a property is required only if both the schema and the body say so'],
+];
+
+const sh = (args) => spawnSync('npx', ['--yes', 'yarn@1.22.22', '-s', ...args], {cwd: root, encoding: 'utf8'});
+const rows = [];
+let survived = 0;
+for (const [id, find, repl, bug] of MUTANTS) {
+  const n = original.split(find).length - 1;
+  if (n !== 1) { console.error(`${id}: pattern occurs ${n} times, expected 1`); process.exit(2); }
+  fs.writeFileSync(file, original.replace(find, repl));
+  const b = sh(['build']);
+  let result;
+  if (b.status !== 0) result = 'build failed (not counted)';
+  else {
+    const t = sh(['test']);
+    result = t.status !== 0 ? 'killed' : 'SURVIVED';
+    if (t.status === 0) survived++;
+  }
+  restore();
+  rows.push(`| ${id} | ${bug} | ${result} |`);
+  console.log(rows.at(-1));
+}
+sh(['build']);
+console.log(`\n${MUTANTS.length - survived}/${MUTANTS.length} killed`);
+process.exit(survived ? 1 : 0);

package/tools/mutation-run.mjs

@@ -0,0 +1,120 @@
+// Mutation check for the connector test harness.
+//
+//   yarn build && yarn test:mutation
+//
+// Applies each deliberate single-point bug below to src/, rebuilds, runs the harness tests and expects them
+// to FAIL. The original file is restored after every mutant (and on Ctrl-C). Writes test/MUTATION.md.
+// Not part of CI: it rebuilds the SDK ~30 times. Run it when the harness or the SDK paths it covers change.
+import {spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const src = (p) => path.join(root, 'src', p);
+
+// [id, area, file (under src/), exact text to find (must occur once), replacement, what the bug is]
+const MUTANTS = [
+  ['M01', 'sdk handshake', 'internal/websocket/connection/index.mjs', 'response.status === 401', 'response.status === 403', 'a 401 from /connect no longer triggers registration'],
+  ['M02', 'sdk handshake', 'internal/websocket/connection/index.mjs', 'config.setToken(await new Registration(local.config).run());', 'await new Registration(local.config).run();', 'the token from registration is not stored'],
+  ['M03', 'sdk handshake', 'internal/websocket/connection/registration.mjs', 'return (await response.json()).key;', 'return (await response.json()).token;', 'registration reads the wrong field of the answer'],
+  ['M04', 'sdk handshake', 'internal/websocket/connection/registration.mjs', 'id: config.id(),', 'id: config.name(),', 'registration sends the name as the connector id'],
+  ['M05', 'sdk handshake', 'internal/websocket/connection/registration.mjs', 'publicKey: config.publicKey(),', 'publicKey: undefined,', 'registration omits the public key'],
+  ['M06', 'sdk handshake', 'internal/websocket/connection/constants.mjs', "'User-Agent': config.id() + '/' + config.version(),\n    };\n\n    what.headers[AUTHORIZATION] = `Connector ${config.token()}`;", "'User-Agent': config.id(),\n    };\n\n    what.headers[AUTHORIZATION] = `Connector ${config.token()}`;", 'authenticated requests drop the version from the User-Agent'],
+  ['M07', 'sdk handshake', 'internal/websocket/connection/constants.mjs', 'what.headers[AUTHORIZATION] = `Connector ${config.token()}`;', 'what.headers[AUTHORIZATION] = `Bearer ${config.token()}`;', 'wrong authorization scheme for the session token'],
+  ['M08', 'sdk handshake', 'internal/websocket/transport/index.mjs', "config.wsUrl(), ['connector']", 'config.wsUrl(), []', 'websocket opened without the "connector" subprotocol'],
+  ['M09', 'sdk transport', 'internal/websocket/transport/index.mjs', 'msgs.p?.forEach((item) => {', 'msgs.p?.slice(1).forEach((item) => {', 'the first packet of every incoming frame is dropped'],
+  ['M10', 'sdk transport', 'internal/websocket/transport/index.mjs', 'local.ws.send(JSON.stringify({p: packets}));', 'local.ws.send(JSON.stringify({packets}));', 'outgoing frames use the wrong envelope'],
+  ['M11', 'sdk transport', 'internal/websocket/transport/index.mjs', 'if (packet.cb() && this.callbacks[packet.cb()]) {', 'if (false && packet.cb() && this.callbacks[packet.cb()]) {', 'answers to connector-initiated requests are never routed to their callback'],
+  ['M12', 'sdk dispatch', 'internal/dispatcher/index.mts', 'case \'connector.set-config\':\n          await local.onConfig({...packet.args().secrets});', 'case \'connector.set-config\':\n          await local.onConfig({});', 'configuration secrets are dropped before onConfig'],
+  ['M13', 'sdk dispatch', 'internal/dispatcher/index.mts', 'const ctx = {taskId, namespace, sticky};', 'const ctx = {taskId, namespace};', 'sticky is not forwarded to the method'],
+  ['M14', 'sdk dispatch', 'internal/dispatcher/index.mts', 'if (!method && !_resolvers.__default) throw new Error(`${originalQuery} not found`);', 'if (false) throw new Error(`${originalQuery} not found`);', 'unknown methods are no longer reported as "not found"'],
+  ['M15', 'sdk result return', 'internal/dispatcher/index.mts', 'return typeof ret === \'object\' && !Array.isArray(ret) ? ret : {[packet.args().query]: ret};', 'return typeof ret === \'object\' && !Array.isArray(ret) ? ret : {result: ret};', 'scalar results are wrapped under the wrong key'],
+  ['M16', 'sdk result return', 'internal/util/index.mts', 'transport.send(transport.newPacket({c: packet.cb(), a: {...arg}}));', 'transport.send(transport.newPacket({c: packet.cb(), a: {}}));', 'successful results are replied empty'],
+  ['M17', 'sdk result return', 'internal/util/index.mts', "a: {error: '' + e}", "a: {error: 'failed'}", 'errors lose their message'],
+  ['M18', 'sdk result return', 'internal/connector/server/on-message.mts', 'if (ret) reply(ret, packet, transport);', 'if (false) reply(ret, packet, transport);', 'results are never sent back'],
+  ['M19', 'sdk config', 'internal/connector/server/on-connect/decrypt-config.mts', 'jwe.decrypt(value, config.id())', "jwe.decrypt(value, 'other-audience')", 'config is decrypted for the wrong audience'],
+  ['M20', 'sdk config', 'internal/connector/server/on-connect/decrypt-config.mts', 'if (fields[key]?.plain ||', 'if (false ||', 'plain fields are decrypted like secrets'],
+  ['M21', 'sdk config', 'internal/connector/server/on-connect/index.mts', 'config: decrypted,\n        oauth: theOAuth,', 'config: {},\n        oauth: theOAuth,', 'main() receives an empty config'],
+  ['M22', 'harness vendor mock', 'testing/vendor-mock.mts', 'error.alomaHarnessUnmocked = true;\n    throw error;', 'error.alomaHarnessUnmocked = true;\n    return new Response(\'{}\');', 'an unmocked request is answered instead of rejected'],
+  ['M23', 'harness vendor mock', 'testing/vendor-mock.mts', 'if (this.unmocked.length) {', 'if (false) {', 'verify() never fails'],
+  ['M24', 'harness vendor mock', 'testing/vendor-mock.mts', 'const status = spec.status ?? 200;', 'const status = 200;', 'mocked status codes are ignored'],
+  ['M25', 'harness vendor mock', 'testing/vendor-mock.mts', 'r.used < r.times && ', '', 'the times limit on a route is ignored'],
+  ['M26', 'harness network guard', 'testing/network-guard.mts', 'if (!local && !LOOPBACK.has(host)) {', 'if (false) {', 'the network guard lets everything through (the mutant may try one TCP connect to the TEST-NET-3 documentation address 203.0.113.9)'],
+  ['M27', 'harness fake ALOMA', 'testing/fake-aloma.mts', 'const authorized = auth === `Connector ${this.sessionToken}`;', 'const authorized = true;', 'the fake accepts a connect without registration'],
+  ['M28', 'harness fake ALOMA', 'testing/fake-aloma.mts', '.setAudience(this.id)', ".setAudience('wrong')", 'the fake encrypts config for the wrong audience'],
+  ['M29', 'harness fake ALOMA', 'testing/fake-aloma.mts', '      done(packet.a);', '      done(undefined);', 'the fake drops the connector\'s answer'],
+  ['M30', 'harness fake ALOMA', 'testing/fake-aloma.mts', "{query: method, variables, ...ctx}", "{query: method, variables}", 'call() drops the ctx fields'],
+  ['M31', 'harness', 'testing/harness.mts', 'this.vendor.verify();', '', 'stop() no longer fails on unmocked requests'],
+  ['M32', 'harness', 'testing/harness.mts', "await aloma.setConfig(options.config || {});", "", 'the harness never sends configuration'],
+];
+
+const run = (cmd, args, timeout) =>
+  spawnSync(cmd, args, {cwd: root, encoding: 'utf8', timeout, env: {...process.env, FORCE_COLOR: '0'}});
+
+const build = () => {
+  const r = run('node', ['./node_modules/typescript/bin/tsc'], 120000);
+  if (r.status !== 0) throw new Error('build failed:\n' + r.stdout + r.stderr);
+};
+const mocha = () => run('node', ['./node_modules/mocha/bin/_mocha', '--bail', '--exit', 'test/harness.test.mjs', 'test/harness-connector-smoke.test.mjs'], 150000);
+
+let current = null;
+const restore = () => {
+  if (current) fs.writeFileSync(current.file, current.original);
+  current = null;
+};
+process.on('SIGINT', () => {
+  restore();
+  process.exit(130);
+});
+
+const results = [];
+try {
+  build();
+  const baseline = mocha();
+  if (baseline.status !== 0) throw new Error('baseline run must pass before mutating:\n' + baseline.stdout.slice(-2000));
+
+  for (const [id, area, rel, find, replace, bug] of MUTANTS) {
+    const file = src(rel);
+    const original = fs.readFileSync(file, 'utf8');
+    const count = original.split(find).length - 1;
+    if (count !== 1) throw new Error(`${id}: expected exactly one match in ${rel}, found ${count}`);
+
+    current = {file, original};
+    let outcome;
+    try {
+      fs.writeFileSync(file, original.replace(find, () => replace));
+      build();
+      const r = mocha();
+      const failing = (r.stdout.match(/^\s+\d+\) .+$/gm) || [])[0]?.trim() || '';
+      outcome = r.error?.code === 'ETIMEDOUT' ? 'killed (timeout)' : r.status !== 0 ? 'killed' : 'SURVIVED';
+      results.push({id, area, rel, bug, outcome, by: failing});
+    } finally {
+      restore();
+    }
+    console.log(id, results[results.length - 1].outcome, '-', bug);
+  }
+} finally {
+  restore();
+  build();
+}
+
+const killed = results.filter((r) => r.outcome.startsWith('killed')).length;
+const md = [
+  '# Mutation check for the connector test harness',
+  '',
+  `Result: **${killed}/${results.length} mutants killed**${killed === results.length ? '' : ' (survivors listed below)'}.`,
+  '',
+  'Each row is one deliberate single-point bug in the SDK code paths the harness exercises (handshake, transport,',
+  'dispatch, result return, config) or in the harness itself. `tools/mutation-run.mjs` applies it to `src/`, rebuilds,',
+  'runs `test/harness.test.mjs` with `--bail`, expects a failure, and restores the file. Re-run with',
+  '`yarn build && yarn test:mutation` after changing the harness or those SDK paths.',
+  '',
+  '| # | Area | File | Bug | Result |',
+  '|---|------|------|-----|--------|',
+  ...results.map((r) => `| ${r.id} | ${r.area} | \`src/${r.rel}\` | ${r.bug} | ${r.outcome} |`),
+  '',
+].join('\n');
+fs.writeFileSync(path.join(root, 'test', 'MUTATION.md'), md);
+console.log(`\n${killed}/${results.length} killed`);
+process.exit(killed === results.length ? 0 : 1);