ravensight-playtest 0.5.0 → 0.5.2

package/README.md

@@ -1,5 +1,53 @@
 # ravensight-playtest
 
+Hosted comparisons use a separate command from the local `run`:
+
+```sh
+ravensight-playtest hosted quote --game GAME --build BUILD --profile PROFILE --persona curious-kid --video --transcript --output hosted-quote.json
+ravensight-playtest hosted run hosted-quote.json
+```
+
+The quote names the full Standard then Jev price, prepaid amount, evidence
+options, expiry and refund rules. It charges nothing. `hosted run` confirms
+that saved quote before one admission request. Its durable journal blocks an
+automatic second POST after an uncertain outcome; preserve it for reconciliation.
+A charged-blocked acknowledgement does not prove gameplay or a report. This
+command does not top up funds, change local run/report files or ask for model
+proxy permission on the CLI credential.
+
+On a server that advertises it as ready, `hosted quote --standard-provider openai`
+selects OpenAI for Standard. Explicit `anthropic` works the same way. The returned
+provider and policy hash must match and remain in the saved consent; `hosted run`
+has no provider override. Omitting the flag keeps the original default request
+and consent wire. No choice falls back to another provider, and a CLI declaration
+does not establish deployed provider or hosted engine readiness. Existing `run`
+continues to use its local runner and original API contract.
+
+The hosted build command source adds a local check before a paid upload:
+
+```sh
+ravensight-playtest build preflight ./game.zip --format web --entrypoint index.html
+ravensight-playtest build upload ./game.zip --game GAME --profile READY_PROFILE --entrypoint index.html --dry-run
+```
+
+`preflight` seeks through bounded ZIP metadata; it does not load a multi-GB
+archive into memory. A saved server profile can be supplied with `--capacity`
+for its declared limits. Upload selects a currently advertised ready profile,
+checks metadata and a streamed checksum, then asks for the separate $0.49
+validation hold before requesting it. The server’s isolated validator remains
+authoritative. A passing local check does not establish engine, GPU or license
+compatibility.
+
+The current upload protocol is one streamed presigned PUT. Multipart upload
+and byte-range resume are not advertised. The original upload journal is kept
+after an uncertain response, and repeating that upload cannot silently request
+a second reservation. A different journal does not cancel or refund an earlier
+upload. Reports and existing run-upload journals are left intact. Larger limits
+and native executable formats are usable only when the server advertises a
+ready profile and the corresponding upload and runtime support exists. This
+source addition does not claim an accepted AAA engine run or a published CLI
+release.
+
 AI personas play your game, then file a report you can read, mark up and argue
 with. The personas run on your machine, against your build; Ravensight stores
 the reports and renders them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ravensight-playtest",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Local AI playtests and seeded game simulations with reports in Ravensight.",
   "license": "MIT",
   "homepage": "https://ravensight.io/docs/#playtest",

package/src/api/client.js

@@ -51,7 +51,7 @@ export function createClient(options = {}) {
    * @param {string} method
    * @param {string} path
    * @param {{query?: Object, body?: unknown, headers?: Object, idempotent?: boolean,
-   *   raw?: boolean, anonymous?: boolean}} [opts]
+   *   raw?: boolean, anonymous?: boolean, onResponseRaw?: Function}} [opts]
    * @returns {Promise<{status: number, headers: Headers, body: unknown}>}
    */
   async function request(method, path, opts = {}) {
@@ -86,6 +86,7 @@ export function createClient(options = {}) {
       bodyText,
       idempotent: Boolean(opts.idempotent),
       raw: Boolean(opts.raw),
+      onResponseRaw: opts.onResponseRaw,
       ...transport
     });
   }

package/src/api/http.js

@@ -43,18 +43,26 @@ export function buildUrl(apiUrl, path, query) {
 }
 
 /**
- * Read a response body without ever throwing. A 502 from a load balancer is
+ * Read a response body without throwing for body or JSON decoding errors. A 502 from a load balancer is
  * HTML, a 204 is empty, and a JSON parse failure on the error path would
  * replace a useful status code with a useless SyntaxError.
  * @param {Response} response
  * @returns {Promise<{json: unknown, text: string}>}
  */
