@volter/twin-standard 1.0.158 → 1.0.160

package/dist/src/clients/harness.js

@@ -11,16 +11,38 @@ 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) {
+ *  answers are then the vendor's secure ones). Its stop settles every connection it opened. */
+export async function worldProxy(served, observe) {
+    const sockets = new Set();
+    const requests = new Set();
+    const track = (socket) => { if (sockets.has(socket))
+        return; sockets.add(socket); socket.once('close', () => sockets.delete(socket)); };
     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) => {
+            if (observe) {
+                answer.on('end', () => {
+                    const headers = new Headers();
+                    for (const [name, value] of Object.entries(req.headers))
+                        if (value !== undefined)
+                            for (const one of Array.isArray(value) ? value : [value])
+                                headers.append(name, one);
+                    observe({ url: `https://${headers.get('x-volter-twin-original-host') ?? headers.get('host')}${req.url}`, headers }, { status: answer.statusCode ?? 502 });
+                });
+            }
+            answer.on('error', () => res.destroy());
             res.writeHead(answer.statusCode ?? 502, answer.headers);
             answer.pipe(res);
         });
-        forward.on('error', () => { res.writeHead(502); res.end(); });
+        requests.add(forward);
+        forward.once('close', () => requests.delete(forward));
+        forward.on('error', () => { if (!res.headersSent)
+            res.writeHead(502); res.end(); });
+        forward.on('socket', track);
+        req.on('aborted', () => forward.destroy());
+        res.on('close', () => forward.destroy());
         req.pipe(forward);
     });
