@volter/twin-standard 1.0.30 → 1.0.31

package/src/clients/openai-compatible.ts

@@ -0,0 +1,59 @@
+// The chat cases every vendor whose chat API is OpenAI's wire holds, driven by openai-node pointed at the vendor (as an
+// application using the OpenAI SDK with that vendor's base URL does): a turn answered with the World's scenario loaded,
+// `tool_choice: none` answered with a message, the scenario rewritten between two turns deciding the second.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
+const TOOLS = [{ type: 'function' as const, function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
+const SCRIPT = { handlers: [
+  { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+  { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
+] };
+
+/** A vendor's chat as openai-node reaches it: the variable its key is issued in, the base URL on its host, a model it serves. */
+export type Compatible = { key: string; base: (host: string) => string; model: string };
+
+export async function openaiClient(c: ClientContext, v: Compatible) {
+  const { default: OpenAI } = await import('openai');
+  return new OpenAI({ apiKey: c.env[v.key] ?? '', baseURL: v.base(c.host), fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+}
+
+export function chatCases(v: Compatible): ClientCase[] {
+  const ask = async (c: ClientContext, extra: Record<string, unknown> = {}) => (await openaiClient(c, v)).chat.completions.create({ model: v.model, messages: [{ role: 'user', content: 'hello' }], ...extra } as never) as Promise<{ choices?: Array<{ message?: { content?: string | null; tool_calls?: unknown[] } }> }>;
+  return [
+    {
+      id: 'chat-answers',
+      asks: "a chat completion is answered, the World's scenario loaded",
+      source: `${CHAT} "Creates a model response for the given chat conversation."`,
+      async run(c) {
+        c.scenario(SCRIPT);
+        const answer = await ask(c).catch((e: Error) => e);
+        if (answer instanceof Error) return [`the client's chat.completions.create failed: ${answer.message}`];
+        return answer.choices?.[0]?.message?.content === 'scripted words' ? [] : [`the scripted turn was not answered: ${JSON.stringify(answer.choices?.[0]?.message).slice(0, 120)}`];
+      },
+    },
+    {
+      id: 'chat-tool-choice-none',
+      asks: 'tool_choice none is answered with a message, never a tool call',
+      source: `${CHAT} "none means the model will not call any tool and instead generates a message."`,
+      async run(c) {
+        c.scenario(SCRIPT);
+        const none = await ask(c, { tools: TOOLS, tool_choice: 'none' }).catch((e: Error) => e);
+        if (none instanceof Error) return [`the client's chat.completions.create failed: ${none.message}`];
+        return none.choices?.[0]?.message?.tool_calls?.length ? ['tool_choice none was answered with a tool call'] : [];
+      },
+    },
+    {
+      id: 'scenario-each-turn',
+      asks: "the World's scenario rewritten between two turns decides the second (no reboot)",
+      source: 'architecture "The scenario is read from the World\'s store at every turn"',
+      async run(c) {
+        c.scenario({ handlers: [{ id: 'one', on: { userTextIncludes: 'hello' }, respond: { text: 'first script' } }] });
+        const first = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e: Error) => `error ${e.message}`);
+        c.scenario({ handlers: [{ id: 'two', on: { userTextIncludes: 'hello' }, respond: { text: 'second script' } }] });
+        const second = await ask(c).then((a) => a.choices?.[0]?.message?.content, (e: Error) => `error ${e.message}`);
+        return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
+      },
+    },
+  ];
+}

package/src/clients/openai.ts

@@ -0,0 +1,66 @@
+// OpenAI's own client (openai-node), driving the openai pack as an application does. Each case is what OpenAI documents;
+// the World's scenario scripts the turns a model would take.
+import type { ClientCase, ClientContext } from './harness.ts';
+import { chatCases } from './openai-compatible.ts';
+
+const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
+const REALTIME = 'https://developers.openai.com/api/reference/resources/realtime/server-events';
+
+async function client(c: ClientContext) {
+  const { default: OpenAI } = await import('openai');
+  return new OpenAI({ apiKey: c.env.OPENAI_API_KEY ?? '', baseURL: `https://${c.host}/v1`, fetch: c.fetch, maxRetries: 0, timeout: 10_000 });
+}
+const TOOLS = [{ type: 'function' as const, function: { name: 'lookup', parameters: { type: 'object', properties: {} } } }];
+// a turn that calls the tool wherever one is offered, and one that answers in words
+const SCRIPT = { handlers: [
+  { id: 'calls', on: { hasTool: 'lookup' }, respond: { toolCalls: [{ name: 'lookup', arguments: {} }] } },
+  { id: 'words', on: { userTextIncludes: 'hello' }, respond: { text: 'scripted words' } },
+] };
+
+/** A Realtime session through the client (openai-node's server-side Realtime client, on the ws library, as a Node
+ *  application opens it), until its response is done: its first event and the output items' types, or what went wrong. */
+async function realtimeTurn(c: ClientContext, toolChoice: 'auto' | 'none'): Promise<{ first?: string; output?: string[]; error?: string }> {
+  const { OpenAIRealtimeWS } = await import('openai/realtime/ws');
+  const openai = await client(c);
+  return new Promise((done) => {
+    const rt = new OpenAIRealtimeWS({ model: 'gpt-realtime', options: { createConnection: c.connect } as never }, openai);
+    let first: string | undefined;
+    const timer = setTimeout(() => { rt.close(); done({ first, error: 'no response.done in 10 s' }); }, 10_000);
+    rt.on('error', (e) => { clearTimeout(timer); rt.close(); done({ first, error: String((e as Error).message ?? e) }); });
+    rt.socket.on('open', () => {
+      rt.send({ type: 'session.update', session: { type: 'realtime', output_modalities: ['text'], tools: [{ type: 'function', name: 'lookup', parameters: { type: 'object', properties: {} } }], tool_choice: toolChoice } } as never);
+      rt.send({ type: 'conversation.item.create', item: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'hello' }] } } as never);
+      rt.send({ type: 'response.create' } as never);
+    });
+    rt.on('event', (e: { type: string; response?: { output?: Array<{ type: string }> } }) => {
+      first ??= e.type;
+      if (e.type === 'response.done') { clearTimeout(timer); rt.close(); done({ first, output: (e.response?.output ?? []).map((o) => o.type) }); }
+    });
+  });
+}
+
+export const cases: ClientCase[] = [
+  ...chatCases({ key: 'OPENAI_API_KEY', base: (host) => `https://${host}/v1`, model: 'gpt-4o' }),
+  {
+    id: 'realtime-connects',
+    asks: 'a Realtime connection opens and its first event is session.created',
+    source: `${REALTIME} "Emitted automatically when a new connection is established as the first server event."`,
+    async run(c) {
+      c.scenario(SCRIPT);
+      const turn = await realtimeTurn(c, 'auto');
+      if (turn.error && !turn.first) return [`the client's Realtime connection failed: ${turn.error}`];
+      return turn.first === 'session.created' ? [] : [`the first server event was ${turn.first ?? 'none'}`];
+    },
+  },
+  {
+    id: 'realtime-tool-choice-none',
+    asks: "a Realtime response under tool_choice none carries no function call",
+    source: `${CHAT} "none means the model will not call any tool and instead generates a message."`,
+    async run(c) {
+      c.scenario(SCRIPT);
+      const turn = await realtimeTurn(c, 'none');
+      if (turn.error) return [`the Realtime turn failed: ${turn.error}`];
+      return turn.output?.includes('function_call') ? ['tool_choice none was answered with a function_call item'] : [];
+    },
+  },
+];

package/src/clients/openrouter.ts

@@ -0,0 +1,4 @@
+// OpenRouter's chat through openai-node (its OpenAI-compatible API), the shared chat cases.
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = chatCases({ key: 'OPENROUTER_API_KEY', base: (host) => `https://${host}/api/v1`, model: 'openai/gpt-4o' });

package/src/clients/perplexity.ts

@@ -0,0 +1,4 @@
+// Perplexity's chat through openai-node (its OpenAI-compatible API), the shared chat cases.
+import { chatCases } from './openai-compatible.ts';
+
+export const cases = chatCases({ key: 'PERPLEXITY_API_KEY', base: (host) => `https://${host}`, model: 'test-model' });

package/src/clients/planetscale.ts

@@ -0,0 +1,98 @@
+// PlanetScale's own driver (@planetscale/database, at the version Dub and Substrate pin), driving the planetscale pack as
+// its applications do, with the connection string the pack's credential door issued (PLANETSCALE_DATABASE_URL): Dub's
+// connection sends SQL with `?` parameters and reads typed rows; Prisma's PlanetScale adapter (Dub's edge client and the
+// client the World's injector gives Dub's PrismaClient, Substrate's Prisma client in a tab) reads rows as arrays, runs an
+// interactive transaction through the driver's `transaction`, and reads MySQL's errno and sqlstate out of a
+// `DatabaseError`'s message (`(errno 1062) (sqlstate 23000)` is Prisma's unique-constraint violation).
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const DRIVER = 'https://planetscale.com/docs/tutorials/planetscale-serverless-driver';
+const README = 'https://github.com/planetscale/database-js';
+const ERRORS = 'https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html';
+
+type Connection = {
+  execute: (query: string, args?: unknown, options?: { as?: 'object' | 'array' }) => Promise<{ rows: unknown[]; types: Record<string, string>; rowsAffected: number; insertId: string; statement: string }>;
+  transaction: <T>(fn: (tx: { execute: Connection['execute'] }) => Promise<T>) => Promise<T>;
+};
+
+/** A connection as Dub's lib/planetscale/connection.ts makes one: `connect({ url })`, here with the World's fetch. */
+async function connection(c: ClientContext): Promise<Connection> {
+  const { connect } = (await import('@planetscale/database')) as unknown as { connect: (config: { url?: string; fetch?: typeof fetch }) => Connection };
+  return connect({ url: c.env.PLANETSCALE_DATABASE_URL, fetch: c.fetch });
+}
+
+export const cases: ClientCase[] = [
+  {
+    id: 'parameters-and-types',
+    asks: "SQL sent with ? parameters, each replaced by its value, and the rows read back as the column's JavaScript type, as objects and as arrays",
+    source: `${DRIVER} "The driver package will replace the ? entries in the query with the values passed in the array, in the order in which they were placed."; ${README} "Column values are converted to their corresponding JavaScript data types."; ${README} "Rows can be returned as an object or an array of column values by passing an as option to execute ."`,
+    async run(c) {
+      try {
+        if (!c.env.PLANETSCALE_DATABASE_URL) return ['the credential door issued no PLANETSCALE_DATABASE_URL'];
+        const conn = await connection(c);
+        await conn.execute('CREATE TABLE hotels (id INT UNSIGNED NOT NULL AUTO_INCREMENT, name VARCHAR(100) NOT NULL, address VARCHAR(200) NOT NULL, stars FLOAT NOT NULL, PRIMARY KEY (id))');
+        const out: string[] = [];
+        const inserted = await conn.execute('INSERT INTO hotels (`name`, `address`, `stars`) VALUES (?, ?, ?)', ['The Galt House', '140 N Fourth St, Louisville, KY 40202', 4.2]);
+        if (inserted.rowsAffected !== 1) out.push(`the insert affected ${inserted.rowsAffected} rows, not 1`);
+        if (inserted.insertId !== '1') out.push(`the insert's id is ${JSON.stringify(inserted.insertId)}, not "1"`);
+        if (!inserted.statement.includes("'The Galt House'")) out.push(`the statement sent was ${JSON.stringify(inserted.statement)}`);
+        const read = await conn.execute('SELECT id, name, stars FROM hotels WHERE name = ?', ['The Galt House']);
+        const row = read.rows[0] as Record<string, unknown> | undefined;
+        if (!row) return [...out, 'the hotel inserted was not read back'];
+        if (row.id !== 1) out.push(`its id read back as ${JSON.stringify(row.id)}, not the number 1`);
+        if (row.name !== 'The Galt House') out.push(`its name read back as ${JSON.stringify(row.name)}`);
+        if (row.stars !== 4.2) out.push(`its stars read back as ${JSON.stringify(row.stars)} (${read.types.stars}), not the number 4.2`);
+        if (read.types.id !== 'UINT32') out.push(`its id's type is ${String(read.types.id)}, not UINT32`);
+        const arrays = await conn.execute('SELECT id, name FROM hotels', null, { as: 'array' });
+        if (JSON.stringify(arrays.rows) !== JSON.stringify([[1, 'The Galt House']])) out.push(`as arrays the rows are ${JSON.stringify(arrays.rows)}`);
+        return out;
+      } catch (e) { return [`the driver's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'transaction-rolls-back',
+    asks: 'a transaction whose callback returns is committed, and one whose callback throws is rolled back, its writes gone',
+    source: `${README} "Use the transaction function to safely perform database transactions. If any unhandled errors are thrown during execution of the transaction, the transaction will be rolled back."`,
+    async run(c) {
+      try {
+        if (!c.env.PLANETSCALE_DATABASE_URL) return ['the credential door issued no PLANETSCALE_DATABASE_URL'];
+        const conn = await connection(c);
+        await conn.execute('CREATE TABLE slotted_counters (record_type VARCHAR(40) NOT NULL, record_id INT NOT NULL, count INT NOT NULL, PRIMARY KEY (record_type, record_id))');
+        await conn.transaction(async (tx) => {
+          await tx.execute("INSERT INTO slotted_counters (record_type, record_id, count) VALUES ('branch_count', 42, 1)");
+          await tx.execute("INSERT INTO slotted_counters (record_type, record_id, count) VALUES ('branch_count', 43, 1)");
+        });
+        const refused = new Error('the second branch was refused');
+        const raised = await conn.transaction(async (tx) => {
+          await tx.execute("UPDATE slotted_counters SET count = count + 1 WHERE record_id = 42");
+          throw refused;
+        }).then(() => undefined, (e: unknown) => e);
+        const out: string[] = [];
+        if (raised !== refused) out.push(`the failed transaction raised ${String((raised as Error | undefined)?.message)}, not its callback's error`);
+        const after = await conn.execute('SELECT record_id, count FROM slotted_counters ORDER BY record_id');
+        if (JSON.stringify(after.rows) !== JSON.stringify([{ record_id: 42, count: 1 }, { record_id: 43, count: 1 }])) out.push(`after a commit and a rollback the counters are ${JSON.stringify(after.rows)}, not both at 1`);
+        return out;
+      } catch (e) { return [`the driver's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+  {
+    id: 'duplicate-key-raises',
+    asks: "inserting a primary key the table holds raises the driver's DatabaseError, its message ending in MySQL's errno and sqlstate, (errno 1062) (sqlstate 23000)",
+    source: `${ERRORS} "ER_DUP_ENTRY"; ${ERRORS} "Duplicate entry '%s' for key '%s'"`,
+    async run(c) {
+      try {
+        if (!c.env.PLANETSCALE_DATABASE_URL) return ['the credential door issued no PLANETSCALE_DATABASE_URL'];
+        const conn = await connection(c);
+        await conn.execute('CREATE TABLE links (domain VARCHAR(190) NOT NULL, `key` VARCHAR(190) NOT NULL, PRIMARY KEY (domain, `key`))');
+        await conn.execute('INSERT INTO links (domain, `key`) VALUES (?, ?)', ['go.trailmark.io', 'pricing']);
+        const raised = await conn.execute('INSERT INTO links (domain, `key`) VALUES (?, ?)', ['go.trailmark.io', 'pricing'])
+          .then(() => undefined, (e: unknown) => e as { name?: string; message?: string });
+        if (!raised) return ['inserting the same key twice succeeded'];
+        const out: string[] = [];
+        if (raised.name !== 'DatabaseError') out.push(`it raised ${String(raised.name)}, not the driver's DatabaseError`);
+        if (!/ \(errno 1062\) \(sqlstate 23000\)$/.test(String(raised.message))) out.push(`its message is ${JSON.stringify(raised.message)}, not MySQL's errno 1062 and sqlstate 23000`);
+        return out;
+      } catch (e) { return [`the driver's calls failed: ${(e as Error).name}: ${(e as Error).message}`]; }
+    },
+  },
+];

package/src/clients/posthog.ts

@@ -0,0 +1,132 @@
+// Official posthog-node 5.46.1 and @posthog/core 1.45.1, the versions Rallly pins.
+// The client's fetch option keeps every forwarded request on the World's proxy.
+import type { ClientCase, ClientContext } from './harness.ts';
+
+const NODE = 'https://posthog.com/docs/libraries/node';
+const CORE = 'https://unpkg.com/@posthog/core@1.45.1/src/posthog-core-stateless.ts';
+const IDENTIFY = 'https://posthog.com/docs/product-analytics/person-properties';
+
+async function client(c: ClientContext, options: { key?: string; fetch?: typeof fetch; flushAt?: number } = {}) {
+  const { PostHog } = await import('posthog-node');
+  return new PostHog(options.key ?? c.env.POSTHOG_KEY ?? '', {
+    host: 'https://' + c.host, fetch: options.fetch ?? c.fetch, flushAt: options.flushAt ?? 100,
+    flushInterval: 0, fetchRetryCount: 2, fetchRetryDelay: 1, requestTimeout: 10_000,
+  });
+}
+async function read(c: ClientContext, resource: string, query = ''): Promise<Record<string, any>> {
+  const response = await c.fetch((c.env.POSTHOG_API_HOST || 'https://us.posthog.com') + '/api/projects/' + c.env.POSTHOG_PROJECT_ID + '/' + resource + '/' + query, {
+    headers: { authorization: 'Bearer ' + c.env.POSTHOG_PERSONAL_API_KEY },
+  });
+  if (!response.ok) throw new Error(resource + ' readback answered ' + response.status + ': ' + await response.text());
+  return await response.json() as Record<string, any>;
+}
+export const cases: ClientCase[] = [
+  {
+    id: 'queued-captures-and-groups-drained-on-shutdown',
+    asks: 'shutdown drains queued captures and groupIdentify into a compressed batch; events and group properties read back',
+    source: NODE + ' "which can be awaited to ensure all queued events are sent to the API"',
+    async run(c) {
+      const requests: Request[] = [];
+      const forwarded = (async (url: Parameters<typeof fetch>[0], init?: RequestInit) => {
+        const request = new Request(url, init);
+        if (request.method === 'POST') requests.push(request.clone());
+        return c.fetch(request);
+      }) as typeof fetch;
+      const sdk = await client(c, { fetch: forwarded });
+      sdk.groupIdentify({ groupType: 'organization', groupKey: 'sdk-harbourline', distinctId: 'sdk-manager', properties: { name: 'Harbourline SDK case' } });
+      sdk.capture({ distinctId: 'sdk-manager', event: 'sdk_meeting_started', properties: { meeting: 'morning' }, groups: { organization: 'sdk-harbourline' } });
+      sdk.capture({ distinctId: 'sdk-manager', event: 'sdk_meeting_finished', properties: { meeting: 'morning' }, groups: { organization: 'sdk-harbourline' } });
+      await sdk.shutdown();
+      const failures: string[] = [];
+      if (requests.length !== 1 || !new URL(requests[0]!.url).pathname.startsWith('/batch')) failures.push('three queued calls did not drain as one batch');
+      if (requests[0]?.headers.get('content-encoding') !== 'gzip') failures.push('the default Node transport did not send gzip');
+      const events = await read(c, 'events', '?distinct_id=sdk-manager');
+      for (const event of ['sdk_meeting_started', 'sdk_meeting_finished']) {
+        const row = events.results.find((r: any) => r.event === event);
+        if (!row || row.properties.meeting !== 'morning' || row.properties.$groups.organization !== 'sdk-harbourline') failures.push(event + ' lost its properties or group link');
+      }
+      const types = await read(c, 'groups_types');
+      const groupType = (Array.isArray(types) ? types : types.results).find((r: any) => r.group_type === 'organization');
+      if (!groupType) failures.push('groupIdentify made no group type');
+      else {
+        const groups = await read(c, 'groups', '?group_type_index=' + groupType.group_type_index + '&group_key=sdk-harbourline');
+        if (groups.results[0]?.group_properties.name !== 'Harbourline SDK case') failures.push('groupIdentify lost the group properties');
+      }
+      return failures;
+    },
+  },
+  {
+    id: 'identify-alias-and-person-properties',
+    asks: 'alias links an anonymous ID; set_once preserves its first value and unset removes the named profile property',
+    source: IDENTIFY + ' "set_once only sets the property if it has never been set before."',
+    async run(c) {
+      const sdk = await client(c);
+      sdk.capture({ distinctId: 'sdk-anonymous', event: 'sdk_pageview', properties: { $set: { source: 'invite' } } });
+      sdk.alias({ distinctId: 'sdk-member', alias: 'sdk-anonymous' });
+      sdk.identify({ distinctId: 'sdk-member', properties: { email: 'sdk@harbourline.test' } });
+      sdk.setPersonProperties({ distinctId: 'sdk-member', properties: { plan: 'trial' }, propertiesOnce: { first_plan: 'trial' } });
+      sdk.setPersonProperties({ distinctId: 'sdk-member', properties: { plan: 'paid' }, propertiesOnce: { first_plan: 'paid' } });
+      sdk.unsetPersonProperties({ distinctId: 'sdk-member', properties: ['plan'] });
+      await sdk.flush();
+      await sdk.shutdown();
+      const rows = (await read(c, 'persons', '?distinct_id=sdk-member')).results;
+      const person = rows[0];
+      if (rows.length !== 1 || !person.distinct_ids.includes('sdk-anonymous')) return ['the alias did not link the two IDs to one person'];
+      return person.properties.source === 'invite' && person.properties.email === 'sdk@harbourline.test'
+        && person.properties.first_plan === 'trial' && !('plan' in person.properties) ? [] : ['profile updates lost the anonymous properties, overwrote set_once, or retained the unset property'];
+    },
+  },
+  {
+    id: 'transient-retry-preserves-request-and-event-uuid',
+    asks: 'a transient503 is retried with the same event UUID and accepted once by the twin',
+    source: CORE + ' "return err.status === 408 || err.status === 429 || err.status >= 500"',
+    async run(c) {
+      const requests: Request[] = [];
+      const forwarded = (async (url: Parameters<typeof fetch>[0], init?: RequestInit) => {
+        const request = new Request(url, init);
+        if (request.method !== 'POST') return c.fetch(request);
+        requests.push(request.clone());
+        if (requests.length === 1) return new Response('service unavailable', { status: 503 });
+        return c.fetch(request);
+      }) as typeof fetch;
+      const sdk = await client(c, { fetch: forwarded });
+      await sdk.captureImmediate({ distinctId: 'sdk-retry-member', event: 'sdk_retry_capture' });
+      await sdk.shutdown();
+      const failures: string[] = [];
+      if (requests.length !== 2) failures.push('one transient503 did not cause exactly one retry');
+      else {
+        const first = new Uint8Array(await requests[0]!.arrayBuffer()), second = new Uint8Array(await requests[1]!.arrayBuffer());
+        if (first.length !== second.length || first.some((v, i) => v !== second[i])) failures.push('the retry changed the prepared payload and event UUID');
+      }
+      const events = await read(c, 'events', '?event=sdk_retry_capture');
+      if (events.results.length !== 1 || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(events.results[0]?.id ?? '')) failures.push('the retried capture is not one stored event with a UUID');
+      return failures;
+    },
+  },
+  {
+    id: 'nonretryable401-is-a-typed-http-error',
+    asks: 'capture with a personal key is rejected as401 once; the official client exposes PostHogFetchHttpError and its status',
+    source: CORE + ' "class PostHogFetchHttpError extends Error"',
+    async run(c) {
+      let attempts = 0;
+      const sdk = await client(c, { key: c.env.POSTHOG_PERSONAL_API_KEY, fetch: (async (url: Parameters<typeof fetch>[0], init?: RequestInit) => { attempts++; return c.fetch(url, init); }) as typeof fetch });
+      let error: unknown;
+      try { await sdk.captureImmediate({ distinctId: 'sdk-refusal', event: 'sdk_refused_capture' }); } catch (caught) { error = caught; }
+      await sdk.shutdown();
+      const typed = error as { name?: string; status?: number } | undefined;
+      return attempts === 1 && typed?.name === 'PostHogFetchHttpError' && typed.status === 401 ? [] : ['the401 was retried or did not expose the SDK HTTP error and status'];
+    },
+  },
+  {
+    id: 'flags-empty-account-through-node-client',
+    asks: 'getAllFlags interprets the v2 response with person/group overrides and requested keys for this account with no flags',
+    source: 'https://unpkg.com/posthog-node@5.46.1/src/client.ts "Promise that resolves to a record of flag keys and their values"',
+    async run(c) {
+      const sdk = await client(c);
+      const flags = await sdk.getAllFlags('sdk-member', { groups: { organization: 'sdk-harbourline' },
+        personProperties: { email: 'sdk@harbourline.test' }, groupProperties: { organization: { name: 'Harbourline SDK case' } }, flagKeys: ['new-booking-flow'] });
+      await sdk.shutdown();
+      return Object.keys(flags).length === 0 ? [] : ['the empty account returned invented flags'];
+    },
+  },
+];

package/src/clients/run.ts

@@ -0,0 +1,18 @@
+// The vendor's client cases, run in Node as an application runs its SDK: `node run.ts <job.json>`. The job names the
+// vendor, the served port, the host, the issued credentials and the scenario file; each case's failures are printed as
+// one JSON line, `{ id, asks, failures }`.
+import { readFileSync } from 'node:fs';
+import { clientContext, worldProxy, type ClientCase } from './harness.ts';
+
+const job = JSON.parse(readFileSync(process.argv[2]!, 'utf8')) as { vendor: string; port: number; host: string; env: Record<string, string>; scenarioPath: string };
+const { cases } = (await import(`./${job.vendor}.ts`)) as { cases: ClientCase[] };
+// every connection a case makes goes through the World's proxy, as an application's does in a World
+const context = clientContext(await worldProxy(job.port), job.host, job.env, job.scenarioPath);
+for (const c of cases) {
+  const failures = await Promise.race([
+    c.run(context).catch((e: Error) => [`the case threw: ${e.message}`]),
+    new Promise<string[]>((r) => setTimeout(() => r(['no outcome in 30 s']), 30_000)),
+  ]);
+  process.stdout.write(`${JSON.stringify({ id: c.id, asks: c.asks, failures })}\n`);
+}
+process.exit(0);

package/src/clients/sentry.ts

@@ -0,0 +1,157 @@
+// Official SDKs at the demanded applications' pinned versions. The native HTTP module
+// takes the harness agent, preserving the SDK's DSN URL, compression, queue and wire.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { request as httpsRequest } from 'node:https';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import type { ClientCase, ClientContext } from './harness.ts';
+
+// The pins live in ../../client-sdks with their own lockfile, installed here on first use: some carry advisories with no
+// fix in the line an application pins, so the repository's install (and a release, .github/release-scan.mjs) never does.
+const SDKS = new URL('../../client-sdks/', import.meta.url);
+async function sdkOf(name: string): Promise<any> {
+  if (!existsSync(new URL('node_modules/', SDKS))) {
+    const install = spawnSync('bun', ['install', '--frozen-lockfile', '--ignore-scripts'], { cwd: SDKS, stdio: 'inherit' });
+    if (install.status !== 0) throw new Error('client-sdks: bun install --frozen-lockfile failed');
+  }
+  return await import(pathToFileURL(createRequire(new URL('package.json', SDKS)).resolve(name)).href);
+}
+
+const pins = [
+  ['rallly', '@sentry/node', '10.38.0'],
+  ['twenty', 'sentry-node-twenty', '10.73.0'],
+  ['postiz', 'sentry-node-postiz', '10.56.0'],
+  ['cal-api', 'sentry-node-cal', '9.46.0'],
+  ['cal-web', 'sentry-node-cal-web', '10.33.0'],
+] as const;
+
+async function token(c: ClientContext): Promise<string> {
+  const answer = await c.fetch('https://' + c.host + '/_twin/auth-tokens', { method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ organization: c.env.SENTRY_ORG, name: 'SDK read-back', kind: 'personal', scopes: ['org:read', 'project:read', 'event:read'] }) });
+  if (!answer.ok) throw new Error('read-back token: ' + answer.status);
+  return (await answer.json() as { token: string }).token;
+}
+
+async function read(c: ClientContext, id: string, auth: string): Promise<Record<string, any>> {
+  const answer = await c.fetch(`https://${c.host}/api/0/projects/${c.env.SENTRY_ORG}/${c.env.SENTRY_PROJECT}/events/${id}/`, { headers: { authorization: 'Bearer ' + auth } });
+  if (!answer.ok) throw new Error('event read-back: ' + answer.status);
+  return await answer.json();
+}
+
+export const cases: ClientCase[] = pins.map(([application, name, version]) => ({
+  id: application + '-native-exception-flush-compression',
+  asks: 'captureException prepares its event ID, stack and scope; flush drains the native compressed envelope and its event reads back',
+  source: `https://unpkg.com/@sentry/core@${version}/build/esm/client.js "transport.flush(timeout)"`,
+  async run(c) {
+    const sdk = await sdkOf(name);
+    const requests: Array<{ url: string; encoding?: string }> = [];
+    const client = new sdk.NodeClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+      release: 'sdk-' + application, environment: 'sdk', transport: (options: any) => sdk.makeNodeTransport({ ...options,
+        httpModule: { request(options: any, callback: any) { requests.push({ url: String(options.path), encoding: options.headers?.['Content-Encoding'] ?? options.headers?.['content-encoding'] }); return httpsRequest({ ...options, agent: c.agent }, callback); } },
+      }) });
+    const scope = new sdk.Scope();
+    scope.setUser({ id: 'sdk-member' }); scope.setTag('application', application);
+    scope.setExtra('large-context', 'x'.repeat(64 * 1024));
+    const id = client.captureException(new Error('SDK ' + application + ' exception'), undefined, scope);
+    const drained = await client.flush(10_000);
+    const event = await read(c, id, await token(c));
+    await client.close(10_000);
+    const failures: string[] = [];
+    if (!drained || requests.length !== 1 || !requests[0]!.url.includes('/envelope/')) failures.push('flush did not drain exactly one exception envelope');
+    if (requests[0]?.encoding !== 'gzip') failures.push('large Node envelope was not compressed');
+    if (event.eventID !== id || event.user?.id !== 'sdk-member' || event.context?.['large-context']?.length !== 64 * 1024) failures.push('event ID or scope did not survive the native transport');
+    if (!event.entries?.some((e: any) => e.type === 'exception' && e.data.values[0]?.stacktrace?.frames?.length)) failures.push('the SDK stack was lost');
+    return failures;
+  },
+}));
+
+for (const [name, version] of [['@sentry/browser', '10.38.0'], ['sentry-browser-twenty', '10.59.0'], ['sentry-browser-postiz', '10.56.0']] as const) cases.push({
+  id: 'browser-' + version + '-dsn-query-auth-and-session-envelope',
+  asks: 'the browser fetch transport uses DSN query authentication and flushes event and session envelopes',
+  source: `https://unpkg.com/@sentry/core@${version}/build/esm/api.js "sentry_key: publicKey"`,
+  async run(c) {
+    const sdk = await sdkOf(name);
+    const { makeSession } = await sdkOf('@sentry/core');
+    const sent: Request[] = [];
+    const forward = (async (url: Parameters<typeof fetch>[0], init?: RequestInit) => { const request = new Request(url, init); sent.push(request.clone()); return c.fetch(request); }) as typeof fetch;
+    const client = new sdk.BrowserClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+      transport: (options: any) => sdk.makeFetchTransport(options, forward) });
+    const id = client.captureEvent({ message: 'browser SDK case', level: 'error', platform: 'javascript' });
+    client.captureSession(makeSession({ release: 'sdk-browser', environment: 'sdk' }));
+    const drained = await client.flush(10_000);
+    const event = await read(c, id, await token(c));
+    await client.close(10_000);
+    return drained && sent.length === 2 && sent.every((r) => new URL(r.url).searchParams.has('sentry_key')) && event.message === 'browser SDK case' ? [] : ['browser queue, DSN query authentication or event/session envelopes failed'];
+  },
+});
+
+cases.push({
+  id: 'twenty-cron-check-in-options-and-id',
+  asks: 'captureCheckIn creates an ID for in_progress and reuses it for ok with the monitor schedule and configured margins',
+  source: 'https://unpkg.com/@sentry/core@10.73.0/build/esm/server-runtime-client.js "checkin_margin: monitorConfig.checkinMargin"',
+  async run(c) {
+    const sdk = await sdkOf('sentry-node-twenty');
+    const sent: string[] = [];
+    const client = new sdk.NodeClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+      transport: (options: any) => sdk.createTransport(options, async (request: { body: string | Uint8Array }) => {
+        sent.push(typeof request.body === 'string' ? request.body : new TextDecoder().decode(request.body));
+        const answer = await c.fetch(options.url, { method: 'POST', body: request.body as BodyInit });
+        return { statusCode: answer.status, headers: {} };
+      }) });
+    let id = '';
+    sdk.withScope((scope: any) => { scope.setClient(client); id = sdk.captureCheckIn({ monitorSlug: 'sdk-cleanup', status: 'in_progress' }, { schedule: { type: 'crontab', value: '0 3 * * *' }, checkinMargin: 1, maxRuntime: 5 }); sdk.captureCheckIn({ monitorSlug: 'sdk-cleanup', status: 'ok', checkInId: id }); });
+    const drained = await client.flush(10_000); await client.close(10_000);
+    const payloads = sent.map((s) => JSON.parse(s.split('\n')[2]!));
+    return drained && payloads.length === 2 && payloads[0].check_in_id === id && payloads[1].check_in_id === id && payloads[0].monitor_config.checkin_margin === 1 && payloads[0].monitor_config.max_runtime === 5 && !('duration' in payloads[1]) ? [] : ['check-in ID or monitor options changed'];
+  },
+});
+
+cases.push({
+  id: 'transport-rate-limit-drop-and-no-retry',
+  asks: 'core transport drains its queue, drops a rate-limited category and does not retry a 503',
+  source: 'https://unpkg.com/@sentry/core@10.38.0/build/esm/transports/base.js "ratelimit_backoff"',
+  async run(c) {
+    const sdk = await sdkOf('@sentry/core');
+    const ds = new URL(c.env.SENTRY_DSN!);
+    const url = `https://${ds.host}/api${ds.pathname}/envelope/?sentry_key=${ds.username}&sentry_version=7`;
+    let attempts = 0; const dropped: string[] = [];
+    const transport = sdk.createTransport({ recordDroppedEvent: (reason: string) => { dropped.push(reason); } }, async (request: { body: string | Uint8Array }) => {
+      attempts++;
+      if (attempts === 1) return { statusCode: 503, headers: {} };
+      const response = await c.fetch(url, { method: 'POST', body: request.body as BodyInit });
+      return { statusCode: response.status, headers: { 'x-sentry-rate-limits': '60:error:organization' } };
+    });
+    const envelope = (id: string) => sdk.createEnvelope({ event_id: id }, [[{ type: 'event' }, { event_id: id, message: 'transport SDK case', platform: 'javascript' }]]);
+    await transport.send(envelope('00000000000000000000000000000001'));
+    await transport.send(envelope('00000000000000000000000000000002'));
+    await transport.send(envelope('00000000000000000000000000000003'));
+    const drained = await transport.flush(10_000);
+    return drained && attempts === 2 && dropped.includes('ratelimit_backoff') ? [] : ['transport retried 503, failed to drain, or sent a rate-limited event'];
+  },
+});
+
+
+cases.push({
+  id: 'postiz-feedback-attribution',
+  asks: 'captureFeedback preserves the widget message, explicit name/email, associated event and scoped user',
+  source: 'https://unpkg.com/@sentry/core@10.56.0/build/esm/feedback.js "associated_event_id: associatedEventId"',
+  async run(c) {
+    const sdk = await sdkOf('sentry-browser-postiz');
+    const client = new sdk.BrowserClient({ dsn: c.env.SENTRY_DSN, integrations: [], stackParser: sdk.defaultStackParser,
+      transport: (options: any) => sdk.createTransport(options, async (request: { body: string | Uint8Array }) => {
+        const answer = await c.fetch(options.url, { method: 'POST', body: request.body as BodyInit });
+        return { statusCode: answer.status, headers: {} };
+      }) });
+    let id = '';
+    sdk.withScope((scope: any) => {
+      scope.setClient(client); scope.setUser({ id: 'feedback-author' });
+      id = sdk.captureFeedback({ message: 'The scheduling button is hard to find', name: 'Priya', email: 'priya@harbourline.test', associatedEventId: '00000000000000000000000000000002' }, {}, scope);
+    });
+    const drained = await client.flush(10_000);
+    const event = await read(c, id, await token(c));
+    await client.close(10_000);
+    const feedback = event.contexts?.feedback;
+    return drained && event.type === 'feedback' && event.user?.id === 'feedback-author' && feedback?.name === 'Priya' && feedback?.contact_email === 'priya@harbourline.test' && feedback?.associated_event_id === '00000000000000000000000000000002' ? [] : ['feedback attribution or associated event was lost'];
+  },
+});