@volter/twin-standard 1.0.30 → 1.0.32

package/dist/src/clients/harness.js

@@ -0,0 +1,74 @@
+// THE VENDOR'S OWN CLIENT — how conformance drives a pack the way an application does (docs/contributing/architecture.md,
+// "Conformance"): the vendor's official SDK, unmodified, in a Node process as an application runs it, against the pack
+// served as a World runs it. Its credentials are the ones the pack's own credential door issued; its connections reach the
+// served port as a World's interception routes the vendor's hosts, the vendor's URL and Host unchanged (an HTTP request
+// over node:http with its Host kept, a socket's TCP connection made to the served port). A case's expectations are the
+// vendor's documented semantics, each cited, never the pack author's life.
+import { createServer, request as httpRequest } from 'node:http';
+import { Agent as HttpsAgent } from 'node:https';
+import { connect } from 'node:net';
+import { writeFileSync } from 'node:fs';
+/** The World's proxy in front of a pack served on `served`: it ends the caller's TLS (here, none was begun) and forwards
+ *  each request and socket upgrade to the pack with `x-forwarded-proto: https`, the vendor's Host unchanged, as a World's
+ *  proxy forwards a caller of the vendor's https host (twin-fetch.ts, twinPublicBase: the links and socket URLs the pack
+ *  answers are then the vendor's secure ones). Answers the proxy's port. */
+export async function worldProxy(served) {
+    const server = createServer((req, res) => {
+        const forward = httpRequest({ host: '127.0.0.1', port: served, method: req.method, path: req.url, headers: { ...req.headers, 'x-forwarded-proto': 'https' } }, (answer) => {
+            res.writeHead(answer.statusCode ?? 502, answer.headers);
+            answer.pipe(res);
+        });
+        forward.on('error', () => { res.writeHead(502); res.end(); });
+        req.pipe(forward);
+    });
+    server.on('upgrade', (req, socket, head) => {
+        const upstream = connect(served, '127.0.0.1', () => {
+            const lines = [`${req.method} ${req.url} HTTP/1.1`, ...Object.entries({ ...req.headers, 'x-forwarded-proto': 'https' }).flatMap(([k, v]) => (Array.isArray(v) ? v : [v]).map((x) => `${k}: ${x}`)), '', ''];
+            upstream.write(lines.join('\r\n'));
+            if (head.length)
+                upstream.write(head);
+            upstream.pipe(socket);
+            socket.pipe(upstream);
+        });
+        upstream.on('error', () => socket.destroy());
+        socket.on('error', () => upstream.destroy());
+    });
+    await new Promise((r) => server.listen(0, '127.0.0.1', () => r()));
+    server.unref();
+    return server.address().port;
+}
+/** The context for a pack reached at `port` of this machine (the World's proxy in front of it). */
+export function clientContext(port, host, env, scenarioPath) {
+    const routedFetch = (async (input, init) => {
+        const request = new Request(input, init);
+        const url = new URL(request.url);
+        const body = request.method === 'GET' || request.method === 'HEAD' ? undefined : Buffer.from(await request.arrayBuffer());
+        const headers = Object.fromEntries(request.headers);
+        headers.host = url.host;
+        return new Promise((resolve, reject) => {
+            const sent = httpRequest({ host: '127.0.0.1', port, method: request.method, path: `${url.pathname}${url.search}`, headers }, (res) => {
+                const chunks = [];
+                res.on('data', (c) => chunks.push(c));
+                res.on('end', () => {
+                    const answer = new Headers();
+                    for (const [k, v] of Object.entries(res.headers))
+                        if (v !== undefined)
+                            for (const one of Array.isArray(v) ? v : [v])
+                                answer.append(k, one);
+                    resolve(new Response(res.statusCode === 204 || res.statusCode === 304 ? null : Buffer.concat(chunks), { status: res.statusCode ?? 0, headers: answer }));
+                });
+                res.on('error', reject);
+            });
+            sent.on('error', reject);
+            sent.end(body);
+        });
+    });
+    const agent = new (class extends HttpsAgent {
+        createConnection() { return connect(port, '127.0.0.1'); }
+    })({ keepAlive: false });
+    return {
+        host, env, fetch: routedFetch, agent,
+        connect: () => connect(port, '127.0.0.1'),
+        scenario: (doc) => writeFileSync(scenarioPath, JSON.stringify(doc)),
+    };
+}

package/dist/src/clients/merge.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/merge.js