+    server.on('connection', track);
     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}`)), '', ''];
@@ -30,15 +52,115 @@ export async function worldProxy(served) {
             upstream.pipe(socket);
             socket.pipe(upstream);
         });
+        track(upstream);
         upstream.on('error', () => socket.destroy());
         socket.on('error', () => upstream.destroy());
+        socket.on('close', () => upstream.destroy());
+    });
+    await new Promise((done, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => { server.off('error', reject); done(); });
     });
-    await new Promise((r) => server.listen(0, '127.0.0.1', () => r()));
     server.unref();
-    return server.address().port;
+    let stopping;
+    return {
+        port: server.address().port,
+        stop: () => stopping ??= (async () => {
+            const closed = new Promise((done, reject) => server.close((error) => error ? reject(error) : done()));
+            const pending = [...requests].map((request) => new Promise((done) => { request.once('close', () => done()); request.destroy(); }));
+            const connections = [...sockets].map((socket) => new Promise((done) => { socket.once('close', () => done()); socket.destroy(); }));
+            await Promise.all([closed, ...pending, ...connections]);
+        })(),
+    };
 }
-/** HTTP to a served pack, with the vendor Host and manual redirects. Each call owns a fresh connection;
- * its caller's abort signal retires that request, including an unfinished response body. */
+/** A served socket either opens within its five-second handshake or closes under the same owner. */
+export function openWebSocket(socket) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (opened) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            socket.removeEventListener('open', openedSocket);
+            socket.removeEventListener('error', failed);
+            socket.removeEventListener('close', failed);
+            try {
+                if (!opened)
+                    socket.close();
+            }
+            catch (error) {
+                reject(error);
+                return;
+            }
+            resolve(opened);
+        };
+        const openedSocket = () => finish(true);
+        const failed = () => finish(false);
+        const timer = setTimeout(failed, 5000);
+        socket.addEventListener('open', openedSocket, { once: true });
+        socket.addEventListener('error', failed, { once: true });
+        socket.addEventListener('close', failed, { once: true });
+    });
+}
+/** One request and its complete body share the check's ten-second lifetime, including caller cancellation. */
+export async function readHttpResponse(fetcher, request) {
+    request.signal.throwIfAborted();
+    const abort = new AbortController();
+    const signal = AbortSignal.any([request.signal, abort.signal]);
+    const timer = setTimeout(() => abort.abort(new DOMException('request exceeded 10 s', 'TimeoutError')), 10_000);
+    let cancel;
+    const interrupted = new Promise((_, reject) => {
+        cancel = () => reject(signal.reason);
+        signal.addEventListener('abort', cancel, { once: true });
+        if (signal.aborted)
+            cancel();
+    });
+    let reader;
+    try {
+        const arriving = fetcher(new Request(request, { signal })).then((response) => {
+            if (signal.aborted)
+                void response.body?.cancel(signal.reason).catch(() => undefined);
+            return response;
+        });
+        const response = await Promise.race([arriving, interrupted]);
+        reader = response.body?.getReader();
+        const chunks = [];
+        let size = 0;
+        let bodyError;
+        try {
+            if (reader)
+                for (;;) {
+                    const chunk = await Promise.race([reader.read(), interrupted]);
+                    if (chunk.done)
+                        break;
+                    chunks.push(chunk.value);
+                    size += chunk.value.byteLength;
+                }
+        }
+        catch (error) {
+            bodyError = { message: String(error), cancelled: signal.aborted || error instanceof Error && ['AbortError', 'TimeoutError'].includes(error.name) };
+            void reader?.cancel(error).catch(() => undefined);
+        }
+        const bodyBytes = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            bodyBytes.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        const cookies = response.headers.getSetCookie();
+        return { status: response.status, headers: { ...Object.fromEntries(response.headers), ...(cookies.length ? { 'set-cookie': cookies.join(', ') } : {}) },
+            text: new TextDecoder().decode(bodyBytes), bodyBytes, ...(bodyError ? { bodyError } : {}) };
+    }
+    finally {
+        clearTimeout(timer);
+        if (cancel)
+            signal.removeEventListener('abort', cancel);
+        reader?.releaseLock();
+    }
+}
+/** HTTP to a served pack, with the vendor Host and manual redirects. Headers resolve before the streamed body;
+ * its caller's abort signal owns the fresh connection until the body ends or is cancelled. */
 export function servedHttpFetch(port) {
     return (async (input, init) => {
         const request = new Request(input, init);
@@ -49,28 +171,68 @@ export function servedHttpFetch(port) {
         const signal = init?.signal ?? (input instanceof Request ? input.signal : request.signal);
         return new Promise((resolve, reject) => {
             const cleanup = () => signal.removeEventListener('abort', abort);
-            const failed = (error) => { cleanup(); reject(error); };
+            let responseFailed;
+            const failed = (error) => { cleanup(); if (responseFailed)
+                responseFailed(error);
+            else
+                reject(error); };
             const sent = httpRequest({ host: '127.0.0.1', port, method: request.method, path: `${url.pathname}${url.search}`, headers, agent: false }, (res) => {
+                res.pause();
+                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);
                 const chunks = [];
-                res.on('data', (c) => chunks.push(c));
-                res.on('end', () => {
-                    cleanup();
-                    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);
-                    try {
-                        resolve(new Response(request.method === 'HEAD' || res.statusCode === 204 || res.statusCode === 205 || res.statusCode === 304 ? null : Buffer.concat(chunks), { status: res.statusCode ?? 0, headers: answer }));
+                let controller;
+                let ended = false, cancelled = false, bodyError;
+                const pump = () => {
+                    if (cancelled)
+                        return;
+                    while (chunks.length && (controller.desiredSize ?? 0) > 0)
+                        controller.enqueue(chunks.shift());
+                    if (chunks.length || (controller.desiredSize ?? 0) <= 0) {
+                        res.pause();
+                        return;
                     }
-                    catch (error) {
-                        reject(error);
+                    // Do not error until the reader has taken queued bytes: an errored web stream discards its queue.
+                    if (bodyError) {
+                        cancelled = true;
+                        controller.error(bodyError);
                     }
+                    else if (ended) {
+                        cancelled = true;
+                        controller.close();
+                    }
+                    else
+                        res.resume();
+                };
+                const body = new ReadableStream({
+                    start(value) { controller = value; },
+                    pull() { pump(); },
+                    cancel() { cancelled = true; chunks.length = 0; cleanup(); res.destroy(); sent.destroy(); },
                 });
-                res.on('error', failed);
+                responseFailed = (error) => { bodyError ??= error; cleanup(); pump(); };
+                res.on('data', (chunk) => { chunks.push(chunk); pump(); });
+                res.on('end', () => { ended = true; cleanup(); pump(); });
+                res.on('error', responseFailed);
+                res.on('close', () => { if (!res.complete && !cancelled)
+                    responseFailed(new Error('HTTP response closed before completion')); });
+                const noBody = request.method === 'HEAD' || res.statusCode === 204 || res.statusCode === 205 || res.statusCode === 304;
+                try {
+                    resolve(new Response(noBody ? null : body, { status: res.statusCode ?? 0, headers: answer }));
+                    if (noBody)
+                        res.resume();
+                }
+                catch (error) {
+                    cancelled = true;
+                    cleanup();
+                    res.destroy();
+                    reject(error);
+                }
             });
             const abort = () => {
-                const error = new Error('served HTTP request aborted');
+                const error = signal.reason instanceof Error ? signal.reason : new Error('served HTTP request aborted');
                 sent.destroy(error);
                 failed(error);
             };

package/dist/src/clients/jira.js

@@ -1,3 +1,14 @@
+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;
+};
+import { standardPackageFile } from "../package-file.js";
+const { importSdk } = await import(__rewriteRelativeImportExtension(new URL('import.mjs', standardPackageFile('client-sdks/')).href));
+const { Version3Client, HttpException } = await importSdk('jira.js');
 const README = 'https://www.npmjs.com/package/jira.js/v/5.4.0';
 const CREATE = 'https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-post';
 const ADF = 'https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/';
@@ -12,7 +23,6 @@ async function site(c, slug, apiToken) {
     const email = `admin@${slug}.example`;
     const made = await door('/_twin/sites', { name: slug, admin: { name: 'Admin', email, password: 'sdk-case-2026' } });
     const token = apiToken ?? (await door('/_twin/api-token', { site: slug, email, password: 'sdk-case-2026' })).apiToken;
-    const { Version3Client } = await import('jira.js');
     const jira = new Version3Client({ host: `https://${slug}.atlassian.net`, authentication: { basic: { email, apiToken: token } }, baseRequestConfig: { httpsAgent: c.agent } });
     return { jira, admin: made.admin };
 }