-async function readBody(response) {
+async function readBody(response, onResponseRaw) {
   let text = '';
-  try {
-    text = await response.text();
-  } catch {
-    return { json: null, text: '' };
+  if (onResponseRaw) {
+    let bytes = Buffer.alloc(0), bodyComplete = false;
+    try { bytes = Buffer.from(await response.arrayBuffer()); bodyComplete = true; }
+    catch { /* Preserve a read-failure observation, never invent complete bytes. */ }
+    // Opt-in capture runs on every HTTP status BEFORE JSON parsing or an
+    // ApiError. Capture failures propagate and cannot trigger a request retry.
+    await onResponseRaw({ status: response.status, contentType: response.headers.get('content-type'), bytes, bodyComplete });
+    if (!bodyComplete) return { json: null, text: '' };
+    text = new TextDecoder().decode(bytes);
+  } else {
+    try { text = await response.text(); }
+    catch { return { json: null, text: '' }; }
   }
   if (!text) return { json: null, text: '' };
   try {
@@ -102,6 +110,7 @@ function errorFrom(response, parsed, { method, path }) {
  * @param {string} [options.bodyText]
  * @param {boolean} [options.idempotent]
  * @param {boolean} [options.raw] - resolve the body as text, not JSON
+ * @param {Function} [options.onResponseRaw] - await exact response-byte capture before parsing, including non-2xx
  * @param {number} [options.retries]
  * @param {number} [options.timeoutMs]
  * @param {typeof fetch} [options.fetchImpl]
@@ -119,6 +128,7 @@ export async function requestWithRetry(options) {
     bodyText,
     idempotent = false,
     raw = false,
+    onResponseRaw,
     retries = DEFAULT_RETRIES,
     timeoutMs = DEFAULT_TIMEOUT_MS,
     fetchImpl = globalThis.fetch,
@@ -162,7 +172,7 @@ export async function requestWithRetry(options) {
     }
 
     if (response) {
-      const parsed = await readBody(response);
+      const parsed = await readBody(response, onResponseRaw);
       if (response.ok || response.status === 304) {
         return {
           status: response.status,

package/src/cli.js

@@ -143,6 +143,50 @@ function withoutFirst(values, value) {
 export function buildProgram() {
   const program = new Command();
   const slot = { code: ExitCode.OK };
+  const hosted = common(program.command('hosted').description('quote and admit a server-hosted Standard/Jev comparison'));
+  hosted.command('quote')
+    .description('save a full hosted quote without charging or admitting a run')
+    .requiredOption('--build <id>', 'an existing validated hosted build')
+    .requiredOption('--profile <version>', 'one currently advertised ready hosted profile')
+    .requiredOption('--persona <slug>', 'one available persona for both separate playthroughs')
+    .requiredOption('--output <file>', 'save the original quote and immutable consent here')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .addOption(new Option('--standard-provider <name>', 'explicit Standard provider; unavailable choices are refused').choices(['anthropic', 'openai']))
+    .option('--video', 'include hosted gameplay video in this quote')
+    .option('--transcript', 'include the hosted transcript in this quote')
+    .action(capture(slot, async (options, command) => {
+      const { hostedQuote } = await import('./commands/hosted.js');
+      return hostedQuote(flagsFrom(command.optsWithGlobals(), { build: options.build, profile: options.profile,
+        persona: options.persona, output: options.output, game: options.game, standardProvider: options.standardProvider,
+        video: options.video, transcript: options.transcript }));
+    }));
+  hosted.command('run <quote-file>')
+    .description('confirm the full saved quote and request one hosted admission; never retry an unknown outcome')
+    .action(capture(slot, async (filename, _options, command) => {
+      const { hostedRun } = await import('./commands/hosted.js');
+      return hostedRun(filename, flagsFrom(command.optsWithGlobals()));
+    }));
+  const build = common(program.command('build').description('check or upload a self-contained hosted game archive'));
+  build.command('preflight <archive>')
+    .description('check bounded ZIP metadata locally before any paid upload')
+    .requiredOption('--entrypoint <path>', 'entry file inside the ZIP')
+    .option('--format <name>', 'web or godot-project without a selected capacity profile', 'web')
+    .option('--capacity <file>', 'saved profile JSON for a local capacity check; does not establish server readiness')
+    .action(capture(slot, async (archive, options, command) => {
+      const { buildPreflight } = await import('./commands/build.js');
+      return buildPreflight(archive, flagsFrom(command.optsWithGlobals(), { entrypoint: options.entrypoint, format: options.format, capacity: options.capacity }));
+    }));
+  build.command('upload <archive>')
+    .description('preflight and stream one private build upload after validation-hold consent')
+    .requiredOption('--profile <version>', 'one currently advertised ready server profile')
+    .requiredOption('--entrypoint <path>', 'entry file inside the ZIP')
+    .option('--game <id>', 'game id, overriding this repo’s configuration')
+    .option('--journal <file>', 'preserve this original upload intent at the specified path')
+    .option('--dry-run', 'inspect and hash the archive without requesting a reservation')
+    .action(capture(slot, async (archive, options, command) => {
+      const { buildUpload } = await import('./commands/build.js');
+      return buildUpload(archive, flagsFrom(command.optsWithGlobals(), { entrypoint: options.entrypoint, profile: options.profile, game: options.game, journal: options.journal, dryRun: options.dryRun }));
+    }));
   program.exitCodeSlot = slot;
   program
     .name('ravensight-playtest')

package/src/commands/build.js

@@ -0,0 +1,81 @@
+import { readFile, stat } from 'node:fs/promises';
+import { createContext } from '../api/index.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { preflightBuildArchive, limitsFromProfile } from '../hosted/archivePreflight.js';
+import { uploadHostedBuild } from '../hosted/buildUpload.js';
+import { CliError, ExitCode } from '../errors.js';
+import { ui } from '../ui/index.js';
+
+// TTY animation stays live while I/O awaits. Piped logs receive at most one
+// byte update per second, plus phase boundaries and the final byte count.
+export function buildUploadProgress({ json = false, now = Date.now } = {}) {
+  let spin, phase, last = 0, finished = false;
+  const labels = { capabilities: 'Checking available build profiles', preflight: 'Checking ZIP metadata',
+    hash: 'Hashing archive', reservation: 'Requesting the confirmed validation hold',
+    upload: 'Streaming archive bytes', completion: 'Submitting the original upload for validation' };
+  return {
+    update(event) {
+      if (json || ui.isQuiet()) return;
+      const at = now(), changed = phase !== event.phase;
+      const complete = event.totalBytes !== undefined && event.completedBytes === event.totalBytes;
+      if (!changed && at - last < 1000 && (!complete || finished)) return;
+      const label = labels[event.phase] + (event.totalBytes === undefined ? ''
+        : `: ${ui.bytes(event.completedBytes)} / ${ui.bytes(event.totalBytes)}`);
+      if (changed) { spin?.stop(); spin = ui.spinner(label); phase = event.phase; }
+      else spin.update(label);
+      last = at; finished = complete;
+    },
+    stop() { spin?.stop(); spin = null; phase = null; finished = false; }
+  };
+}
+
+export async function buildPreflight(filename, flags = {}) {
+  let profile;
+  if (flags.capacity) {
+    const info = await stat(flags.capacity);
+    if (!info.isFile() || info.size > 65536) throw new CliError('Choose a capacity profile JSON file no larger than 64 KiB.');
+    profile = JSON.parse(await readFile(flags.capacity, 'utf8'));
+  }
+  const result = await preflightBuildArchive(filename, { format: profile?.format || flags.format,
+    entrypoint: flags.entrypoint, limits: profile ? limitsFromProfile(profile) : undefined,
+    requirements: profile?.capacity?.requirements });
+  if (flags.json) ui.json(result);
+  else {
+    ui.ok(`ZIP metadata passed: ${result.entries} entries; ${ui.bytes(result.archiveBytes)} uploaded, ${ui.bytes(result.expandedBytes)} expanded.`);
+    ui.info('No wallet charge or upload was requested. Server validation and runtime compatibility checks are still required.');
+  }
+  return ExitCode.OK;
+}
+
+export async function buildUpload(filename, flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const progress = buildUploadProgress({ json: Boolean(flags.json) });
+    try {
+      const result = await uploadHostedBuild({ filename, gameId: resolveGameId(flags, context.config), profileVersion: flags.profile,
+        entrypoint: flags.entrypoint, repoRoot: context.repoRoot, api: context.api, apiUrl: context.api.apiUrl,
+        journalPath: flags.journal, dryRun: Boolean(flags.dryRun), fetchImpl: deps.fetch,
+        confirm: deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) })),
+        onProgress: event => progress.update(event),
+        onPrepared: prepared => {
+          progress.stop();
+          if (flags.json) return;
+          ui.info(`ZIP metadata checked: ${prepared.entries} entries; ${ui.bytes(prepared.archiveBytes)} archive, ${ui.bytes(prepared.expandedBytes)} expanded.`);
+          const limit = prepared.limits;
+          ui.info(`Selected limits: archive ${ui.bytes(limit.archiveBytes)}, expanded ${ui.bytes(limit.expandedBytes)}, file ${ui.bytes(limit.fileBytes)}, ${limit.files} entries, depth ${limit.depth}, ratio ${limit.ratio}:1.`);
+          const required = prepared.capacity?.requirements;
+          if (required) ui.info(`Server profile: ${required.os}/${required.architecture}, ${required.cpuVcpus} CPU, ${ui.bytes(required.memoryBytes)} RAM. Runtime and license readiness must come from the server.`);
+          if (Number.isSafeInteger(prepared.funding?.minimumFundingCents)) ui.info(`Server prepaid funding minimum: $${(prepared.funding.minimumFundingCents / 100).toFixed(2)}; the separate gameplay price is quoted after validation.`);
+          ui.info('Static validation hold: $0.49 from prepaid funds, returned after safe cleanup. A gameplay quote is separate. No top-up is performed.');
+          ui.info('Passing this local check does not establish GPU, licensing or game runtime compatibility.');
+        }
+      });
+      progress.stop();
+      if (flags.json) ui.json(result);
+      else if (result.state === 'awaiting_validation') ui.ok(`Uploaded ${result.buildId}; awaiting server validation. Journal: ${result.journal}`);
+      else ui.info(result.state === 'declined' ? 'Upload declined; no reservation requested.' : 'Preflight finished; no reservation requested.');
+      return result.state === 'declined' ? ExitCode.CANCELED : ExitCode.OK;
+    } finally { progress.stop(); }
+  });
+}

package/src/commands/hosted.js

@@ -0,0 +1,39 @@
+import { createContext } from '../api/index.js';
+import { resolveGameId } from '../config.js';
+import { withAuthHandling } from '../auth/session.js';
+import { CliError, ExitCode } from '../errors.js';
+import { ui } from '../ui/index.js';
+import { quoteHostedRun, runHostedQuote, hostedQuoteLines } from '../hosted/recordedRun.js';
+
+export async function hostedQuote(flags = {}, deps = {}) {
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const result = await quoteHostedRun({ api: context.api, apiUrl: context.api.apiUrl,
+      gameId: resolveGameId(flags, context.config), buildId: flags.build, profileVersion: flags.profile,
+      persona: flags.persona, standardProvider: flags.standardProvider, includeVideo: Boolean(flags.video),
+      includeTranscript: Boolean(flags.transcript), output: flags.output });
+    if (flags.json) ui.json(result);
+    else {
+      hostedQuoteLines(result).forEach(line => ui.info(line));
+      ui.ok(`Saved ${result.quoteFile}. No admission or charge was requested.`);
+    }
+    return ExitCode.OK;
+  });
+}
+
+export async function hostedRun(filename, flags = {}, deps = {}) {
+  if (flags.json && !flags.yes && !deps.confirm) throw new CliError('Inspect the saved quote, then use --yes with --json. No admission was requested.');
+  const context = deps.context || await createContext({ apiUrl: flags.apiUrl, repoRoot: flags.repoRoot, requireAuth: true });
+  return withAuthHandling(context, async () => {
+    const result = await runHostedQuote({ filename, api: context.api, apiUrl: context.api.apiUrl, repoRoot: context.repoRoot,
+      confirm: deps.confirm || (question => ui.confirm(question, { yes: Boolean(flags.yes) })),
+      onPrepared: offer => { if (!flags.json) hostedQuoteLines(offer).forEach(line => ui.info(line)); } });
+    if (flags.json) ui.json(result);
+    else if (result.state === 'declined') ui.info('Hosted quote declined. No admission was requested.');
+    else {
+      ui.ok(`Admission ${result.admissionId}; job ${result.jobId}. Saved ${result.journal}.`);
+      ui.info('The server acknowledged charged_blocked. This does not prove a worker started or produced gameplay or reports.');
+    }
+    return result.state === 'declined' ? ExitCode.CANCELED : ExitCode.OK;
+  });
+}

package/src/commands/run.js

@@ -870,11 +870,11 @@ export async function deliver({ deps, api, gameId, jobId, runId, directory, outc
         body
       });
     } catch (error) {
-      // A server older than partial reports refuses one as `invalid_report`.
-      // The uploads are already done by then, so the run is completed
-      // without it rather than left open: the notes stay on disk in
-      // report.json either way.
-      if (!(body.report && body.report.partial && error && error.status === 422 && error.code === 'invalid_report')) throw error;
+      // A server older than partial reports refuses one as `invalid_report`,
+      // and any server refuses one with a secret shaped value in it. The
+      // uploads are already done by then, so the run is completed without it
+      // rather than left open: the notes stay on disk in report.json either way.
+      if (!(body.report && body.report.partial && error && error.status === 422 && ['invalid_report', 'secrets_detected'].includes(error.code))) throw error;
       log(`run ${runId}: the server refused the partial report (${String(error.message)}), so the run is completed without it. The notes are in ${directory}.`);
       if (delivery) delivery.reportRefused = true;
       const { report: ignored, report_md: alsoIgnored, ...withoutReport } = body;
@@ -1037,7 +1037,10 @@ async function aggregatePhase({
 
   // The aggregate reads reports off disk, so a resumed job whose earlier runs
   // were played by a previous process is covered too.
-  const reports = await loadRunReports(repoRoot, jobId, personaRuns, journal);
+  // A failed run's report explains the failure and its unit is refunded. It is
+  // not a result to summarise, and the server refuses a summary of only those.
+  const reports = (await loadRunReports(repoRoot, jobId, personaRuns, journal))
+    .map(run => (run.state === 'failed' ? { ...run, report: null } : run));
   let aggregate;
   try {
     aggregate = await buildAggregate({

package/src/hosted/archivePreflight.js

@@ -0,0 +1,240 @@
+import { constants } from 'node:fs';
+import { open, lstat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { createInflateRaw } from 'node:zlib';
+import { CliError } from '../errors.js';
+
+export const LEGACY_BUILD_LIMITS = Object.freeze({ archiveBytes: 64 * 1024 ** 2,
+  expandedBytes: 512 * 1024 ** 2, fileBytes: 64 * 1024 ** 2, files: 1000, depth: 16, ratio: 100,
+  archiveFormats: Object.freeze(['zip']), zip64: false });
+// These parser bounds cap metadata/memory even when an operator declares a
+// much larger byte budget. They do not advertise server or engine capacity.
+const MAX_DIRECTORY_BYTES = 64 * 1024 ** 2;
+const MAX_ENTRIES = 1_000_000;
+const MAX_PATH_BYTES = 1024;
+const reject = reason => { throw new CliError(`Build preflight failed: ${reason}. No upload reservation was requested.`); };
+const integer = value => Number.isSafeInteger(value) && value > 0;
+const same = (a, b) => ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs'].every(key => a[key] === b[key]);
+
+export function buildLimits(value = LEGACY_BUILD_LIMITS) {
+  const keys = ['archiveBytes', 'expandedBytes', 'fileBytes', 'files', 'depth', 'ratio'];
+  if (!value || keys.some(key => !integer(value[key]))) reject('the selected build limits are incomplete');
+  if (value.files > MAX_ENTRIES || value.depth > 128 || value.ratio > 10000) reject('the selected limits exceed this client’s bounded metadata parser');
+  if (value.archiveFormats !== undefined && (!Array.isArray(value.archiveFormats) || value.archiveFormats.length !== 1 || value.archiveFormats[0] !== 'zip')
+    || value.zip64 !== undefined && typeof value.zip64 !== 'boolean') reject('the selected archive policy is unsupported');
+  return { ...Object.fromEntries(keys.map(key => [key, value[key]])), archiveFormats: ['zip'], zip64: value.zip64 === true };
+}
+
+export function limitsFromProfile(profile) {
+  if (profile?.capacity?.version !== 1) reject('the selected profile does not declare a supported capacity schema');
+  return buildLimits(profile.capacity.uploadLimits);
+}
+
+function safePath(value, depth, directory = false) {
+  if (!value || Buffer.byteLength(value) > MAX_PATH_BYTES || /[\\\x00-\x1f\x7f:]/.test(value) || value.startsWith('/')) reject('an archive path is unsafe');
+  const name = directory && value.endsWith('/') ? value.slice(0, -1) : value;
+  const parts = name.split('/');
+  if (parts.length > depth || parts.some(part => !part || part === '.' || part === '..' || part.length > 255
+    || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))
+    || !/^[A-Za-z0-9_./ +@()=-]+$/.test(name)) reject('an archive path is not portable or exceeds the selected depth');
+  return name;
+}
+
+function number64(bytes, offset) {
+  const value = bytes.readBigUInt64LE(offset);
+  if (value > BigInt(Number.MAX_SAFE_INTEGER)) reject('a ZIP64 offset or size cannot be represented safely');
+  return Number(value);
+}
+
+// A descriptor owns one open file throughout preflight, hash and upload. The
+// pathname is never reopened for transfer after consent. No file-size buffer.
+export async function openBuildArchive(filename, { signal, onRead } = {}) {
+  const before = await lstat(filename, { bigint: true });
+  if (!before.isFile() || before.isSymbolicLink()) reject('choose a regular ZIP file');
+  const handle = await open(filename, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const stat = await handle.stat({ bigint: true });
+    if (!same(before, stat) || stat.size > BigInt(Number.MAX_SAFE_INTEGER)) reject('the archive changed while opening');
+    let closed = false;
+    const check = async () => {
+      if (closed || signal?.aborted) reject('the archive operation was stopped');
+      if (!same(stat, await handle.stat({ bigint: true }))) reject('the archive changed; run preflight again');
+    };
+    const read = async (offset, length) => {
+      if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) || offset < 0 || length < 0
+        || length > 65557 || offset + length > Number(stat.size)) reject('an archive record extends outside the file');
+      await check();
+      const bytes = Buffer.alloc(length); let done = 0;
+      while (done < length) {
+        const result = await handle.read(bytes, done, length - done, offset + done);
+        if (!result.bytesRead) reject('the archive is truncated');
+        done += result.bytesRead;
+      }
+      onRead?.(length); return bytes;
+    };
+    return { size: Number(stat.size), read, check,
+      async sha256({ onProgress } = {}) {
+        const hash = createHash('sha256');
+        for (let at = 0; at < Number(stat.size); at += 65536) {
+          const chunk = await read(at, Math.min(65536, Number(stat.size) - at));
+          hash.update(chunk); onProgress?.(at + chunk.length, Number(stat.size));
+        }
+        await check(); return hash.digest('hex');
+      },
+      async *chunks({ start = 0, end = Number(stat.size), onProgress } = {}) {
+        if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start < 0 || end < start || end > Number(stat.size)) reject('the upload range is invalid');
+        for (let at = start; at < end; at += 65536) {
+          const chunk = await read(at, Math.min(65536, end - at));
+          yield chunk; onProgress?.(at + chunk.length - start, end - start);
+        }
+        await check();
+      },
+      async close() { if (!closed) { closed = true; await handle.close(); } }
+    };
+  } catch (error) { await handle.close(); throw error; }
+}
+
+async function directory(archive, limits) {
+  if (archive.size < 22 || archive.size > limits.archiveBytes) reject('the ZIP exceeds the selected upload size or is truncated');
+  const tailStart = Math.max(0, archive.size - 65557), tail = await archive.read(tailStart, archive.size - tailStart);
+  let eocd = -1;
+  for (let at = tail.length - 22; at >= 0; at--) {
+    if (tail.readUInt32LE(at) === 0x06054b50 && at + 22 + tail.readUInt16LE(at + 20) === tail.length) { eocd = at; break; }
+  }
+  if (eocd < 0) reject('the ZIP directory is missing');
+  const record = tail.subarray(eocd), end = tailStart + eocd;
+  if (record.readUInt16LE(4) || record.readUInt16LE(6) || record.readUInt16LE(8) !== record.readUInt16LE(10)) reject('split ZIP archives are unsupported');
+  let count = record.readUInt16LE(10), size = record.readUInt32LE(12), offset = record.readUInt32LE(16), boundary = end;
+  const locator = end >= 20 ? await archive.read(end - 20, 20) : null;
+  const zip64 = locator?.readUInt32LE(0) === 0x07064b50;
+  if (zip64 && !limits.zip64) reject('the selected profile does not accept ZIP64');
+  if (zip64) {
+    if (locator.readUInt32LE(4) || locator.readUInt32LE(16) !== 1) reject('split ZIP64 archives are unsupported');
+    boundary = number64(locator, 8);
+    const expanded = await archive.read(boundary, 56);
+    if (expanded.readUInt32LE(0) !== 0x06064b50 || number64(expanded, 4) < 44
+      || number64(expanded, 4) > 1024 || boundary + 12 + number64(expanded, 4) !== end - 20
+      || expanded.readUInt32LE(16) || expanded.readUInt32LE(20) || number64(expanded, 24) !== number64(expanded, 32)) reject('the ZIP64 directory is invalid');
+    const values = [number64(expanded, 32), number64(expanded, 40), number64(expanded, 48)];
+    if ([count, size, offset].some((value, i) => value !== (i ? 0xffffffff : 0xffff) && value !== values[i])) reject('ZIP and ZIP64 directories disagree');
+    [count, size, offset] = values;
+  } else if (count === 0xffff || size === 0xffffffff || offset === 0xffffffff) reject('the ZIP64 locator is missing');
+  if (!count || count > limits.files || count > MAX_ENTRIES) reject('the ZIP entry count exceeds the selected limit');
+  if (size > MAX_DIRECTORY_BYTES || size < count * 46 || offset + size !== boundary) reject('the ZIP directory exceeds the bounded metadata budget or is inconsistent');
+  return { count, size, offset, zip64 };
+}
+
+function sizes(header, extra) {
+  let expanded = header.readUInt32LE(24), compressed = header.readUInt32LE(20), offset = header.readUInt32LE(42), disk = header.readUInt16LE(34);
+  let zip64;
+  for (let at = 0; at < extra.length;) {
+    if (at + 4 > extra.length) reject('a ZIP extra field is truncated');
+    const kind = extra.readUInt16LE(at), size = extra.readUInt16LE(at + 2); at += 4;
+    if (at + size > extra.length) reject('a ZIP extra field is truncated');
+    if (kind === 1) { if (zip64) reject('duplicate ZIP64 extra fields'); zip64 = extra.subarray(at, at + size); }
+    at += size;
+  }
+  let at = 0;
+  const next = () => { if (!zip64 || at + 8 > zip64.length) reject('a ZIP64 file size is missing'); const value = number64(zip64, at); at += 8; return value; };
+  if (expanded === 0xffffffff) expanded = next();
+  if (compressed === 0xffffffff) compressed = next();
+  if (offset === 0xffffffff) offset = next();
+  if (disk === 0xffff) { if (!zip64 || at + 4 > zip64.length) reject('a ZIP64 disk field is missing'); disk = zip64.readUInt32LE(at); }
+  if (disk) reject('split ZIP archives are unsupported');
+  return { expanded, compressed, offset };
+}
+
+async function prefix(archive, file, length) {
+  if (length > 1024 ** 2 || length > file.expanded) reject('the native executable header is outside the bounded metadata window');
+  const source = Readable.from(archive.chunks({ start: file.dataOffset, end: file.dataEnd }), { objectMode: false, highWaterMark: 65536 });
+  const output = file.method === 8 ? source.pipe(createInflateRaw({ chunkSize: 16384 })) : source;
+  const parts = []; let total = 0;
+  const timer = setTimeout(() => { source.destroy(Error('header timeout')); output.destroy(Error('header timeout')); }, 5000);
+  source.on('error', error => output.destroy(error));
+  try {
+    for await (const chunk of output) {
+      const take = chunk.subarray(0, length - total); parts.push(take); total += take.length;
+      if (total === length) return Buffer.concat(parts, total);
+    }
+    reject('the native executable header is truncated');
+  } catch { reject('the native executable header could not be inspected within its bound'); }
+  finally { clearTimeout(timer); source.destroy(); output.destroy(); }
+}
+
+async function nativeHeader(archive, file, format, requirements) {
+  const os = format === 'linux-executable' ? 'linux' : 'windows';
+  if (requirements?.os !== os || !['arm64', 'x86_64'].includes(requirements.architecture)) reject('the native format does not match the selected profile requirements');
+  const header = await prefix(archive, file, 64); let architecture, binaryFormat;
+  if (os === 'linux') {
+    if (header.subarray(0, 4).toString('hex') !== '7f454c46' || header[4] !== 2 || header[5] !== 1 || header[6] !== 1
+      || ![2, 3].includes(header.readUInt16LE(16))) reject('the Linux entrypoint must be a little-endian ELF64 executable');
+    architecture = { 62: 'x86_64', 183: 'arm64' }[header.readUInt16LE(18)]; binaryFormat = 'ELF64';
+  } else {
+    if (header.subarray(0, 2).toString() !== 'MZ') reject('the Windows entrypoint must be a PE executable');
+    const at = header.readUInt32LE(60);
+    if (at < 64 || at > 1024 ** 2 - 26) reject('the PE header offset exceeds the bounded metadata window');
+    const pe = await prefix(archive, file, at + 26);
+    if (pe.readUInt32LE(at) !== 0x00004550 || pe.readUInt16LE(at + 24) !== 0x20b) reject('the Windows entrypoint must be a PE32+ executable');
+    architecture = { 0x8664: 'x86_64', 0xaa64: 'arm64' }[pe.readUInt16LE(at + 4)]; binaryFormat = 'PE32+';
+  }
+  if (architecture !== requirements.architecture) reject('the executable architecture does not match the selected profile');
+  return { os, architecture, binaryFormat, runtimeCompatibilityProven: false };
+}
+
+export async function inspectBuildArchive(archive, { limits: supplied, format, entrypoint, requirements } = {}) {
+  const limits = buildLimits(supplied);
+  if (!['web', 'godot-project', 'linux-executable', 'windows-executable'].includes(format)) reject('the selected runtime format is unsupported');
+  if (typeof entrypoint !== 'string' || entrypoint.length > 240 || !/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(entrypoint)) reject('the entrypoint does not match the current server path policy');
+  const wanted = safePath(entrypoint, limits.depth);
+  if (format === 'web' && !wanted.endsWith('.html') || format === 'godot-project' && wanted.split('/').at(-1) !== 'project.godot'
+    || format === 'windows-executable' && !wanted.toLowerCase().endsWith('.exe')) reject('the entrypoint does not match the selected format');
+  const dir = await directory(archive, limits), paths = new Map(), explicit = new Set(), ranges = [];
+  let cursor = dir.offset, expandedBytes = 0, files = 0, found = false, pathBytes = 0, nativeFile;
+  for (let index = 0; index < dir.count; index++) {
+    const h = await archive.read(cursor, 46);
+    if (h.readUInt32LE(0) !== 0x02014b50) reject('a ZIP directory entry is invalid');
+    const flags = h.readUInt16LE(8), method = h.readUInt16LE(10), nameBytes = h.readUInt16LE(28), extraBytes = h.readUInt16LE(30), commentBytes = h.readUInt16LE(32);
+    if (flags & 0x41 || ![0, 8].includes(method)) reject('encrypted or unsupported ZIP compression');
+    if (!nameBytes || nameBytes > MAX_PATH_BYTES || cursor + 46 + nameBytes + extraBytes + commentBytes > dir.offset + dir.size) reject('a ZIP directory entry is oversized');
+    const nameBuffer = await archive.read(cursor + 46, nameBytes), nameText = nameBuffer.toString('utf8');
+    const isDirectory = nameText.endsWith('/'), name = safePath(nameText, limits.depth, isDirectory), folded = name.toLowerCase();
+    if (explicit.has(folded)) reject('duplicate ZIP paths'); explicit.add(folded);
+    const parts = name.split('/');
+    for (let n = 1; n <= parts.length; n++) {
+      const prefix = parts.slice(0, n).join('/'), key = prefix.toLowerCase(), kind = n < parts.length || isDirectory ? 'directory' : 'file', prior = paths.get(key);
+      if (prior && (prior.name !== prefix || prior.kind !== kind)) reject('colliding ZIP paths');
+      if (!prior) { pathBytes += Buffer.byteLength(prefix); if (pathBytes > MAX_DIRECTORY_BYTES) reject('the ZIP path index exceeds the bounded metadata budget'); }
+      paths.set(key, { name: prefix, kind });
+    }
+    const mode = h.readUInt32LE(38) >>> 16, type = mode & 0xf000;
+    if (type && type !== (isDirectory ? 0x4000 : 0x8000) || mode & 0x0e00 || !isDirectory && h.readUInt32LE(38) & 0x10) reject('links, devices or privileged ZIP entries are unsupported');
+    const extra = await archive.read(cursor + 46 + nameBytes, extraBytes), size = sizes(h, extra);
+    if (size.expanded > limits.fileBytes || BigInt(size.expanded) > BigInt(Math.max(1, size.compressed)) * BigInt(limits.ratio)) reject('a file exceeds the selected size or compression-ratio limit');
+    if (isDirectory && (size.expanded || size.compressed)) reject('a ZIP directory contains file data');
+    expandedBytes += size.expanded;
+    if (!Number.isSafeInteger(expandedBytes) || expandedBytes > limits.expandedBytes) reject('the expanded build exceeds the selected limit');
+    const local = await archive.read(size.offset, 30);
+    if (local.readUInt32LE(0) !== 0x04034b50 || local.readUInt16LE(6) !== flags || local.readUInt16LE(8) !== method
+      || local.readUInt16LE(26) !== nameBytes) reject('local and central ZIP headers disagree');
+    if (!(await archive.read(size.offset + 30, nameBytes)).equals(nameBuffer)) reject('local and central ZIP filenames disagree');
+    const dataEnd = size.offset + 30 + nameBytes + local.readUInt16LE(28) + size.compressed;
+    if (!Number.isSafeInteger(dataEnd) || dataEnd > dir.offset) reject('file data overlaps the ZIP directory');
+    ranges.push([size.offset, dataEnd]);
+    if (!isDirectory) { files++; if (name === wanted) { if (!size.expanded) reject('the entrypoint is empty'); found = true;
+      nativeFile = { ...size, method, dataOffset: size.offset + 30 + nameBytes + local.readUInt16LE(28), dataEnd }; } }
+    cursor += 46 + nameBytes + extraBytes + commentBytes;
+  }
+  if (cursor !== dir.offset + dir.size || !found) reject('the declared entrypoint is absent or the directory is inconsistent');
+  ranges.sort((a, b) => a[0] - b[0]);
+  for (let i = 1; i < ranges.length; i++) if (ranges[i][0] < ranges[i - 1][1]) reject('ZIP file data overlaps');
+  await archive.check();
+  const nativeBinaryMetadata = format.endsWith('-executable') ? await nativeHeader(archive, nativeFile, format, requirements) : null;
+  return { archiveBytes: archive.size, expandedBytes, entries: dir.count, files, format, entrypoint: wanted,
+    zip64: dir.zip64, metadataVerified: true, nativeBinaryMetadata, contentsVerified: false, serverValidationRequired: true, runtimeCompatibilityProven: false };
+}
+
+export async function preflightBuildArchive(filename, options) {
+  const archive = await openBuildArchive(filename, options);
+  try { return await inspectBuildArchive(archive, options); } finally { await archive.close(); }
+}