@@ -0,0 +1,8 @@
+// Merge Gateway through the SDKs its callers use: openai-node on its chat completions, Anthropic's SDK on its Messages
+// surface (both of its OpenAI- and Anthropic-compatible APIs), the shared cases.
+import { messagesCases } from "./anthropic-messages.js";
+import { chatCases } from "./openai-compatible.js";
+export const cases = [
+    ...chatCases({ key: 'MERGE_GATEWAY_API_KEY', base: (host) => `https://${host}/v1`, model: 'zai/glm-5.3-flash' }),
+    ...messagesCases({ key: 'MERGE_GATEWAY_API_KEY', base: (host) => `https://${host}`, model: 'zai/glm-5.3-flash', toolTurn: { toolCalls: [{ name: 'lookup', arguments: {} }] } }),
+];

package/dist/src/clients/openai-compatible.d.ts

@@ -0,0 +1,9 @@
+import type { ClientCase, ClientContext } from './harness.js';
+/** 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 declare function openaiClient(c: ClientContext, v: Compatible): Promise<import("openai").default>;
+export declare function chatCases(v: Compatible): ClientCase[];

package/dist/src/clients/openai-compatible.js

@@ -0,0 +1,51 @@
+const CHAT = 'https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create';
+const TOOLS = [{ type: 'function', 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' } },
+    ] };
+export async function openaiClient(c, v) {
+    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) {
+    const ask = async (c, extra = {}) => (await openaiClient(c, v)).chat.completions.create({ model: v.model, messages: [{ role: 'user', content: 'hello' }], ...extra });
+    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) => 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) => 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 ${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 ${e.message}`);
+                return first === 'first script' && second === 'second script' ? [] : [`the turns answered "${first}" then "${second}"`];
+            },
+        },
+    ];
+}

package/dist/src/clients/openai.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/openai.js

@@ -0,0 +1,65 @@
+import { chatCases } from "./openai-compatible.js";
+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) {
+    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', 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, toolChoice) {
+    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 } }, openai);
+        let first;
+        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.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 } });
+            rt.send({ type: 'conversation.item.create', item: { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'hello' }] } });
+            rt.send({ type: 'response.create' });
+        });
+        rt.on('event', (e) => {
+            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 = [
+    ...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/dist/src/clients/openrouter.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/openrouter.js

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

package/dist/src/clients/perplexity.d.ts

@@ -0,0 +1 @@
+export declare const cases: import("./harness.js").ClientCase[];

package/dist/src/clients/perplexity.js

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

package/dist/src/clients/planetscale.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/planetscale.js

@@ -0,0 +1,109 @@
+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';
+/** A connection as Dub's lib/planetscale/connection.ts makes one: `connect({ url })`, here with the World's fetch. */
+async function connection(c) {
+    const { connect } = (await import('@planetscale/database'));
+    return connect({ url: c.env.PLANETSCALE_DATABASE_URL, fetch: c.fetch });
+}
+export const cases = [
+    {
+        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 = [];
+                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];
+                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.name}: ${e.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) => e);
+                const out = [];
+                if (raised !== refused)
+                    out.push(`the failed transaction raised ${String(raised?.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.name}: ${e.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) => e);
+                if (!raised)
+                    return ['inserting the same key twice succeeded'];
+                const out = [];
+                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.name}: ${e.message}`];
+            }
+        },
+    },
+];

package/dist/src/clients/posthog.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];

package/dist/src/clients/posthog.js

@@ -0,0 +1,145 @@
+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, options = {}) {
+    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, resource, query = '') {
+    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();
+}
+export const cases = [
+    {
+        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 = [];
+            const forwarded = (async (url, init) => {
+                const request = new Request(url, init);
+                if (request.method === 'POST')
+                    requests.push(request.clone());
+                return c.fetch(request);
+            });
+            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 = [];
+            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) => 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) => 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 = [];
+            const forwarded = (async (url, init) => {
+                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);
+            });
+            const sdk = await client(c, { fetch: forwarded });
+            await sdk.captureImmediate({ distinctId: 'sdk-retry-member', event: 'sdk_retry_capture' });
+            await sdk.shutdown();
+            const failures = [];
+            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, init) => { attempts++; return c.fetch(url, init); }) });
+            let error;
+            try {
+                await sdk.captureImmediate({ distinctId: 'sdk-refusal', event: 'sdk_refused_capture' });
+            }
+            catch (caught) {
+                error = caught;
+            }
+            await sdk.shutdown();
+            const typed = error;
+            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/dist/src/clients/run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/clients/run.js

@@ -0,0 +1,25 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// 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 } from "./harness.js";
+const job = JSON.parse(readFileSync(process.argv[2], 'utf8'));
+const { cases } = (await import(__rewriteRelativeImportExtension(`./${job.vendor}.ts`)));
+// 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) => [`the case threw: ${e.message}`]),
+        new Promise((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/dist/src/clients/sentry.d.ts

@@ -0,0 +1,2 @@
+import type { ClientCase } from './harness.js';
+export declare const cases: ClientCase[];