@@ -55,7 +65,6 @@ export const cases = [
         asks: 'a request with an API token the account never made is refused, and the client throws its HttpException carrying the status',
         source: `${README} "\`HttpException\`: Server responded with an error (includes parsed error details)"`,
         async run(c) {
-            const { HttpException } = await import('jira.js');
             const { jira } = await site(c, 'sdk-refused', 'ATATT-not-a-token-this-account-made');
             try {
                 await jira.projects.searchProjects({ maxResults: 50 });

package/dist/src/clients/resend.first-use.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "source": "https://www.npmjs.com/package/resend/v/6.6.0",
-  "about": "Send a synthetic sign-in email through the official SDK and inspect the retained message and local inbox after restart. Advance the frozen World clock to settle synthetic delivery before retained-state inspection.",
+  "about": "Send a synthetic sign-in email through the official SDK and inspect the retained message after restart. Advance the frozen World clock to settle synthetic delivery before retained-state inspection.",
   "files": {
     "package.json": "{\n  \"name\": \"resend-installed-customer\",\n  \"private\": true,\n  \"type\": \"module\",\n  \"dependencies\": {\n    \"resend\": \"6.6.0\"\n  }\n}\n",
     ".env.example": "RESEND_API_KEY=\n",
-    "inspect-email.mjs": "import assert from 'node:assert/strict';\nimport { readFileSync } from 'node:fs';\nimport { Resend } from 'resend';\n\nassert.ok(process.env.VOLTER_WORLD, 'run this script through the World');\nconst { id } = JSON.parse(readFileSync('last-email.json', 'utf8'));\nconst resend = new Resend(process.env.RESEND_API_KEY);\nconst saved = await resend.emails.get(id);\nassert.equal(saved.error, null);\nassert.equal(saved.data.last_event, 'delivered');\nconst response = await fetch(`${process.env.RESEND_TWIN_URL}/_twin/mail?to=owner%40world.test`);\nassert.equal(response.status, 200);\nconst inbox = await response.json();\nconst email = inbox.mail.find((message) => message.id === id);\nassert.ok(email, 'the delivered message must be in the local inbox');\nassert.equal(email.subject, 'Your local sign-in code');\nassert.match(email.text, /123456/);\nassert.match(email.html, /<strong>123456<\\/strong>/);\nconsole.log('local inbox contains the delivered email and sign-in code');\n",
+    "inspect-email.mjs": "import assert from 'node:assert/strict';\nimport { readFileSync } from 'node:fs';\nimport { Resend } from 'resend';\n\nassert.ok(process.env.VOLTER_WORLD, 'run this script through the World');\nconst { id } = JSON.parse(readFileSync('last-email.json', 'utf8'));\nconst resend = new Resend(process.env.RESEND_API_KEY);\nconst saved = await resend.emails.get(id);\nassert.equal(saved.error, null);\nassert.equal(saved.data.last_event, 'delivered');\nassert.equal(saved.data.subject, 'Your local sign-in code');\nassert.match(saved.data.text, /123456/);\nassert.match(saved.data.html, /<strong>123456<\\/strong>/);\nconsole.log('the retained email reads back with its sign-in code');\n",
     "send-email.mjs": "import assert from 'node:assert/strict';\nimport { writeFileSync } from 'node:fs';\nimport { Resend } from 'resend';\n\nassert.ok(process.env.VOLTER_WORLD, 'run this script through the World');\nconst resend = new Resend(process.env.RESEND_API_KEY);\nconst email = {\n  from: 'Example app <onboarding@resend.dev>',\n  to: ['owner@world.test'],\n  subject: 'Your local sign-in code',\n  text: 'Your synthetic sign-in code is 123456.',\n  html: '<p>Your synthetic sign-in code is <strong>123456</strong>.</p>'\n};\nconst sent = await resend.emails.send(email);\nassert.equal(sent.error, null);\nassert.ok(sent.data.id);\nconst saved = await resend.emails.get(sent.data.id);\nassert.equal(saved.error, null);\nassert.equal(saved.data.id, sent.data.id);\nassert.equal(saved.data.subject, email.subject);\nassert.equal(saved.data.text, email.text);\nassert.deepEqual(saved.data.to, email.to);\nwriteFileSync('last-email.json', JSON.stringify({ id: sent.data.id }) + '\\n');\nconsole.log('email sent and read back locally');\n"
   },
   "run": [

package/dist/src/clients/run.js

@@ -20,19 +20,24 @@ if (!Array.isArray(cases) || cases.length === 0)
     throw new Error(`${job.vendor} client module declares no cases; there is no SDK execution evidence`);
 // every connection a case makes goes through the World's proxy, as an application's does in a World
 const proxy = await worldProxy(job.port);
-// Bind only this artifact's declared vendor hosts to the assessed server. The enclosing World's
-// injector stays active, and untwinned destinations keep its refusal policy.
-const require = createRequire(import.meta.url);
-require('@volter/world-core/pack-facts').extendPackFacts([job.packFacts]);
-const facts = JSON.parse(readFileSync(job.packFacts, 'utf8')).packs[job.vendor];
-const keys = [...new Set((facts.hosts ?? []).map((rule) => rule.key ?? job.vendor))];
-require('@volter/world-core/inject').install(Object.fromEntries(keys.map((key) => [key, `http://127.0.0.1:${proxy}`])));
-const context = clientContext(proxy, job.host, job.env, job.scenarioPath, job.raw ? job.port : undefined);
-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`);
+try {
+    // Bind only this artifact's declared vendor hosts to the assessed server. The enclosing World's
+    // injector stays active, and untwinned destinations keep its refusal policy.
+    const require = createRequire(import.meta.url);
+    require('@volter/world-core/pack-facts').extendPackFacts([job.packFacts]);
+    const facts = JSON.parse(readFileSync(job.packFacts, 'utf8')).packs[job.vendor];
+    const keys = [...new Set((facts.hosts ?? []).map((rule) => rule.key ?? job.vendor))];
+    require('@volter/world-core/inject').install(Object.fromEntries(keys.map((key) => [key, `http://127.0.0.1:${proxy.port}`])));
+    const context = clientContext(proxy.port, job.host, job.env, job.scenarioPath, job.raw ? job.port : undefined);
+    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`);
+    }
+}
+finally {
+    await proxy.stop();
 }
 process.exit(0);

package/dist/src/conformance.d.ts

@@ -1,3 +1,4 @@
+import { type ConsumerResult } from './consumer.js';
 export type ConformanceResult = {
     id: string;
     asks: string;
@@ -5,13 +6,10 @@ export type ConformanceResult = {
     note?: string;
 };
 /** The files conformance reads from a unit: its manifest, its spec's record, its vendor's life and its decision table
- *  (a lane's journeys are its own `journeys/` or else its vendor's). A release publishes each (published()), and a
- *  pack's standing counts it in the form only when every unit holds them (twin-world's scripts/pack-standing.ts, by
- *  unitFilesMissing): the one list of both. */
+ *  (a lane's journeys are its own `journeys/` or else its vendor's). A release publishes each (published()). */
 export declare const UNIT_FILES: readonly ["src/manifest.ts", "spec/SOURCE.md", "journeys/customer-life.json", "journeys/decisions.json"];
 /** The published package must carry every conformance input its units hold, including lanes. */
 export declare function unpublishedUnitFiles(unit: string): string[];
-export declare function unitFilesMissing(unit: string): string[];
 type Owners = Record<string, string>;
 type Decision = {
     operation: string;
@@ -33,5 +31,6 @@ export declare function decisionTableProblems(unit: string, byUnit: Record<strin
 /** `onCheck` hears each check's id as it starts, so a caller can show where a long run stands. */
 export declare function conformance(dir: string, options?: {
     onCheck?: (id: string) => void;
+    consumer?: ConsumerResult;
 }): Promise<ConformanceResult[]>;
 export {};