@volter/twin-standard 1.0.158 → 1.0.159

package/dist/src/walk/walk-database.js

@@ -3,6 +3,7 @@
 import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join } from 'node:path';
+import { worldDoorMatcher } from '@volter/world-core/runtime';
 let loaded;
 const worldRuntime = () => loaded ??= (async () => {
     try {
@@ -19,7 +20,7 @@ export async function startTwinDatabase(pack, descriptor) {
     const definition = descriptor.managedDatabase, door = descriptor.credentialDoor;
     if (!definition || !door || !definition.credentialField)
         throw new Error('The selected twin must declare its SQL credential door field');
-    const { runWorld, worldConfigDocument } = await worldRuntime();
+    const { runWorld, worldConfigDocument, verifyPrivateTwinDatabaseConnection } = await worldRuntime();
     // Keep the disposable World on the pack's own volume and package-resolution ancestry.
     const root = mkdtempSync(join(dirname(pack), '.walk-database-'));
     const manifest = JSON.parse(readFileSync(join(pack, 'package.json'), 'utf8'));
@@ -30,10 +31,10 @@ export async function startTwinDatabase(pack, descriptor) {
     const readyFile = join(root, 'ready.json'), releaseFile = join(root, 'release');
     // Ask the selected twin's actual product door. The runtime alone allocates and owns its engine.
     const hold = `
-    import { existsSync, readFileSync, renameSync, watch, writeFileSync } from 'node:fs';
-    import { dirname } from 'node:path';
+    import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+    import { join } from 'node:path';
     const [ready, release, vendor, path, body, field] = process.argv.slice(1);
-    if (!process.env.VOLTER_WORLD_INSTANCE) throw new Error('Missing held World instance');
+    if (!process.env.VOLTER_WORLD_INSTANCE || !process.env.VOLTER_WORLD_DATA) throw new Error('Missing held World instance');
     const instance = JSON.parse(readFileSync(process.env.VOLTER_WORLD_INSTANCE, 'utf8'));
     const service = instance.services[vendor];
     if (!service?.url) throw new Error('Selected twin has no product endpoint');
@@ -42,8 +43,8 @@ export async function startTwinDatabase(pack, descriptor) {
     const result = await response.json();
     if (typeof result[field] !== 'string' || !result[field]) throw new Error('SQL credential door omitted its declared field');
     const done = () => { if (existsSync(release)) process.exit(0); };
-    watch(dirname(release), done);
-    writeFileSync(ready + '.tmp', JSON.stringify({ url: result[field] }), {mode:0o600});
+    setInterval(done, 100);
+    writeFileSync(ready + '.tmp', JSON.stringify({ url: result[field], databaseRoot: join(process.env.VOLTER_WORLD_DATA, vendor) }), {mode:0o600});
     renameSync(ready + '.tmp', ready);
     done();`;
     let finished;
@@ -65,12 +66,33 @@ export async function startTwinDatabase(pack, descriptor) {
     }
     const ready = JSON.parse(readFileSync(readyFile, 'utf8'));
     let stopping;
-    return { url: ready.url,
-        stop: () => stopping ??= (async () => {
-            writeFileSync(releaseFile, 'released\n');
-            const result = await task;
-            if (result.exitCode !== 0)
-                throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
-        })(),
+    const stop = () => stopping ??= (async () => {
+        writeFileSync(releaseFile, 'released\n');
+        const result = await task;
+        if (result.exitCode !== 0)
+            throw new Error(`Twin SQL World consumer exited ${result.exitCode}; evidence: ${root}`);
+    })();
+    const verify = (value) => verifyPrivateTwinDatabaseConnection(descriptor.vendor, ready.databaseRoot, value);
+    try {
+        await verify(ready.url);
+    }
+    catch (error) {
+        try {
+            await stop();
+        }
+        catch (cleanup) {
+            throw new AggregateError([error, cleanup], 'Native connection verification and World retirement failed');
+        }
+        throw error;
+    }
+    const matches = worldDoorMatcher([{ method: 'POST', path: door.path }]);
+    return { url: ready.url, stop,
+        connection: async (method, path, status, body) => {
+            if (status < 200 || status >= 300 || !matches(method, path))
+                return undefined;
+            const value = body && typeof body === 'object' ? body[definition.credentialField] : undefined;
+            await verify(value);
+            return { kind: definition.kind, field: definition.credentialField, authenticated: true };
+        },
     };
 }

package/dist/src/walk/xml-view.d.ts

@@ -1,2 +1,3 @@
-/** The root element's members, or undefined when the text is not one XML document. */
-export declare function xmlMembers(text: string): Record<string, unknown> | undefined;
+/** The root element's members, or undefined when the text is not one XML document.
+ *  A schema distinguishes an empty structure from an empty scalar member such as LocationConstraint. */
+export declare function xmlMembers(text: string, rootFields?: ReadonlyArray<string>): Record<string, unknown> | undefined;

package/dist/src/walk/xml-view.js

@@ -3,11 +3,12 @@
 // text. What a restXml output structure's members are on the wire, so a journey asserts and captures them (`Contents.0.Key`)
 // and SHAPE checks them as it checks a JSON answer's. Attributes and namespaces are not members and are dropped. XML
 // cannot say a lone element is a list: one `<Contents>` reads as an object, two as a list. A root with no children is
-// its one member, by its name.
+// its one member, by its name. When a resource schema is supplied, an empty root is a member only if the schema names it.
 const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
 const decode = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) => (e[0] === '#' ? String.fromCodePoint(e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : Number(e.slice(1))) : ENTITIES[e] ?? m));
-/** The root element's members, or undefined when the text is not one XML document. */
-export function xmlMembers(text) {
+/** The root element's members, or undefined when the text is not one XML document.
+ *  A schema distinguishes an empty structure from an empty scalar member such as LocationConstraint. */
+export function xmlMembers(text, rootFields) {
     const src = text.replace(/<\?[\s\S]*?\?>/g, '').replace(/<!--[\s\S]*?-->/g, '').replace(/<!\[CDATA\[([\s\S]*?)\]\]>/g, (_, c) => c.replace(/&/g, '&amp;').replace(/</g, '&lt;'));
     const stack = [{ name: '', children: [], text: '' }];
     const tag = /<(\/?)([\w:.-]+)[^>]*?(\/?)>|([^<]+)/g;
@@ -50,6 +51,6 @@ export function xmlMembers(text) {
     };
     // a document whose root is a leaf (S3's `<LocationConstraint>auto</LocationConstraint>`) is that one member
     if (!root.children.length)
-        return { [root.name]: value(root) };
+        return !root.text.trim() && rootFields && !rootFields.includes(root.name) ? {} : { [root.name]: value(root) };
     return value(root);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.158",
+  "version": "1.0.159",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -77,8 +77,8 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.163",
-    "@volter/world-runtime": "*",
+    "@volter/world-core": "3.0.164",
+    "@volter/world-runtime": "^3.0.188",
     "playwright": "^1.63.0"
   },
   "peerDependenciesMeta": {

package/src/assessment.ts

@@ -8,7 +8,8 @@ import { conformance } from './conformance.ts';
 import { inMemoryWorld, walk, withPinnedWorldDraws, usePacks, type ServedTwin } from './walk/behavior-journey.ts';
 import { compilePackFacts } from './pack-facts.ts';
 import { expandFills, type Journey } from './walk/journey-kit.ts';
-import { runConsumerWorkflow, type ConsumerOptions } from './consumer.ts';
+import { compareReplays, type ReplayStep } from './walk/replay.ts';
+import { runConsumerWorkflow, type ConsumerOptions, type ConsumerResult } from './consumer.ts';
 
 const canonical = (value: unknown): unknown => value && typeof value === 'object' ? Array.isArray(value) ? value.map(canonical) : Object.fromEntries(Object.entries(value).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => [key, canonical(item)])) : value;
 const json = (value: unknown) => JSON.stringify(canonical(value));
@@ -56,7 +57,8 @@ export async function assessPack(packDir: string, options: AssessmentOptions = {
   const coverageOf = (result: { exercised: string[]; ambiguous: boolean }) => !instrumented || result.ambiguous ? null : { total: declared.length, exercised: result.exercised.length, percent: 100 * result.exercised.length / declared.length, operations: result.exercised, missing: declared.filter((id) => !result.exercised.includes(id)) };
   async function replay(served?: ServedTwin) {
     const world = inMemoryWorld('catalog-replay');
-    const failures: Array<{ step: string; beat: string; detail: string }> = [], trace: unknown[] = [];
+    const failures: Array<{ step: string; beat: string; detail: string }> = [];
+    const trace: ReplayStep[] = [];
     const exercised = new Set<string>();
     const signatures = new WeakMap<object, string>();
     let ambiguous = false;
@@ -70,14 +72,15 @@ export async function assessPack(packDir: string, options: AssessmentOptions = {
       exercised.add(id);
     });
     try {
-      await withPinnedWorldDraws(() => walk(structuredClone(life), world.root(), failures, { beats: true, ...(served ? { served } : {}), hooks: { after: (step, path, answer) => trace.push({ name: step.name ?? '', path, status: answer.status, body: answer.body }) } }));
+      await withPinnedWorldDraws(() => walk(structuredClone(life), world.root(), failures, { beats: true, ...(served ? { served } : {}), hooks: { after: (step, path, answer) => trace.push({ name: step.name ?? '', path, status: answer.status, body: answer.body, ...(answer.sql ? { sql: answer.sql } : {}), ...(answer.connection ? { connection: answer.connection } : {}) }) } }));
       return { failures, trace, exercised: [...exercised].sort(), ambiguous };
     } finally { stop(); world.restore(); }
   }
   const first = await replay(), second = await replay();
-  const replayEqual = first.trace.length > 0 && json(first.trace) === json(second.trace);
+  const comparison = compareReplays(first.trace, second.trace);
+  const replayEqual = comparison.equal;
   const coverage = coverageOf(first);
-  const quick = { scope: 'packaged-customer-journey; in-process', steps: life.steps.length, answered: first.trace.length, failures: [...first.failures, ...second.failures], replay: { equal: replayEqual, runs: 2, firstSha256: hash(first.trace), secondSha256: hash(second.trace) }, operationCoverage: coverage, servedOperations, surface: owners ? { total: declared.length, served: servedOperations.length, gap: declared.length - servedOperations.length } : null, codeCoverage: null, stateTransitionCoverage: null };
+  const quick = { scope: 'packaged-customer-journey; in-process', steps: life.steps.length, answered: first.trace.length, failures: [...first.failures, ...second.failures], replay: { equal: replayEqual, diagnostics: comparison.diagnostics, runs: 2, firstSha256: hash(first.trace), secondSha256: hash(second.trace) }, operationCoverage: coverage, servedOperations, surface: owners ? { total: declared.length, served: servedOperations.length, gap: declared.length - servedOperations.length } : null, codeCoverage: null, stateTransitionCoverage: null };
   let browser: Record<string, unknown> = { measured: false, reason: options.browser ? 'Journey has a wire Chromium fetch cannot exercise' : 'Browser target not requested' };
   const httpOnly = life.steps.every((step) => 'method' in step || 'wait' in step);
   if (options.browser && httpOnly) {
@@ -85,13 +88,14 @@ export async function assessPack(packDir: string, options: AssessmentOptions = {
     const transport = await chromiumServed(packDir, life.host ?? 'twin.local', 'http-journey');
     try {
       const a = await replay(transport.served), b = await replay(transport.served);
-      browser = { measured: true, target: 'HTTP customer journey replay through Chromium at each request origin; authored HTTP headers and observed wire responses', responseObservation: 'Transport observes status, headers and body, including redirects and Set-Cookie; these are not JavaScript-visible response claims', applicationOriginCorsCoverage: null, cookieJarCoverage: null, version: transport.version, answered: a.trace.length, failures: [...a.failures, ...b.failures], replay: { equal: a.trace.length > 0 && json(a.trace) === json(b.trace), firstSha256: hash(a.trace), secondSha256: hash(b.trace), runs: 2 }, operationCoverage: coverageOf(a), domCoverage: null, clock: transport.clock };
+      const compared = compareReplays(a.trace, b.trace);
+      browser = { measured: true, target: 'HTTP customer journey replay through Chromium at each request origin; authored HTTP headers and observed wire responses', responseObservation: 'Transport observes status, headers and body, including redirects and Set-Cookie; these are not JavaScript-visible response claims', applicationOriginCorsCoverage: null, cookieJarCoverage: null, version: transport.version, answered: a.trace.length, failures: [...a.failures, ...b.failures], replay: { equal: compared.equal, diagnostics: compared.diagnostics, firstSha256: hash(a.trace), secondSha256: hash(b.trace), runs: 2 }, operationCoverage: coverageOf(a), domCoverage: null, clock: transport.clock };
     } finally { await transport.stop(); }
   }
-  const conform = options.conformance === false ? null : await conformance(packDir);
-  let consumer;
+  let consumer: ConsumerResult | { measured: false; passed: false; failures: string[] };
   try { consumer = options.consumer ? await runConsumerWorkflow(packDir, options.consumer) : { measured: false, passed: false, failures: ['Installed customer workflow was not prepared'] }; }
   catch (error) { consumer = { measured: false, passed: false, failures: [(error as Error).message] }; }
+  const conform = options.conformance === false ? null : await conformance(packDir, consumer.measured ? { consumer } : {});
   const ready = gates.length > 0 && gates.every((gate) => !gate.failures.length) && !quick.failures.length && replayEqual && conform !== null && conform.length > 0 && conform.every((result) => !result.failures.length) && consumer.measured && consumer.passed && (!options.browser || !httpOnly || browser.measured === true && (browser.failures as unknown[]).length === 0 && (browser.replay as { equal: boolean }).equal);
   // the artifact assessed, by the integrity its prepared consumer verified the installed candidate against (consumer.ts)
   return { schemaVersion: 1, vendor, package: manifest.name, version: manifest.version, ...((consumer as { integrity?: string }).integrity ? { integrity: (consumer as { integrity?: string }).integrity } : {}), ready, gates: gates.map((gate) => ({ ...gate, unit: gate.unit === packDir ? vendor : `${vendor}/${gate.unit.slice(packDir.length + 1)}` })), quick, browser, conformance: conform, consumer };

package/src/browser-assessment.ts

@@ -4,10 +4,10 @@ import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { worldNow } from '@volter/world-core/runtime';
 import type { ServedTwin } from './walk/behavior-journey.ts';
+import { packFetch } from './walk/vendor-fetch.ts';
 export async function chromiumServed(packDir: string, host: string, mode: 'browser-fetch' | 'http-journey' = 'browser-fetch') {
   const { chromium } = await import('playwright');
-  const mod = await import(join(packDir, 'src/index.ts')) as Record<string, unknown>;
-  const factory = Object.entries(mod).find(([name, value]) => /^create\w+Fetch$/.test(name) && !/TwinFetch$/.test(name) && typeof value === 'function')?.[1] as ((options: import('@volter/world-core').PackFetchOptions) => (request: Request) => Promise<Response>) | undefined;
+  const factory = await packFetch(packDir);
   if (!factory) throw new Error('Browser assessment needs the pack HTTP fetch factory');
   const library = ['/usr/lib/x86_64-linux-gnu/faketime/libfaketimeMT.so.1', '/usr/lib/aarch64-linux-gnu/faketime/libfaketimeMT.so.1'].find(existsSync);
   if (process.platform !== 'linux' || !library) throw new Error('Deterministic browser assessment needs Linux libfaketime installed for native cookie time');
@@ -27,7 +27,7 @@ export async function chromiumServed(packDir: string, host: string, mode: 'brows
   catch (error) { rmSync(clockDir, { recursive: true, force: true }); throw error; }
   const served: ServedTwin = async (root, options) => {
     syncClock();
-    const fetchPack = factory({ root, ...options });
+    const fetchPack = factory(root, options);
     const context = await browser.newContext({ serviceWorkers: 'block', locale: 'en-US', timezoneId: 'UTC' });
     type Page = Awaited<ReturnType<typeof context.newPage>>;
     const pages: Array<{ page: Page; origin: string; busy: boolean }> = [];
@@ -65,7 +65,7 @@ export async function chromiumServed(packDir: string, host: string, mode: 'brows
     };
     return {
       scheme: 'https',
-      fetch: async (request: Request, options?: { credentials?: RequestCredentials }) => {
+      fetch: Object.assign(async (request: Request, options?: { credentials?: RequestCredentials }) => {
         const entry = await acquire(mode === 'http-journey' ? new URL(request.url).origin : `https://${host}`);
         const { page } = entry;
         const observation = { request } as { request: Request; response?: Response; error?: unknown };
@@ -89,8 +89,15 @@ export async function chromiumServed(packDir: string, host: string, mode: 'brows
           if (!result.status) throw new Error('Chromium returned an opaque response; this journey needs browser-specific navigation assertions');
           return new Response([101, 204, 205, 304].includes(result.status) || request.method === 'HEAD' ? null : Buffer.from(result.body, 'base64'), { status: result.status, headers: result.headers });
         } finally { pending.delete(page); entry.busy = false; }
+      }, {
+        managedDatabaseUrl: fetchPack.managedDatabaseUrl,
+        managedDatabaseClock: fetchPack.managedDatabaseClock,
+        managedDatabaseConnection: fetchPack.managedDatabaseConnection,
+      }),
+      stop: async () => {
+        try { await context.close(); }
+        finally { await fetchPack.stopDatabase?.(); }
       },
-      stop: () => context.close(),
     };
   };
   return { served, version: browser.version(), clock: { native: 'World time through libfaketime', nativePrecisionMs: 1000, javascriptPrecisionMs: 1, monotonic: 'elapsed machine time' }, stop: async () => { try { await browser.close(); } finally { rmSync(clockDir, { recursive: true, force: true }); } } };

package/src/clients/harness.ts

@@ -4,7 +4,7 @@
 // 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 { createServer, request as httpRequest, type ClientRequest } from 'node:http';
 import { Agent as HttpsAgent } from 'node:https';
 import { connect, type AddressInfo, type Socket } from 'node:net';
 import { writeFileSync } from 'node:fs';
@@ -41,16 +41,33 @@ export type ClientCase = {
 /** 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: number): Promise<number> {
+ *  answers are then the vendor's secure ones). Its stop settles every connection it opened. */
+export async function worldProxy(served: number, observe?: (request: { url: string; headers: Headers }, answer: { status: number }) => void) {
+  const sockets = new Set<Socket>();
+  const requests = new Set<ClientRequest>();
+  const track = (socket: 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}`)), '', ''];
@@ -59,16 +76,103 @@ export async function worldProxy(served: number): Promise<number> {
       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<void>((done, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => { server.off('error', reject); done(); });
   });
-  await new Promise<void>((r) => server.listen(0, '127.0.0.1', () => r()));
   server.unref();
-  return (server.address() as AddressInfo).port;
+  let stopping: Promise<void> | undefined;
+  return {
+    port: (server.address() as AddressInfo).port,
+    stop: () => stopping ??= (async () => {
+      const closed = new Promise<void>((done, reject) => server.close((error) => error ? reject(error) : done()));
+      const pending = [...requests].map((request) => new Promise<void>((done) => { request.once('close', () => done()); request.destroy(); }));
+      const connections = [...sockets].map((socket) => new Promise<void>((done) => { socket.once('close', () => done()); socket.destroy(); }));
+      await Promise.all([closed, ...pending, ...connections]);
+    })(),
+  };
+}
+
+/** A served socket either opens within its five-second handshake or closes under the same owner. */
+export function openWebSocket(socket: WebSocket): Promise<boolean> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (opened: boolean) => {
+      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) => Promise<Response>, request: Request): Promise<{
+  status: number; headers: Record<string, string>; text: string; bodyBytes: Uint8Array;
+  bodyError?: { message: string; cancelled: boolean };
+}> {
+  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: (() => void) | undefined;
+  const interrupted = new Promise<never>((_, reject) => {
+    cancel = () => reject(signal.reason);
+    signal.addEventListener('abort', cancel, { once: true });
+    if (signal.aborted) cancel();
+  });
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  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: Uint8Array[] = [];
+    let size = 0;
+    let bodyError: { message: string; cancelled: boolean } | undefined;
+    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. Each call owns a fresh connection;
- * its caller's abort signal retires that request, including an unfinished response body. */
+/** 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: number): typeof fetch {
   return (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const request = new Request(input, init);
@@ -79,21 +183,40 @@ export function servedHttpFetch(port: number): typeof fetch {
     const signal = init?.signal ?? (input instanceof Request ? input.signal : request.signal);
     return new Promise<Response>((resolve, reject) => {
       const cleanup = () => signal.removeEventListener('abort', abort);
-      const failed = (error: Error) => { cleanup(); reject(error); };
+      let responseFailed: ((error: Error) => void) | undefined;
+      const failed = (error: 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) => {
-        const chunks: Buffer[] = [];
-        res.on('data', (c: Buffer) => 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 })); }
-          catch (error) { reject(error); }
+        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: Uint8Array[] = [];
+        let controller: ReadableStreamDefaultController<Uint8Array>;
+        let ended = false, cancelled = false, bodyError: Error | undefined;
+        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; }
+          // 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<Uint8Array>({
+          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: Buffer) => { 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/src/clients/jira.ts

@@ -3,6 +3,10 @@
 // requests through the World's routed HTTPS agent. The site, its admin and the token are made at the pack's doors, as a
 // person makes them at Atlassian's sign-up and account console.
 import type { ClientCase, ClientContext } from './harness.ts';
+import { standardPackageFile } from '../package-file.ts';
+
+const { importSdk } = await import(new URL('import.mjs', standardPackageFile('client-sdks/')).href);
+const { Version3Client, HttpException }: typeof import('jira.js') = 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';
@@ -18,7 +22,6 @@ async function site(c: ClientContext, slug: string, apiToken?: string) {
   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! };
 }
@@ -59,7 +62,6 @@ export const cases: ClientCase[] = [
     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/src/clients/run.ts

@@ -12,19 +12,21 @@ const { cases } = (await import(`./${job.vendor}${extname(fileURLToPath(import.m
 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: string[] = [...new Set<string>((facts.hosts ?? []).map((rule: { key?: string }) => 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: 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`);
-}
+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: string[] = [...new Set<string>((facts.hosts ?? []).map((rule: { key?: string }) => 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: 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`);
+  }
+} finally { await proxy.stop(); }
 process.exit(0);