diff --git a/.github/workflows/browser-demos-pages.yml b/.github/workflows/browser-demos-pages.yml
index 6b24955cfc..68e4a38851 100644
--- a/.github/workflows/browser-demos-pages.yml
+++ b/.github/workflows/browser-demos-pages.yml
@@ -107,8 +107,9 @@ jobs:
# bottle member. Repeating selection or extraction here could make
# inspection and the bytes actually served by Vite disagree.
bootstrap="$PWD/apps/browser-demos/public/homebrew-bootstrap.zip"
+ portable_ruby="$PWD/apps/browser-demos/public/homebrew-portable-ruby.zip"
report="$RUNNER_TEMP/homebrew-main-shell-public-product.json"
- for path in "$image" "$bootstrap"; do
+ for path in "$image" "$bootstrap" "$portable_ruby"; do
test -f "$path"
test ! -L "$path"
done
@@ -125,6 +126,7 @@ jobs:
scripts/inspect-homebrew-main-shell-public-product.ts \
--image "$image" \
--homebrew-bootstrap-archive "$bootstrap" \
+ --homebrew-portable-ruby-archive "$portable_ruby" \
--homebrew-bootstrap-spec \
homebrew/main-shell-brew-package-tree.json \
--homebrew-runtime-support \
@@ -137,6 +139,8 @@ jobs:
(.image.bytes > 0) and
(.homebrew_bootstrap.sha256 | test("^[0-9a-f]{64}$")) and
(.homebrew_bootstrap.bytes > 0) and
+ (.homebrew_portable_ruby.sha256 | test("^[0-9a-f]{64}$")) and
+ (.homebrew_portable_ruby.bytes > 0) and
.homebrew_bootstrap.activation_root == "/usr/bin/brew" and
(.bottle_mirror.plan_url |
startswith("https://github.com/") and
@@ -146,6 +150,7 @@ jobs:
{
echo "image=$image"
echo "bootstrap=$bootstrap"
+ echo "portable_ruby=$portable_ruby"
echo "image_sha256=$(jq -er '.image.sha256' "$report")"
echo "bootstrap_sha256=$(jq -er \
'.homebrew_bootstrap.sha256' "$report")"
@@ -165,6 +170,8 @@ jobs:
npm run build
cmp "${{ steps.shell_product.outputs.bootstrap }}" \
dist/homebrew-bootstrap.zip
+ cmp "${{ steps.shell_product.outputs.portable_ruby }}" \
+ dist/homebrew-portable-ruby.zip
# WHY: Vite imports the resolver-selected shell under a hashed asset
# name. Verify that exact emitted asset; an unhashed public copy can
# be absent or stale without affecting the image the browser boots.
diff --git a/.github/workflows/homebrew-main-shell-ci.yml b/.github/workflows/homebrew-main-shell-ci.yml
index 1e3161a3fd..d3c6bb3a46 100644
--- a/.github/workflows/homebrew-main-shell-ci.yml
+++ b/.github/workflows/homebrew-main-shell-ci.yml
@@ -683,9 +683,11 @@ jobs:
--output-directory "$prepared_inputs"
bootstrap_root="$prepared_inputs/bootstrap"
bootstrap="$bootstrap_root/homebrew-bootstrap.zip"
+ portable_ruby="$bootstrap_root/homebrew-portable-ruby.zip"
bootstrap_env="$bootstrap_root/homebrew-brew.env"
bootstrap_bottle_report="$bootstrap_root/report.json"
test -f "$bootstrap"
+ test -f "$portable_ruby"
test -f "$bootstrap_env"
test -f "$bootstrap_bottle_report"
artifact_state=$(jq -er '.state' \
@@ -727,6 +729,7 @@ jobs:
echo "image=$candidate_root/main-shell.vfs.zst"
echo "report=$candidate_root/main-shell-report.json"
echo "bootstrap=$bootstrap"
+ echo "portable_ruby=$portable_ruby"
echo "bootstrap_env=$bootstrap_env"
echo "bootstrap_bottle_report=$bootstrap_bottle_report"
echo "tap_sha=$tap_sha"
@@ -975,6 +978,7 @@ jobs:
--image "${{ steps.bottle_candidate.outputs.image }}" \
--homebrew-bootstrap-spec homebrew/main-shell-brew-package-tree.json \
--homebrew-bootstrap-archive "${{ steps.bottle_candidate.outputs.bootstrap }}" \
+ --homebrew-portable-ruby-archive "${{ steps.bottle_candidate.outputs.portable_ruby }}" \
--homebrew-bootstrap-env "${{ steps.bottle_candidate.outputs.bootstrap_env }}" \
--bottle-mirror "$RUNNER_TEMP/homebrew-main-shell-bottles" \
--fixed-asset-url-root "$fixed_url_root" \
@@ -999,6 +1003,7 @@ jobs:
install_browser_fixture_asset "${{ steps.bottle_candidate.outputs.image }}"
install_browser_fixture_asset homebrew/main-shell-brew-package-tree.json
install_browser_fixture_asset "${{ steps.bottle_candidate.outputs.bootstrap }}"
+ install_browser_fixture_asset "${{ steps.bottle_candidate.outputs.portable_ruby }}"
install_browser_fixture_asset "${{ steps.bottle_candidate.outputs.bootstrap_env }}"
echo "fixture=$fixture" >> "$GITHUB_OUTPUT"
@@ -1032,6 +1037,8 @@ jobs:
if [ "$SHELL_ACTIVATION_MODE" = bottles ]; then
cmp "${{ steps.bottle_candidate.outputs.bootstrap }}" \
dist/homebrew-bootstrap.zip
+ cmp "${{ steps.bottle_candidate.outputs.portable_ruby }}" \
+ dist/homebrew-portable-ruby.zip
fi
- name: Boot the exact installed bytes in Node
@@ -1053,6 +1060,7 @@ jobs:
--migration-lock homebrew/main-shell-migration-lock.json
--homebrew-bootstrap-spec homebrew/main-shell-brew-package-tree.json
--homebrew-bootstrap-archive "${{ steps.bottle_candidate.outputs.bootstrap }}"
+ --homebrew-portable-ruby-archive "${{ steps.bottle_candidate.outputs.portable_ruby }}"
--homebrew-bootstrap-env "${{ steps.bottle_candidate.outputs.bootstrap_env }}"
--homebrew-bootstrap-state deferred
--homebrew-runtime-support homebrew/main-shell-homebrew-runtime-support.json
@@ -1091,6 +1099,7 @@ jobs:
--image "${{ steps.bottle_candidate.outputs.image }}" \
--homebrew-bootstrap-spec homebrew/main-shell-brew-package-tree.json \
--homebrew-bootstrap-archive "${{ steps.bottle_candidate.outputs.bootstrap }}" \
+ --homebrew-portable-ruby-archive "${{ steps.bottle_candidate.outputs.portable_ruby }}" \
--homebrew-bootstrap-env "${{ steps.bottle_candidate.outputs.bootstrap_env }}" \
--transport-mode closed \
--bottle-mirror-plan "${{ steps.mirror.outputs.plan }}" \
@@ -1220,6 +1229,7 @@ jobs:
${{ steps.source_candidate.outputs.manifest }}
${{ steps.bottle_candidate.outputs.report }}
${{ steps.bottle_candidate.outputs.bootstrap }}
+ ${{ steps.bottle_candidate.outputs.portable_ruby }}
${{ steps.bottle_candidate.outputs.bootstrap_env }}
${{ steps.bottle_candidate.outputs.bootstrap_bottle_report }}
${{ runner.temp }}/homebrew-main-shell-bottles
diff --git a/.github/workflows/reusable-homebrew-main-shell-mirror-publish.yml b/.github/workflows/reusable-homebrew-main-shell-mirror-publish.yml
index 24d054b4c1..de6b2319e1 100644
--- a/.github/workflows/reusable-homebrew-main-shell-mirror-publish.yml
+++ b/.github/workflows/reusable-homebrew-main-shell-mirror-publish.yml
@@ -242,8 +242,9 @@ jobs:
--require-sealed \
--output-directory "$bootstrap_root"
bootstrap="$bootstrap_root/homebrew-bootstrap.zip"
+ portable_ruby="$bootstrap_root/homebrew-portable-ruby.zip"
bootstrap_env="$bootstrap_root/homebrew-brew.env"
- for path in "$image" "$bootstrap" "$bootstrap_env"; do
+ for path in "$image" "$bootstrap" "$portable_ruby" "$bootstrap_env"; do
test -f "$path"
test ! -L "$path"
done
@@ -254,6 +255,7 @@ jobs:
{
echo "image=$image"
echo "bootstrap=$bootstrap"
+ echo "portable-ruby=$portable_ruby"
echo "bootstrap-env=$bootstrap_env"
} >>"$GITHUB_OUTPUT"
@@ -305,6 +307,7 @@ jobs:
env:
IMAGE: ${{ steps.shell.outputs.image }}
BOOTSTRAP: ${{ steps.shell.outputs.bootstrap }}
+ PORTABLE_RUBY: ${{ steps.shell.outputs.portable-ruby }}
BOOTSTRAP_ENV: ${{ steps.shell.outputs.bootstrap-env }}
MIRROR: ${{ steps.mirror.outputs.root }}
PUBLISH: ${{ steps.mirror.outputs.publish }}
@@ -321,6 +324,7 @@ jobs:
mkdir "$handoff"
cp "$IMAGE" "$handoff/main-shell.vfs.zst"
cp "$BOOTSTRAP" "$handoff/homebrew-bootstrap.zip"
+ cp "$PORTABLE_RUBY" "$handoff/homebrew-portable-ruby.zip"
cp "$BOOTSTRAP_ENV" "$handoff/homebrew-brew.env"
cp "$PUBLISH" "$handoff/publish.json"
cp -R "$MIRROR" "$handoff/mirror"
@@ -345,6 +349,8 @@ jobs:
--argjson image_bytes "$(bytes "$handoff/main-shell.vfs.zst")" \
--arg bootstrap_sha "$(digest "$handoff/homebrew-bootstrap.zip")" \
--argjson bootstrap_bytes "$(bytes "$handoff/homebrew-bootstrap.zip")" \
+ --arg portable_ruby_sha "$(digest "$handoff/homebrew-portable-ruby.zip")" \
+ --argjson portable_ruby_bytes "$(bytes "$handoff/homebrew-portable-ruby.zip")" \
--arg env_sha "$(digest "$handoff/homebrew-brew.env")" \
--argjson env_bytes "$(bytes "$handoff/homebrew-brew.env")" \
--arg publish_sha "$(digest "$handoff/publish.json")" \
@@ -367,6 +373,9 @@ jobs:
"homebrew-bootstrap.zip": {
sha256: $bootstrap_sha, bytes: $bootstrap_bytes
},
+ "homebrew-portable-ruby.zip": {
+ sha256: $portable_ruby_sha, bytes: $portable_ruby_bytes
+ },
"homebrew-brew.env": {
sha256: $env_sha, bytes: $env_bytes
},
@@ -408,6 +417,7 @@ jobs:
env:
IMAGE: ${{ steps.shell.outputs.image }}
BOOTSTRAP: ${{ steps.shell.outputs.bootstrap }}
+ PORTABLE_RUBY: ${{ steps.shell.outputs.portable-ruby }}
BOOTSTRAP_ENV: ${{ steps.shell.outputs.bootstrap-env }}
MIRROR_PLAN: ${{ steps.mirror.outputs.root }}/kandelo-homebrew-bottle-mirror-plan.json
KANDELO_REF: ${{ inputs.kandelo-ref }}
@@ -431,6 +441,7 @@ jobs:
--homebrew-bootstrap-spec \
homebrew/main-shell-brew-package-tree.json \
--homebrew-bootstrap-archive "$BOOTSTRAP" \
+ --homebrew-portable-ruby-archive "$PORTABLE_RUBY" \
--homebrew-bootstrap-env "$BOOTSTRAP_ENV" \
--bottle-mirror-plan "$MIRROR_PLAN" \
--kandelo-ref "$KANDELO_REF" \
@@ -627,7 +638,7 @@ jobs:
.repository == "kandelo-dev/homebrew-tap-core" and
.target_commitish == $tap and
.immutable == true and
- (.assets | length) == 4
+ (.assets | length) == 5
' "$lifecycle_receipt" >/dev/null
{
echo "mirror-receipt=$mirror_receipt"
@@ -789,6 +800,7 @@ jobs:
main-shell.vfs.zst \
main-shell-brew-package-tree.json \
homebrew-bootstrap.zip \
+ homebrew-portable-ruby.zip \
homebrew-brew.env
do
env -u GH_TOKEN -u GITHUB_TOKEN \
@@ -803,11 +815,14 @@ jobs:
"$lifecycle/main-shell-brew-package-tree.json"
cmp "$handoff/homebrew-bootstrap.zip" \
"$lifecycle/homebrew-bootstrap.zip"
+ cmp "$handoff/homebrew-portable-ruby.zip" \
+ "$lifecycle/homebrew-portable-ruby.zip"
cmp "$handoff/homebrew-brew.env" \
"$lifecycle/homebrew-brew.env"
{
echo "image=$lifecycle/main-shell.vfs.zst"
echo "bootstrap=$lifecycle/homebrew-bootstrap.zip"
+ echo "portable-ruby=$lifecycle/homebrew-portable-ruby.zip"
echo "bootstrap-env=$lifecycle/homebrew-brew.env"
} >>"$GITHUB_OUTPUT"
@@ -825,6 +840,7 @@ jobs:
env:
IMAGE: ${{ steps.public.outputs.image }}
BOOTSTRAP: ${{ steps.public.outputs.bootstrap }}
+ PORTABLE_RUBY: ${{ steps.public.outputs.portable-ruby }}
BOOTSTRAP_ENV: ${{ steps.public.outputs.bootstrap-env }}
TAP_CATALOG_REF: ${{ inputs.tap-catalog-ref }}
CANARY_REF: ${{ inputs.canary-ref }}
@@ -839,6 +855,7 @@ jobs:
env:
IMAGE: ${{ steps.public.outputs.image }}
BOOTSTRAP: ${{ steps.public.outputs.bootstrap }}
+ PORTABLE_RUBY: ${{ steps.public.outputs.portable-ruby }}
BOOTSTRAP_ENV: ${{ steps.public.outputs.bootstrap-env }}
TAP_CATALOG_REF: ${{ inputs.tap-catalog-ref }}
CANARY_REF: ${{ inputs.canary-ref }}
@@ -980,9 +997,11 @@ jobs:
lifecycle="$RUNNER_TEMP/homebrew-guest-lifecycle-inputs-handoff"
image="$(bash scripts/resolve-binary.sh programs/shell.vfs.zst)"
bootstrap="$PWD/apps/browser-demos/public/homebrew-bootstrap.zip"
+ portable_ruby="$PWD/apps/browser-demos/public/homebrew-portable-ruby.zip"
bootstrap_env="$lifecycle/homebrew-brew.env"
cmp "$image" "$handoff/main-shell.vfs.zst"
cmp "$bootstrap" "$handoff/homebrew-bootstrap.zip"
+ cmp "$portable_ruby" "$handoff/homebrew-portable-ruby.zip"
cmp "$bootstrap_env" "$handoff/homebrew-brew.env"
plan="$handoff/mirror/kandelo-homebrew-bottle-mirror-plan.json"
plan_url="$(jq -er '.release_root + "/" + .manifest_asset' "$plan")"
@@ -994,6 +1013,7 @@ jobs:
main-shell.vfs.zst \
main-shell-brew-package-tree.json \
homebrew-bootstrap.zip \
+ homebrew-portable-ruby.zip \
homebrew-brew.env
do
env -u GH_TOKEN -u GITHUB_TOKEN \
@@ -1006,10 +1026,12 @@ jobs:
cmp homebrew/main-shell-brew-package-tree.json \
"$lifecycle/main-shell-brew-package-tree.json"
cmp "$bootstrap" "$lifecycle/homebrew-bootstrap.zip"
+ cmp "$portable_ruby" "$lifecycle/homebrew-portable-ruby.zip"
cmp "$bootstrap_env" "$lifecycle/homebrew-brew.env"
{
echo "image=$image"
echo "bootstrap=$bootstrap"
+ echo "portable-ruby=$portable_ruby"
echo "bootstrap-env=$bootstrap_env"
echo "plan-url=$plan_url"
echo "image-sha=$(sha256sum "$image" | awk '{print $1}')"
@@ -1027,12 +1049,17 @@ jobs:
run: |
set -euo pipefail
browser_bootstrap=public/homebrew-bootstrap.zip
+ browser_portable_ruby=public/homebrew-portable-ruby.zip
test -f "$browser_bootstrap"
test ! -L "$browser_bootstrap"
+ test -f "$browser_portable_ruby"
+ test ! -L "$browser_portable_ruby"
# WHY: prepare-browser owns this fixed same-origin asset. The build
# must consume those admitted bytes instead of silently replacing
# them from a second package source.
cmp "${{ steps.public.outputs.bootstrap }}" "$browser_bootstrap"
+ cmp "${{ steps.public.outputs.portable-ruby }}" \
+ "$browser_portable_ruby"
# WHY: dev-shell intentionally drops ambient variables. Forward the
# selector or Vite builds its default pages and omits the proof page.
bash ../../scripts/dev-shell.sh env \
@@ -1043,6 +1070,8 @@ jobs:
test -f dist/pages/homebrew-vfs-test/index.html
cmp "${{ steps.public.outputs.bootstrap }}" \
dist/homebrew-bootstrap.zip
+ cmp "${{ steps.public.outputs.portable-ruby }}" \
+ dist/homebrew-portable-ruby.zip
bash ../../scripts/verify-browser-shell-vfs-asset.sh \
dist "${{ steps.public.outputs.image }}"
@@ -1065,6 +1094,8 @@ jobs:
"$lifecycle/main-shell-brew-package-tree.json" \
--homebrew-bootstrap-archive \
"$lifecycle/homebrew-bootstrap.zip" \
+ --homebrew-portable-ruby-archive \
+ "$lifecycle/homebrew-portable-ruby.zip" \
--homebrew-bootstrap-env "$lifecycle/homebrew-brew.env" \
--bottle-mirror \
"$RUNNER_TEMP/main-shell-mirror-handoff/mirror" \
diff --git a/apps/browser-demos/pages/homebrew-benchmark/index.html b/apps/browser-demos/pages/homebrew-benchmark/index.html
new file mode 100644
index 0000000000..b79cc00752
--- /dev/null
+++ b/apps/browser-demos/pages/homebrew-benchmark/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ Kandelo Homebrew query benchmark
+
+
+ Preparing Homebrew query benchmark…
+
+
+
diff --git a/apps/browser-demos/pages/homebrew-benchmark/main.ts b/apps/browser-demos/pages/homebrew-benchmark/main.ts
new file mode 100644
index 0000000000..3bc2cefcdf
--- /dev/null
+++ b/apps/browser-demos/pages/homebrew-benchmark/main.ts
@@ -0,0 +1,350 @@
+import { BrowserKernel } from "@host/browser-kernel-host";
+import type { SyscallTraceEvent } from "@host/kernel-worker";
+import type { LazyDownloadEvent } from "@host/vfs/memory-fs";
+import type { ClosedLazyAsset } from "@host/vfs/closed-lazy-assets";
+import {
+ assertHomebrewQueryFixture,
+ commandScript,
+ emptyProcessCounts,
+ medianMetrics,
+ summarizeLazyDownloads,
+ type HomebrewQueryArtifact,
+ type HomebrewQueryCommand,
+ type HomebrewQueryCommandResult,
+ type HomebrewQueryFixtureManifest,
+ type HomebrewQueryNetworkAudit,
+ type HomebrewQueryProcessCounts,
+ type HomebrewQueryScenarioResult,
+} from "../../../../benchmarks/homebrew-query/contracts";
+import {
+ runHomebrewQueryScenario,
+ type HomebrewQueryMachine,
+ type HomebrewQueryMachineFactory,
+} from "../../../../benchmarks/homebrew-query/scenario";
+
+declare global {
+ interface Window {
+ __homebrewQueryBenchmarkReady: boolean;
+ __runHomebrewQueryBenchmark(
+ rounds: number,
+ auditNetwork?: boolean,
+ ): Promise<{
+ fixture: HomebrewQueryFixtureManifest;
+ rounds: HomebrewQueryScenarioResult[];
+ median: Record;
+ }>;
+ }
+}
+
+interface ProcessEvent {
+ kind: "spawn" | "exec" | "exit";
+}
+
+const COMMAND_TIMEOUT_MS = 10 * 60_000;
+const logElement = document.getElementById("log")!;
+const decoder = new TextDecoder("utf-8", { fatal: false });
+
+function log(message: string): void {
+ logElement.textContent += `${message}\n`;
+ console.log(message);
+}
+
+async function prepare(): Promise<{
+ fixture: HomebrewQueryFixtureManifest;
+ factory: BrowserHomebrewQueryMachineFactory;
+}> {
+ const fixtureParameter = new URL(location.href).searchParams.get("fixture");
+ if (!fixtureParameter) throw new Error("Homebrew benchmark fixture URL is missing");
+ const fixtureUrl = new URL(fixtureParameter, location.href);
+ const response = await fetch(fixtureUrl);
+ if (!response.ok) throw new Error(`Fixture returned HTTP ${response.status}`);
+ const fixture = await response.json();
+ assertHomebrewQueryFixture(fixture);
+ const kernel = await fetchVerifiedArtifact(fixtureUrl, fixture.kernel);
+ const lazyAssets: ClosedLazyAsset[] = [];
+ for (const artifact of fixture.lazyAssets) {
+ lazyAssets.push({
+ url: artifact.url,
+ sha256: artifact.sha256,
+ size: artifact.bytes,
+ bytes: await fetchVerifiedArtifact(fixtureUrl, artifact),
+ });
+ }
+ return {
+ fixture,
+ factory: new BrowserHomebrewQueryMachineFactory(
+ fixtureUrl,
+ fixture,
+ kernel,
+ lazyAssets,
+ ),
+ };
+}
+
+class BrowserHomebrewQueryMachineFactory
+ implements HomebrewQueryMachineFactory {
+ constructor(
+ private readonly fixtureUrl: URL,
+ private readonly fixture: HomebrewQueryFixtureManifest,
+ private readonly kernel: Uint8Array,
+ private readonly lazyAssets: ClosedLazyAsset[],
+ ) {}
+
+ async create(image: "lazy" | "eager"): Promise {
+ const artifact = image === "lazy"
+ ? this.fixture.rootfs
+ : this.fixture.eagerRootfs;
+ if (!artifact) throw new Error("Eager Homebrew query image is unavailable");
+ return new BrowserHomebrewQueryMachine(
+ this.fixture,
+ await fetchVerifiedArtifact(this.fixtureUrl, artifact),
+ this.kernel,
+ image === "lazy" ? this.lazyAssets : undefined,
+ );
+ }
+}
+
+class BrowserHomebrewQueryMachine implements HomebrewQueryMachine {
+ private readonly stdout: Uint8Array[] = [];
+ private readonly stderr: Uint8Array[] = [];
+ private readonly processEvents: ProcessEvent[] = [];
+ private readonly lazyEvents: LazyDownloadEvent[] = [];
+ private readonly diagnostics: string[] = [];
+ private readonly kernel: BrowserKernel;
+
+ constructor(
+ private readonly fixture: HomebrewQueryFixtureManifest,
+ private readonly image: Uint8Array,
+ private readonly kernelWasm: Uint8Array,
+ private readonly lazyAssets?: ClosedLazyAsset[],
+ ) {
+ this.kernel = new BrowserKernel({
+ maxWorkers: 4,
+ kernelOwnedFs: true,
+ onStdout: (value) => this.stdout.push(value.slice()),
+ onStderr: (value) => this.stderr.push(value.slice()),
+ onProcessEvent: (event) => this.processEvents.push(event),
+ onLazyDownload: (event) => this.lazyEvents.push(event),
+ onHostDiagnostic: (diagnostic) => {
+ this.diagnostics.push(
+ `pid=${diagnostic.pid} source=${diagnostic.source}: ` +
+ diagnostic.message,
+ );
+ },
+ });
+ }
+
+ async start(): Promise {
+ const startedAt = performance.now();
+ await this.kernel.initFromOwnedImage({
+ kernelWasm: wholeArrayBuffer(this.kernelWasm),
+ vfsImage: wholeArrayBuffer(this.image),
+ lazyUrlBase: this.fixture.lazyUrlBase,
+ ...(this.lazyAssets === undefined
+ ? {}
+ : { closedLazyAssets: this.lazyAssets }),
+ });
+ return performance.now() - startedAt;
+ }
+
+ async run(command: HomebrewQueryCommand): Promise {
+ const stdoutStart = this.stdout.length;
+ const stderrStart = this.stderr.length;
+ const processStart = this.processEvents.length;
+ const lazyStart = this.lazyEvents.length;
+ const diagnosticStart = this.diagnostics.length;
+ const startedAt = performance.now();
+ const spawned = await this.kernel.spawnFromVfs(
+ this.fixture.shell.path,
+ [this.fixture.shell.argv0, "-l", "-c", commandScript(command)],
+ {
+ env: this.fixture.homebrew.environment,
+ cwd: "/home/user",
+ uid: 1000,
+ gid: 1000,
+ stdin: new Uint8Array(),
+ },
+ );
+ // BrowserKernel's VFS spawn is a main-thread root event and therefore is
+ // not echoed by the worker's fork/exec event stream.
+ this.processEvents.push({ kind: "spawn" });
+ const status = await withTimeout(
+ spawned.exit,
+ COMMAND_TIMEOUT_MS,
+ `Homebrew query timed out: ${command.id}`,
+ );
+ const elapsedMs = performance.now() - startedAt;
+ const stdout = concatenate(this.stdout.slice(stdoutStart));
+ const stderr = concatenate(this.stderr.slice(stderrStart));
+ const invalidQueryOutput = command.id !== "shell_boot" && (
+ stdout.byteLength === 0 || stderr.byteLength !== 0
+ );
+ if (
+ status !== 0 || invalidQueryOutput ||
+ this.diagnostics.length !== diagnosticStart
+ ) {
+ throw new Error(
+ `Homebrew query ${command.id} did not produce clean output ` +
+ `(status=${status}, stdout=${stdout.byteLength}, ` +
+ `stderr=${stderr.byteLength}): ` +
+ decoder.decode(stderr).slice(-4_000) + "\n" +
+ this.diagnostics.slice(diagnosticStart).join("\n"),
+ );
+ }
+ return {
+ id: command.id,
+ argv: command.argv,
+ elapsedMs,
+ status,
+ stdoutBytes: stdout.byteLength,
+ stderrBytes: stderr.byteLength,
+ stdoutSha256: await sha256(stdout),
+ stderrSha256: await sha256(stderr),
+ processCounts: countProcessEvents(this.processEvents.slice(processStart)),
+ lazy: summarizeLazyDownloads(this.lazyEvents.slice(lazyStart)),
+ };
+ }
+
+ async auditNetwork(
+ commands: readonly HomebrewQueryCommand[],
+ ): Promise {
+ const events: SyscallTraceEvent[] = [];
+ const unsubscribe = this.kernel.subscribeSyscalls((event) => events.push(event));
+ try {
+ const output: HomebrewQueryNetworkAudit["commands"] = [];
+ for (const command of commands) {
+ const start = events.length;
+ const result = await this.run(command);
+ await delay(350);
+ output.push({
+ id: command.id,
+ status: result.status,
+ networkSyscalls: countNetworkSyscalls(events.slice(start)),
+ });
+ }
+ return { commands: output };
+ } finally {
+ unsubscribe();
+ }
+ }
+
+ async destroy(): Promise {
+ // WHY: this harness runs Chromium only. Avoid importing the WebKit
+ // reclamation helper because that module also imports the repository's
+ // default rootfs, while this benchmark must use only its verified fixture.
+ await this.kernel.destroy();
+ }
+}
+
+function countNetworkSyscalls(
+ events: readonly SyscallTraceEvent[],
+): Record {
+ const counts: Record = {};
+ for (const event of events) {
+ const name = event.decoded?.match(
+ /\]\s+(socket|connect|send|sendto|sendmsg|recv|recvfrom|recvmsg)\b/,
+ )?.[1];
+ if (name) counts[name] = (counts[name] ?? 0) + 1;
+ }
+ return counts;
+}
+
+function countProcessEvents(
+ events: readonly ProcessEvent[],
+): HomebrewQueryProcessCounts {
+ const counts = emptyProcessCounts();
+ for (const event of events) counts[event.kind] += 1;
+ return counts;
+}
+
+async function fetchVerifiedArtifact(
+ fixtureUrl: URL,
+ artifact: HomebrewQueryArtifact,
+): Promise {
+ const url = new URL(artifact.file, fixtureUrl);
+ const response = await fetch(url);
+ if (!response.ok) throw new Error(`${url} returned HTTP ${response.status}`);
+ const value = new Uint8Array(await response.arrayBuffer());
+ if (value.byteLength !== artifact.bytes || await sha256(value) !== artifact.sha256) {
+ throw new Error(`Homebrew query artifact changed identity: ${url}`);
+ }
+ return value;
+}
+
+function concatenate(chunks: readonly Uint8Array[]): Uint8Array {
+ const output = new Uint8Array(
+ chunks.reduce((total, chunk) => total + chunk.byteLength, 0),
+ );
+ let offset = 0;
+ for (const chunk of chunks) {
+ output.set(chunk, offset);
+ offset += chunk.byteLength;
+ }
+ return output;
+}
+
+function wholeArrayBuffer(value: Uint8Array): ArrayBuffer {
+ return value.buffer.slice(
+ value.byteOffset,
+ value.byteOffset + value.byteLength,
+ ) as ArrayBuffer;
+}
+
+async function sha256(value: Uint8Array): Promise {
+ const digest = new Uint8Array(await crypto.subtle.digest(
+ "SHA-256",
+ wholeArrayBuffer(value),
+ ));
+ return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function delay(ms: number): Promise {
+ return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
+async function withTimeout(
+ promise: Promise,
+ timeoutMs: number,
+ message: string,
+): Promise {
+ let timer: ReturnType | undefined;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise((_resolve, reject) => {
+ timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+ }),
+ ]);
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ }
+}
+
+const prepared = prepare();
+window.__homebrewQueryBenchmarkReady = false;
+window.__runHomebrewQueryBenchmark = async (roundCount, auditNetwork = true) => {
+ if (!Number.isSafeInteger(roundCount) || roundCount <= 0) {
+ throw new Error("Homebrew query rounds must be a positive integer");
+ }
+ const { fixture, factory } = await prepared;
+ const rounds: HomebrewQueryScenarioResult[] = [];
+ for (let index = 0; index < roundCount; index += 1) {
+ log(`Homebrew query Chromium round ${index + 1}/${roundCount}`);
+ rounds.push(await runHomebrewQueryScenario({
+ fixture,
+ machines: factory,
+ auditNetwork: auditNetwork && index === 0,
+ }));
+ }
+ return { fixture, rounds, median: medianMetrics(rounds) };
+};
+void prepared.then(
+ () => {
+ window.__homebrewQueryBenchmarkReady = true;
+ log("Homebrew query benchmark ready");
+ },
+ (error) => {
+ window.__homebrewQueryBenchmarkReady = true;
+ log(`Homebrew query benchmark failed to prepare: ${String(error)}`);
+ },
+);
diff --git a/benchmarks/homebrew-query/README.md b/benchmarks/homebrew-query/README.md
new file mode 100644
index 0000000000..f2cee08f06
--- /dev/null
+++ b/benchmarks/homebrew-query/README.md
@@ -0,0 +1,77 @@
+# In-guest Homebrew query benchmark
+
+This benchmark measures real Homebrew metadata queries inside Kandelo on Node
+and Chromium. It separates a cold machine plus its first Brew invocation, the
+first invocation after a shell process has already run, repeated warm
+invocations, and an optional fully materialized VFS control.
+
+The preparation step is the only networked phase. It embeds exact tap
+checkouts into a copy of a published shell image, downloads every deferred
+artifact, and verifies each artifact's declared byte count and SHA-256 digest.
+The runners then bind those bytes as closed lazy assets. Node disables its TCP
+backend, and Chromium blocks and reports every request outside the local
+fixture origin. The first round also records guest socket syscalls for every
+command.
+
+Prepare one fixture and reuse that exact manifest for both sides of a
+comparison:
+
+```bash
+npx tsx benchmarks/homebrew-query/prepare.ts \
+ --image /path/to/shell.vfs.zst \
+ --kernel /path/to/kandelo-kernel.wasm \
+ --bootstrap /path/to/homebrew-bootstrap.zip \
+ --output /tmp/kandelo-homebrew-query \
+ --source-commit FULL_PRODUCER_COMMIT \
+ --tap kandelo-dev/tap-core=/path/to/tap-core \
+ --tap owner/canary-tap=/path/to/canary-tap \
+ --canary-formula owner/canary-tap/formula \
+ --trust-formula kandelo-dev/tap-core/dash \
+ --eager
+```
+
+The shell metadata supplies the Homebrew prefix and shell path; the harness
+does not assume either the rev22 compatibility prefix or the canonical prefix.
+Tap checkouts should be clean and pinned to the commits under test.
+`--trust-formula` records ordinary formula-granular Homebrew trust in the
+fixture. The generated environment points Homebrew at that immutable store
+under `/etc` through `XDG_CONFIG_HOME`, because Kandelo intentionally replaces
+`/home/user` with fresh scratch storage at boot. Use it when a third-party
+Formula has a fully qualified dependency; do not disable Homebrew's tap-trust
+enforcement for the benchmark.
+
+Run the focused workload on both hosts:
+
+```bash
+npx tsx benchmarks/homebrew-query/run-node.ts \
+ --fixture /tmp/kandelo-homebrew-query/manifest.json \
+ --rounds 3 --output /tmp/homebrew-node.json
+npx tsx benchmarks/homebrew-query/run-browser.ts \
+ --fixture /tmp/kandelo-homebrew-query/manifest.json \
+ --rounds 3 --output /tmp/homebrew-chromium.json
+```
+
+Each Chromium sample uses a newly launched browser. Browser launch is outside
+the timed machine and command intervals. This makes rounds independent and
+guarantees that a previous round's renderer, Workers, JavaScript Realms,
+WebAssembly memories, and shared buffers cannot survive into the next sample.
+Used guest Workers are still terminated within each round; no guest Realm or
+process state is reused.
+
+The runners reject a zero exit with empty standard output or non-empty standard
+error for a measured Brew command. This catches shell wrappers that accidentally
+mask an inner command failure instead of recording a fast false success.
+
+Results include artifact and tap identities, host versions, machine details,
+host-side monotonic timings, process counts, lazy transfer counts and bytes,
+output hashes, and the syscall network audit. Compare like-for-like results
+with a deliberately broad 25 percent threshold that detects a large regression
+without turning ordinary host timing noise into a failure:
+
+```bash
+npx tsx benchmarks/homebrew-query/compare.ts \
+ /tmp/homebrew-before.json /tmp/homebrew-after.json
+```
+
+This focused threshold does not replace the repository's full Node and browser
+performance contract in `docs/agent-guidance/performance.md`.
diff --git a/benchmarks/homebrew-query/compare.ts b/benchmarks/homebrew-query/compare.ts
new file mode 100644
index 0000000000..5993ce7cf1
--- /dev/null
+++ b/benchmarks/homebrew-query/compare.ts
@@ -0,0 +1,176 @@
+#!/usr/bin/env -S npx tsx
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type {
+ HomebrewQueryBenchmarkResult,
+ HomebrewQueryFixtureManifest,
+} from "./contracts";
+
+interface Options {
+ beforePath: string;
+ afterPath: string;
+ maxRegressionPercent: number;
+}
+
+interface Comparison {
+ metric: string;
+ before: number;
+ after: number;
+ changePercent: number;
+ regression: boolean;
+}
+
+function main(): void {
+ const options = parseOptions(process.argv.slice(2));
+ const before = readResult(options.beforePath);
+ const after = readResult(options.afterPath);
+ assertComparable(before, after);
+ const comparisons = compareMedians(
+ before.median,
+ after.median,
+ options.maxRegressionPercent,
+ );
+
+ process.stdout.write("| Metric | Before (ms) | After (ms) | Change |\n");
+ process.stdout.write("|---|---:|---:|---:|\n");
+ for (const comparison of comparisons) {
+ const change = Number.isFinite(comparison.changePercent)
+ ? `${comparison.changePercent >= 0 ? "+" : ""}` +
+ `${comparison.changePercent.toFixed(1)}%`
+ : "+infinity";
+ process.stdout.write(
+ `| ${comparison.metric} | ${comparison.before.toFixed(2)} | ` +
+ `${comparison.after.toFixed(2)} | ` +
+ `${comparison.regression ? `**${change}**` : change} |\n`,
+ );
+ }
+
+ const regressions = comparisons.filter((comparison) => comparison.regression);
+ if (regressions.length > 0) {
+ process.stderr.write(
+ `${regressions.length} Homebrew query metric(s) regressed by more than ` +
+ `${options.maxRegressionPercent}%\n`,
+ );
+ process.exitCode = 1;
+ }
+}
+
+export function compareMedians(
+ before: Readonly>,
+ after: Readonly>,
+ maxRegressionPercent: number,
+): Comparison[] {
+ if (!Number.isFinite(maxRegressionPercent) || maxRegressionPercent <= 0) {
+ throw new Error("Homebrew regression threshold must be positive");
+ }
+ const beforeKeys = Object.keys(before).sort();
+ const afterKeys = Object.keys(after).sort();
+ if (JSON.stringify(beforeKeys) !== JSON.stringify(afterKeys)) {
+ throw new Error("Homebrew benchmark results contain different metrics");
+ }
+ return beforeKeys.map((metric) => {
+ const baseline = before[metric]!;
+ const candidate = after[metric]!;
+ if (
+ !Number.isFinite(baseline) || baseline < 0 ||
+ !Number.isFinite(candidate) || candidate < 0
+ ) {
+ throw new Error(`Homebrew benchmark metric ${metric} is invalid`);
+ }
+ const changePercent = baseline === 0
+ ? (candidate === 0 ? 0 : Number.POSITIVE_INFINITY)
+ : ((candidate - baseline) / baseline) * 100;
+ return {
+ metric,
+ before: baseline,
+ after: candidate,
+ changePercent,
+ regression: changePercent > maxRegressionPercent,
+ };
+ });
+}
+
+function readResult(path: string): HomebrewQueryBenchmarkResult {
+ const value = JSON.parse(readFileSync(path, "utf-8")) as
+ Partial;
+ if (
+ value.schema !== 1 ||
+ value.kind !== "kandelo-homebrew-query-benchmark-result" ||
+ (value.host !== "node" && value.host !== "chromium") ||
+ typeof value.median !== "object" || value.median === null ||
+ typeof value.fixture !== "object" || value.fixture === null
+ ) {
+ throw new Error(`Invalid Homebrew query benchmark result: ${path}`);
+ }
+ return value as HomebrewQueryBenchmarkResult;
+}
+
+function assertComparable(
+ before: HomebrewQueryBenchmarkResult,
+ after: HomebrewQueryBenchmarkResult,
+): void {
+ if (before.host !== after.host) {
+ throw new Error(`Cannot compare ${before.host} with ${after.host}`);
+ }
+ const beforeIdentity = fixtureIdentity(before.fixture);
+ const afterIdentity = fixtureIdentity(after.fixture);
+ if (beforeIdentity !== afterIdentity) {
+ throw new Error("Homebrew benchmark results used different input artifacts");
+ }
+}
+
+function fixtureIdentity(fixture: HomebrewQueryFixtureManifest): string {
+ return JSON.stringify({
+ sourceCommit: fixture.sourceCommit,
+ rootfs: fixture.rootfs,
+ eagerRootfs: fixture.eagerRootfs,
+ kernel: fixture.kernel,
+ lazyUrlBase: fixture.lazyUrlBase,
+ lazyAssets: fixture.lazyAssets,
+ shell: fixture.shell,
+ homebrew: fixture.homebrew,
+ taps: fixture.taps,
+ commands: fixture.commands,
+ focusCommandId: fixture.focusCommandId,
+ });
+}
+
+function parseOptions(argv: string[]): Options {
+ const positional: string[] = [];
+ let maxRegressionPercent = 25;
+ for (let index = 0; index < argv.length; index += 1) {
+ const argument = argv[index]!;
+ if (argument.startsWith("--max-regression-percent=")) {
+ maxRegressionPercent = Number(argument.slice(argument.indexOf("=") + 1));
+ } else if (argument === "--max-regression-percent") {
+ maxRegressionPercent = Number(argv[++index]);
+ } else if (argument.startsWith("--")) {
+ usage(`Unknown argument: ${argument}`);
+ } else {
+ positional.push(argument);
+ }
+ }
+ if (positional.length !== 2) usage("Before and after result paths are required");
+ if (!Number.isFinite(maxRegressionPercent) || maxRegressionPercent <= 0) {
+ usage("--max-regression-percent must be positive");
+ }
+ return {
+ beforePath: positional[0]!,
+ afterPath: positional[1]!,
+ maxRegressionPercent,
+ };
+}
+
+function usage(message: string): never {
+ process.stderr.write(`${message}\n`);
+ process.stderr.write(
+ "Usage: npx tsx benchmarks/homebrew-query/compare.ts " +
+ "BEFORE.json AFTER.json [--max-regression-percent 25]\n",
+ );
+ process.exit(2);
+}
+
+if (import.meta.url === pathToFileURL(resolve(process.argv[1]!)).href) main();
diff --git a/benchmarks/homebrew-query/contracts.ts b/benchmarks/homebrew-query/contracts.ts
new file mode 100644
index 0000000000..18ce6d17b0
--- /dev/null
+++ b/benchmarks/homebrew-query/contracts.ts
@@ -0,0 +1,307 @@
+import type { LazyDownloadEvent } from "../../host/src/vfs/memory-fs";
+
+export interface HomebrewQueryArtifact {
+ file: string;
+ bytes: number;
+ sha256: string;
+}
+
+export interface HomebrewQueryLazyArtifact extends HomebrewQueryArtifact {
+ url: string;
+}
+
+export interface HomebrewQueryTap {
+ name: string;
+ repository: string;
+ commit: string;
+}
+
+export interface HomebrewQueryCommand {
+ id: string;
+ argv: string[];
+}
+
+export interface HomebrewQueryFixtureManifest {
+ schema: 1;
+ kind: "kandelo-homebrew-query-benchmark";
+ createdAt: string;
+ sourceCommit: string;
+ rootfs: HomebrewQueryArtifact;
+ eagerRootfs?: HomebrewQueryArtifact;
+ kernel: HomebrewQueryArtifact;
+ lazyUrlBase: string;
+ lazyAssets: HomebrewQueryLazyArtifact[];
+ shell: {
+ path: string;
+ argv0: string;
+ };
+ homebrew: {
+ prefix: string;
+ environment: string[];
+ trustedFormulae: string[];
+ };
+ taps: HomebrewQueryTap[];
+ commands: HomebrewQueryCommand[];
+ focusCommandId: string;
+}
+
+export interface HomebrewQueryProcessCounts {
+ spawn: number;
+ exec: number;
+ exit: number;
+}
+
+export interface HomebrewQueryLazySummary {
+ fetches: number;
+ completed: number;
+ /** The current VFS reports transfers, not individual cached path accesses. */
+ cacheHits: null;
+ bytes: number;
+ urls: string[];
+}
+
+export interface HomebrewQueryCommandResult {
+ id: string;
+ argv: string[];
+ elapsedMs: number;
+ status: number;
+ stdoutBytes: number;
+ stderrBytes: number;
+ stdoutSha256: string;
+ stderrSha256: string;
+ processCounts: HomebrewQueryProcessCounts;
+ lazy: HomebrewQueryLazySummary;
+}
+
+export interface HomebrewQueryNetworkAudit {
+ commands: Array<{
+ id: string;
+ status: number;
+ networkSyscalls: Record;
+ }>;
+}
+
+export interface HomebrewQueryScenarioResult {
+ cold: {
+ machineBootMs: number;
+ machineBootAndFirstBrewMs: number;
+ first: HomebrewQueryCommandResult;
+ warm: HomebrewQueryCommandResult;
+ };
+ booted: {
+ machineBootMs: number;
+ shellBootMs: number;
+ first: HomebrewQueryCommandResult[];
+ warm: HomebrewQueryCommandResult[];
+ };
+ eager?: {
+ machineBootMs: number;
+ shellBootMs: number;
+ first: HomebrewQueryCommandResult;
+ warm: HomebrewQueryCommandResult;
+ };
+ networkAudit?: HomebrewQueryNetworkAudit;
+}
+
+export interface HomebrewQueryBenchmarkResult {
+ schema: 1;
+ kind: "kandelo-homebrew-query-benchmark-result";
+ host: "node" | "chromium";
+ hostVersion: string;
+ kandeloCommit: string;
+ recordedAt: string;
+ machine: {
+ platform: string;
+ architecture: string;
+ cpu: string;
+ };
+ fixture: HomebrewQueryFixtureManifest;
+ rounds: HomebrewQueryScenarioResult[];
+ median: Record;
+}
+
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const SAFE_RELATIVE_PATH_RE = /^[^\\\0/]+(?:\/[^\\\0/]+)*$/;
+
+export function assertHomebrewQueryFixture(
+ value: unknown,
+): asserts value is HomebrewQueryFixtureManifest {
+ if (typeof value !== "object" || value === null) {
+ throw new Error("Homebrew query fixture must be an object");
+ }
+ const fixture = value as Partial;
+ if (
+ fixture.schema !== 1 ||
+ fixture.kind !== "kandelo-homebrew-query-benchmark" ||
+ typeof fixture.createdAt !== "string" ||
+ !Number.isFinite(Date.parse(fixture.createdAt)) ||
+ typeof fixture.sourceCommit !== "string" ||
+ !/^[0-9a-f]{40}$/.test(fixture.sourceCommit) ||
+ typeof fixture.lazyUrlBase !== "string" ||
+ !Array.isArray(fixture.lazyAssets) ||
+ !Array.isArray(fixture.commands) ||
+ !Array.isArray(fixture.taps) ||
+ typeof fixture.focusCommandId !== "string" ||
+ typeof fixture.shell?.path !== "string" ||
+ !fixture.shell.path.startsWith("/") ||
+ typeof fixture.shell.argv0 !== "string" ||
+ typeof fixture.homebrew?.prefix !== "string" ||
+ !fixture.homebrew.prefix.startsWith("/") ||
+ !Array.isArray(fixture.homebrew.environment) ||
+ !Array.isArray(fixture.homebrew.trustedFormulae)
+ ) {
+ throw new Error("Homebrew query fixture has invalid top-level fields");
+ }
+ new URL(fixture.lazyUrlBase);
+ assertArtifact(fixture.rootfs, "rootfs");
+ assertArtifact(fixture.kernel, "kernel");
+ if (fixture.eagerRootfs !== undefined) {
+ assertArtifact(fixture.eagerRootfs, "eagerRootfs");
+ }
+ const commandIds = new Set();
+ for (const command of fixture.commands) {
+ if (
+ typeof command?.id !== "string" || command.id === "" ||
+ !Array.isArray(command.argv) || command.argv.length === 0 ||
+ command.argv.some((argument) => typeof argument !== "string") ||
+ commandIds.has(command.id)
+ ) {
+ throw new Error("Homebrew query fixture has an invalid command");
+ }
+ commandIds.add(command.id);
+ }
+ if (!commandIds.has(fixture.focusCommandId)) {
+ throw new Error("Homebrew query fixture focus command is missing");
+ }
+ const tapNames = new Set();
+ for (const tap of fixture.taps) {
+ if (
+ typeof tap?.name !== "string" || tap.name === "" ||
+ typeof tap.repository !== "string" || tap.repository === "" ||
+ typeof tap.commit !== "string" || !/^[0-9a-f]{40}$/.test(tap.commit) ||
+ tapNames.has(tap.name)
+ ) {
+ throw new Error("Homebrew query fixture has an invalid tap");
+ }
+ tapNames.add(tap.name);
+ }
+ const lazyUrls = new Set();
+ for (const asset of fixture.lazyAssets) {
+ assertArtifact(asset, "lazy asset");
+ if (typeof asset.url !== "string" || lazyUrls.has(asset.url)) {
+ throw new Error("Homebrew query fixture has an invalid lazy URL");
+ }
+ new URL(asset.url);
+ lazyUrls.add(asset.url);
+ }
+ for (const value of fixture.homebrew.environment) {
+ if (typeof value !== "string" || !value.includes("=")) {
+ throw new Error("Homebrew query fixture has an invalid environment");
+ }
+ }
+ for (const value of fixture.homebrew.trustedFormulae) {
+ if (typeof value !== "string" || value.split("/").length !== 3) {
+ throw new Error("Homebrew query fixture has invalid Formula trust state");
+ }
+ }
+}
+
+function assertArtifact(
+ artifact: HomebrewQueryArtifact | undefined,
+ label: string,
+): void {
+ if (
+ typeof artifact?.file !== "string" || artifact.file === "" ||
+ !SAFE_RELATIVE_PATH_RE.test(artifact.file) ||
+ artifact.file.split("/").some((part) => part === "." || part === "..") ||
+ !Number.isSafeInteger(artifact.bytes) || artifact.bytes <= 0 ||
+ typeof artifact.sha256 !== "string" || !SHA256_RE.test(artifact.sha256)
+ ) {
+ throw new Error(`Homebrew query fixture ${label} is invalid`);
+ }
+}
+
+export function shellQuote(argument: string): string {
+ return `'${argument.replaceAll("'", `'\\''`)}'`;
+}
+
+export function commandScript(command: HomebrewQueryCommand): string {
+ return command.argv.map(shellQuote).join(" ");
+}
+
+export function emptyProcessCounts(): HomebrewQueryProcessCounts {
+ return { spawn: 0, exec: 0, exit: 0 };
+}
+
+export function summarizeLazyDownloads(
+ events: readonly LazyDownloadEvent[],
+): HomebrewQueryLazySummary {
+ const byId = new Map();
+ for (const event of events) {
+ const list = byId.get(event.id) ?? [];
+ list.push(event);
+ byId.set(event.id, list);
+ }
+ let completed = 0;
+ let bytes = 0;
+ const urls = new Set();
+ for (const list of byId.values()) {
+ const final = list.at(-1)!;
+ urls.add(final.url);
+ if (final.status === "complete") completed += 1;
+ bytes += final.loadedBytes;
+ }
+ return {
+ fetches: byId.size,
+ completed,
+ cacheHits: null,
+ bytes,
+ urls: [...urls].sort(),
+ };
+}
+
+export function medianMetrics(
+ rounds: readonly HomebrewQueryScenarioResult[],
+): Record {
+ const values = new Map();
+ const add = (key: string, value: number): void => {
+ const list = values.get(key) ?? [];
+ list.push(value);
+ values.set(key, list);
+ };
+ for (const round of rounds) {
+ add("cold.machine_boot_ms", round.cold.machineBootMs);
+ add(
+ "cold.machine_boot_and_first_brew_ms",
+ round.cold.machineBootAndFirstBrewMs,
+ );
+ add("cold.focus_first_ms", round.cold.first.elapsedMs);
+ add("cold.focus_warm_ms", round.cold.warm.elapsedMs);
+ add("booted.machine_boot_ms", round.booted.machineBootMs);
+ add("booted.shell_boot_ms", round.booted.shellBootMs);
+ for (const result of round.booted.first) {
+ add(`booted.first.${result.id}_ms`, result.elapsedMs);
+ }
+ for (const result of round.booted.warm) {
+ add(`booted.warm.${result.id}_ms`, result.elapsedMs);
+ }
+ if (round.eager) {
+ add("eager.machine_boot_ms", round.eager.machineBootMs);
+ add("eager.shell_boot_ms", round.eager.shellBootMs);
+ add("eager.focus_first_ms", round.eager.first.elapsedMs);
+ add("eager.focus_warm_ms", round.eager.warm.elapsedMs);
+ }
+ }
+ return Object.fromEntries(
+ [...values].map(([key, samples]) => [key, median(samples)]),
+ );
+}
+
+function median(samples: readonly number[]): number {
+ const sorted = [...samples].sort((left, right) => left - right);
+ const middle = Math.floor(sorted.length / 2);
+ const value = sorted.length % 2 === 0
+ ? (sorted[middle - 1]! + sorted[middle]!) / 2
+ : sorted[middle]!;
+ return Math.round(value * 100) / 100;
+}
diff --git a/benchmarks/homebrew-query/prepare.ts b/benchmarks/homebrew-query/prepare.ts
new file mode 100644
index 0000000000..82663d88ea
--- /dev/null
+++ b/benchmarks/homebrew-query/prepare.ts
@@ -0,0 +1,548 @@
+#!/usr/bin/env -S npx tsx
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import {
+ copyFileSync,
+ existsSync,
+ lstatSync,
+ mkdirSync,
+ readFileSync,
+ readdirSync,
+ readlinkSync,
+ writeFileSync,
+} from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { constants as zlibConstants, zstdCompressSync } from "node:zlib";
+
+import {
+ MemoryFileSystem,
+ type SerializedLazyTree,
+ type VfsImageMetadata,
+} from "../../host/src/vfs/memory-fs";
+import { restoreVerifiedVfsImage } from "../../host/src/vfs/load-image";
+import { ensureDirRecursive } from "../../host/src/vfs/image-helpers";
+import { ENOENT } from "../../host/src/vfs/sharedfs-vendor";
+import type {
+ HomebrewQueryArtifact,
+ HomebrewQueryFixtureManifest,
+ HomebrewQueryLazyArtifact,
+ HomebrewQueryTap,
+} from "./contracts";
+
+interface Options {
+ imagePath: string;
+ kernelPath: string;
+ bootstrapPath: string;
+ outputDirectory: string;
+ sourceCommit: string;
+ lazyUrlBase: string;
+ taps: Array<{ name: string; path: string }>;
+ coreFormula: string;
+ canaryFormula?: string;
+ trustedFormulae: string[];
+ eager: boolean;
+}
+
+const decoder = new TextDecoder("utf-8", { fatal: true });
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const S_IFMT = 0xf000;
+const S_IFREG = 0x8000;
+const S_IFDIR = 0x4000;
+const S_IFLNK = 0xa000;
+
+async function main(): Promise {
+ const options = parseOptions(process.argv.slice(2));
+ mkdirSync(options.outputDirectory, { recursive: true });
+ const lazyDirectory = join(options.outputDirectory, "lazy");
+ mkdirSync(lazyDirectory, { recursive: true });
+
+ const sourceImage = bytes(options.imagePath);
+ const fs = await restoreVerifiedVfsImage(sourceImage);
+ const metadata = fs.getImageMetadata() as (VfsImageMetadata & {
+ homebrewBootstrap?: { ownership?: { prefix?: unknown } };
+ homebrew?: { defaultShell?: { path?: unknown; argv?: unknown } };
+ }) | null;
+ const prefix = metadata?.homebrewBootstrap?.ownership?.prefix;
+ const shellPath = metadata?.homebrew?.defaultShell?.path;
+ const shellArgv = metadata?.homebrew?.defaultShell?.argv;
+ if (
+ typeof prefix !== "string" || !prefix.startsWith("/") ||
+ typeof shellPath !== "string" || !shellPath.startsWith("/") ||
+ !Array.isArray(shellArgv) || typeof shellArgv[0] !== "string"
+ ) {
+ throw new Error("Homebrew image does not declare its prefix and shell");
+ }
+
+ const taps: HomebrewQueryTap[] = [];
+ const tapRepositories = new Set();
+ for (const tap of options.taps) {
+ const repository = tapRepository(tap.name);
+ if (tapRepositories.has(repository)) {
+ throw new Error(`Duplicate tap repository: ${repository}`);
+ }
+ tapRepositories.add(repository);
+ const dirty = git(tap.path, ["status", "--porcelain=v1"]);
+ if (dirty !== "") {
+ throw new Error(`Tap checkout is not clean: ${tap.path}`);
+ }
+ const commit = git(tap.path, ["rev-parse", "HEAD"]);
+ if (!/^[0-9a-f]{40}$/.test(commit)) {
+ throw new Error(`Tap ${tap.name} did not resolve to a commit`);
+ }
+ const target = `${prefix}/Library/Taps/${repository}`;
+ removeVfsTree(fs, target);
+ copyHostTree(fs, tap.path, target, 1000, 1000);
+ taps.push({ name: tap.name, repository, commit });
+ }
+
+ // Homebrew treats Caskroom as part of an initialized prefix even when no
+ // casks are installed. Published shells mount an empty writable directory
+ // here; put the same state in the cross-host fixture so `brew list` measures
+ // discovery rather than an incomplete harness mount.
+ const caskroom = `${prefix}/Caskroom`;
+ ensureDirRecursive(fs, caskroom, 0o755);
+ fs.chown(caskroom, 1000, 1000);
+ fs.chmod(caskroom, 0o755);
+
+ const environment = [
+ "HOME=/home/user",
+ "USER=user",
+ "LOGNAME=user",
+ `SHELL=${shellPath}`,
+ `PATH=${prefix}/bin:${prefix}/sbin:/usr/local/bin:/usr/bin:/bin`,
+ ...readVfsText(fs, "/etc/homebrew/brew.env")
+ .split("\n")
+ .map((line) => line.trim())
+ .filter((line) => line !== "" && !line.startsWith("#")),
+ ];
+ for (const required of [
+ "HOMEBREW_NO_AUTO_UPDATE=1",
+ "HOMEBREW_NO_INSTALL_FROM_API=1",
+ "HOMEBREW_NO_ANALYTICS=1",
+ ]) {
+ if (!environment.includes(required)) environment.push(required);
+ }
+ const trustedFormulae = [...new Set(options.trustedFormulae)].sort();
+ if (trustedFormulae.length > 0) {
+ // WHY: Kandelo mounts /home/user and /var as fresh per-boot scratch on
+ // both hosts, so user state embedded there is intentionally hidden at
+ // runtime. Keep this immutable benchmark input in the rootfs-backed /etc
+ // tree and select it through the standard XDG configuration variable.
+ const configRoot = "/etc/kandelo/homebrew-query-config";
+ const configHome = `${configRoot}/homebrew`;
+ for (let index = environment.length - 1; index >= 0; index -= 1) {
+ if (
+ environment[index]!.startsWith("XDG_CONFIG_HOME=") ||
+ environment[index]!.startsWith("HOMEBREW_USER_CONFIG_HOME=")
+ ) {
+ environment.splice(index, 1);
+ }
+ }
+ environment.push(`XDG_CONFIG_HOME=${configRoot}`);
+ ensureDirRecursive(fs, configHome, 0o700);
+ fs.chown(configRoot, 1000, 1000);
+ fs.chmod(configRoot, 0o700);
+ fs.chown(configHome, 1000, 1000);
+ fs.chmod(configHome, 0o700);
+ fs.createFileWithOwner(
+ `${configHome}/trust.json`,
+ 0o600,
+ 1000,
+ 1000,
+ new TextEncoder().encode(
+ `${JSON.stringify({ trustedformulae: trustedFormulae }, null, 2)}\n`,
+ ),
+ );
+ }
+
+ const inheritedMetadata: VfsImageMetadata = metadata ?? { version: 1 };
+ fs.setImageMetadata({
+ ...inheritedMetadata,
+ homebrewQueryBenchmark: {
+ schema: 1,
+ taps,
+ sourceImageSha256: sha256(sourceImage),
+ },
+ });
+ const rootfsPath = join(options.outputDirectory, "rootfs.vfs.zst");
+ await saveCompressedImage(fs, rootfsPath);
+
+ const bootstrap = bytes(options.bootstrapPath);
+ const lazyAssets = await materializeLazyArtifacts({
+ groups: fs.exportLazyArchiveEntries(),
+ bootstrap,
+ lazyUrlBase: options.lazyUrlBase,
+ outputDirectory: options.outputDirectory,
+ });
+
+ let eagerRootfs: HomebrewQueryArtifact | undefined;
+ if (options.eager) {
+ const eagerFs = await restoreVerifiedVfsImage(bytes(rootfsPath));
+ const assetsByUrl = new Map(
+ lazyAssets.map((asset) => [
+ asset.url,
+ bytes(join(options.outputDirectory, asset.file)),
+ ]),
+ );
+ eagerFs.setLazyFetcher(async (input) => {
+ const url = new URL(input, options.lazyUrlBase).href;
+ const asset = assetsByUrl.get(url);
+ if (!asset) throw new Error(`Unbound eager lazy URL: ${url}`);
+ return new Response(wholeArrayBuffer(asset));
+ });
+ const eagerPath = join(options.outputDirectory, "rootfs-eager.vfs.zst");
+ await saveCompressedImage(eagerFs, eagerPath, true);
+ eagerRootfs = fingerprint(eagerPath, options.outputDirectory);
+ }
+
+ const kernelOutput = join(options.outputDirectory, "kernel.wasm");
+ copyFileSync(options.kernelPath, kernelOutput);
+ const commands = [
+ { id: "version", argv: [`${prefix}/bin/brew`, "--version"] },
+ { id: "config", argv: [`${prefix}/bin/brew`, "config"] },
+ {
+ id: "info",
+ argv: [`${prefix}/bin/brew`, "info", options.coreFormula],
+ },
+ {
+ id: "info_json_v2",
+ argv: [
+ `${prefix}/bin/brew`,
+ "info",
+ "--json=v2",
+ "--formula",
+ options.coreFormula,
+ ],
+ },
+ {
+ id: "list_versions",
+ argv: [`${prefix}/bin/brew`, "list", "--versions"],
+ },
+ ...(options.canaryFormula === undefined
+ ? []
+ : [{
+ id: "canary_info",
+ argv: [`${prefix}/bin/brew`, "info", options.canaryFormula],
+ }]),
+ ];
+ const manifest: HomebrewQueryFixtureManifest = {
+ schema: 1,
+ kind: "kandelo-homebrew-query-benchmark",
+ createdAt: new Date().toISOString(),
+ sourceCommit: options.sourceCommit,
+ rootfs: fingerprint(rootfsPath, options.outputDirectory),
+ ...(eagerRootfs === undefined ? {} : { eagerRootfs }),
+ kernel: fingerprint(kernelOutput, options.outputDirectory),
+ lazyUrlBase: options.lazyUrlBase,
+ lazyAssets,
+ shell: { path: shellPath, argv0: shellArgv[0] },
+ homebrew: { prefix, environment, trustedFormulae },
+ taps,
+ commands,
+ focusCommandId: "info",
+ };
+ const manifestPath = join(options.outputDirectory, "manifest.json");
+ writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+ process.stdout.write(
+ `Prepared ${manifestPath} with ${lazyAssets.length} closed lazy bindings\n`,
+ );
+}
+
+async function materializeLazyArtifacts(options: {
+ groups: SerializedLazyTree[];
+ bootstrap: Uint8Array;
+ lazyUrlBase: string;
+ outputDirectory: string;
+}): Promise {
+ const bootstrapSha256 = sha256(options.bootstrap);
+ const contentFiles = new Map();
+ const output: HomebrewQueryLazyArtifact[] = [];
+ const seenUrls = new Set();
+ for (const group of options.groups) {
+ const content = group.content;
+ const integrity = group.integrity;
+ const expectedSha256 = content?.sha256 ?? integrity?.sha256;
+ const expectedBytes = content?.bytes ?? integrity?.bytes;
+ const transports = content?.transports ?? [group.url];
+ if (
+ typeof expectedSha256 !== "string" || !SHA256_RE.test(expectedSha256) ||
+ typeof expectedBytes !== "number" ||
+ !Number.isSafeInteger(expectedBytes) || expectedBytes <= 0 ||
+ transports.length === 0
+ ) {
+ throw new Error(`Deferred tree ${group.mountPrefix} lacks content identity`);
+ }
+ let relativeFile = contentFiles.get(expectedSha256);
+ if (relativeFile === undefined) {
+ relativeFile = `lazy/${expectedSha256}.bin`;
+ const outputPath = join(options.outputDirectory, relativeFile);
+ if (expectedSha256 === bootstrapSha256) {
+ writeFileSync(outputPath, options.bootstrap);
+ } else if (!existsSync(outputPath)) {
+ const sourceUrl = new URL(transports[0]!, options.lazyUrlBase).href;
+ process.stdout.write(`Fetching ${sourceUrl}\n`);
+ const response = await fetch(sourceUrl, {
+ credentials: "omit",
+ redirect: "follow",
+ });
+ if (!response.ok) {
+ throw new Error(`Lazy asset returned HTTP ${response.status}: ${sourceUrl}`);
+ }
+ writeFileSync(outputPath, new Uint8Array(await response.arrayBuffer()));
+ }
+ const artifact = fingerprint(outputPath, options.outputDirectory);
+ if (
+ artifact.sha256 !== expectedSha256 || artifact.bytes !== expectedBytes
+ ) {
+ throw new Error(`Lazy asset changed identity: ${outputPath}`);
+ }
+ contentFiles.set(expectedSha256, relativeFile);
+ }
+ for (const transport of transports) {
+ const url = new URL(transport, options.lazyUrlBase).href;
+ if (seenUrls.has(url)) continue;
+ seenUrls.add(url);
+ output.push({
+ url,
+ file: relativeFile,
+ bytes: expectedBytes,
+ sha256: expectedSha256,
+ });
+ }
+ }
+ return output.sort((left, right) => left.url.localeCompare(right.url));
+}
+
+async function saveCompressedImage(
+ fs: MemoryFileSystem,
+ outputPath: string,
+ materializeAll = false,
+): Promise {
+ const image = await fs.saveImage({
+ materializeAll,
+ normalizeTimestampsMs: 0,
+ });
+ const compressed = zstdCompressSync(image, {
+ params: { [zlibConstants.ZSTD_c_compressionLevel]: 19 },
+ });
+ writeFileSync(outputPath, compressed);
+}
+
+function copyHostTree(
+ fs: MemoryFileSystem,
+ source: string,
+ target: string,
+ uid: number,
+ gid: number,
+): void {
+ const stat = lstatSync(source);
+ const mode = stat.mode & 0o7777;
+ if (stat.isDirectory()) {
+ ensureDirRecursive(fs, target, mode || 0o755);
+ fs.chown(target, uid, gid);
+ fs.chmod(target, mode || 0o755);
+ for (const name of readdirSync(source).sort()) {
+ copyHostTree(fs, join(source, name), `${target}/${name}`, uid, gid);
+ }
+ } else if (stat.isFile()) {
+ ensureDirRecursive(fs, target.slice(0, target.lastIndexOf("/")));
+ fs.createFileWithOwner(target, mode || 0o644, uid, gid, bytes(source));
+ } else if (stat.isSymbolicLink()) {
+ ensureDirRecursive(fs, target.slice(0, target.lastIndexOf("/")));
+ fs.symlinkWithOwner(readlinkSync(source), target, uid, gid);
+ } else {
+ throw new Error(`Tap contains unsupported host entry: ${source}`);
+ }
+}
+
+function removeVfsTree(fs: MemoryFileSystem, path: string): void {
+ let mode: number;
+ try {
+ mode = fs.lstat(path).mode & S_IFMT;
+ } catch (error) {
+ if (vfsErrorCode(error) === ENOENT) return;
+ throw error;
+ }
+ if (mode === S_IFDIR) {
+ const handle = fs.opendir(path);
+ const children: string[] = [];
+ try {
+ for (;;) {
+ const entry = fs.readdir(handle);
+ if (!entry) break;
+ if (entry.name !== "." && entry.name !== "..") {
+ children.push(entry.name);
+ }
+ }
+ } finally {
+ fs.closedir(handle);
+ }
+ for (const child of children) removeVfsTree(fs, `${path}/${child}`);
+ fs.rmdir(path);
+ } else if (mode === S_IFREG || mode === S_IFLNK) {
+ fs.unlink(path);
+ } else {
+ throw new Error(`VFS tap path has unsupported type: ${path}`);
+ }
+}
+
+function readVfsText(fs: MemoryFileSystem, path: string): string {
+ const stat = fs.stat(path);
+ const output = new Uint8Array(stat.size);
+ const fd = fs.open(path, 0, 0);
+ try {
+ let offset = 0;
+ while (offset < output.byteLength) {
+ const count = fs.read(
+ fd,
+ output.subarray(offset),
+ null,
+ output.byteLength - offset,
+ );
+ if (count <= 0) throw new Error(`Short VFS read: ${path}`);
+ offset += count;
+ }
+ } finally {
+ fs.close(fd);
+ }
+ return decoder.decode(output);
+}
+
+function fingerprint(
+ path: string,
+ root: string,
+): HomebrewQueryArtifact {
+ const value = bytes(path);
+ return {
+ file: relative(root, path).split("\\").join("/"),
+ bytes: value.byteLength,
+ sha256: sha256(value),
+ };
+}
+
+function sha256(value: Uint8Array): string {
+ return createHash("sha256").update(value).digest("hex");
+}
+
+function bytes(path: string): Uint8Array {
+ const value = readFileSync(path);
+ return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+}
+
+function wholeArrayBuffer(value: Uint8Array): ArrayBuffer {
+ return value.buffer.slice(
+ value.byteOffset,
+ value.byteOffset + value.byteLength,
+ ) as ArrayBuffer;
+}
+
+function tapRepository(name: string): string {
+ const match = /^([a-z0-9_.-]+)\/([a-z0-9_.-]+)$/.exec(name);
+ if (!match) throw new Error(`Invalid tap name: ${name}`);
+ return `${match[1]}/homebrew-${match[2]}`;
+}
+
+function git(directory: string, args: string[]): string {
+ return execFileSync("git", args, {
+ cwd: directory,
+ encoding: "utf-8",
+ stdio: ["ignore", "pipe", "inherit"],
+ }).trim();
+}
+
+function vfsErrorCode(error: unknown): number | undefined {
+ return typeof error === "object" && error !== null && "code" in error
+ ? (error as { code?: number }).code
+ : undefined;
+}
+
+function parseOptions(argv: string[]): Options {
+ const allowed = new Set([
+ "image",
+ "kernel",
+ "bootstrap",
+ "output",
+ "source-commit",
+ "lazy-url-base",
+ "tap",
+ "core-formula",
+ "canary-formula",
+ "trust-formula",
+ ]);
+ const values = new Map();
+ let eager = false;
+ for (let index = 0; index < argv.length; index += 1) {
+ const argument = argv[index]!;
+ if (argument === "--eager") {
+ eager = true;
+ continue;
+ }
+ if (!argument.startsWith("--")) usage(`Unexpected argument: ${argument}`);
+ const equals = argument.indexOf("=");
+ const name = equals < 0 ? argument.slice(2) : argument.slice(2, equals);
+ if (!allowed.has(name)) usage(`Unknown option: --${name}`);
+ const value = equals < 0 ? argv[++index] : argument.slice(equals + 1);
+ if (value === undefined || value.startsWith("--")) {
+ usage(`Missing value for --${name}`);
+ }
+ values.set(name, [...(values.get(name) ?? []), value]);
+ }
+ const required = (name: string): string => {
+ const value = values.get(name)?.at(-1);
+ if (!value) usage(`--${name} is required`);
+ return resolve(value!);
+ };
+ const sourceCommit = values.get("source-commit")?.at(-1);
+ if (!sourceCommit || !/^[0-9a-f]{40}$/.test(sourceCommit)) {
+ usage("--source-commit must be a full Git commit");
+ }
+ const taps = (values.get("tap") ?? []).map((value) => {
+ const separator = value.indexOf("=");
+ if (separator <= 0) usage("--tap must be TAP_NAME=CHECKOUT_PATH");
+ return {
+ name: value.slice(0, separator),
+ path: resolve(value.slice(separator + 1)),
+ };
+ });
+ if (taps.length === 0) usage("At least one --tap is required");
+ const lazyUrlBase = values.get("lazy-url-base")?.at(-1) ??
+ "https://homebrew-query-benchmark.invalid/";
+ if (!lazyUrlBase.endsWith("/")) {
+ usage("--lazy-url-base must end with /");
+ }
+ new URL(lazyUrlBase);
+ return {
+ imagePath: required("image"),
+ kernelPath: required("kernel"),
+ bootstrapPath: required("bootstrap"),
+ outputDirectory: required("output"),
+ sourceCommit,
+ lazyUrlBase,
+ taps,
+ coreFormula: values.get("core-formula")?.at(-1) ??
+ "kandelo-dev/tap-core/dash",
+ canaryFormula: values.get("canary-formula")?.at(-1),
+ trustedFormulae: values.get("trust-formula") ?? [],
+ eager,
+ };
+}
+
+function usage(message: string): never {
+ process.stderr.write(`${message}\n\n`);
+ process.stderr.write(
+ "Usage: npx tsx benchmarks/homebrew-query/prepare.ts " +
+ "--image PATH --kernel PATH --bootstrap PATH --output DIR " +
+ "--source-commit COMMIT --tap TAP=PATH [--tap TAP=PATH] " +
+ "[--core-formula NAME] [--canary-formula NAME] " +
+ "[--trust-formula NAME] [--eager]\n",
+ );
+ process.exit(2);
+}
+
+void main().catch((error) => {
+ process.stderr.write(
+ `homebrew-query prepare failed: ${error instanceof Error ? error.stack : error}\n`,
+ );
+ process.exitCode = 1;
+});
diff --git a/benchmarks/homebrew-query/run-browser.ts b/benchmarks/homebrew-query/run-browser.ts
new file mode 100644
index 0000000000..7bbfdc899b
--- /dev/null
+++ b/benchmarks/homebrew-query/run-browser.ts
@@ -0,0 +1,281 @@
+#!/usr/bin/env -S npx tsx
+
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { arch, cpus, platform, release } from "node:os";
+import { dirname, extname, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { chromium } from "playwright";
+import { createServer, type Plugin, type ViteDevServer } from "vite";
+
+import { withRejectingTimeout } from "../timeout";
+import { medianMetrics } from "./contracts";
+import type {
+ HomebrewQueryBenchmarkResult,
+ HomebrewQueryFixtureManifest,
+ HomebrewQueryScenarioResult,
+} from "./contracts";
+
+interface Options {
+ fixturePath: string;
+ rounds: number;
+ outputPath?: string;
+}
+
+interface PageResult {
+ fixture: HomebrewQueryFixtureManifest;
+ rounds: HomebrewQueryScenarioResult[];
+ median: Record;
+}
+
+declare global {
+ interface Window {
+ __homebrewQueryBenchmarkReady: boolean;
+ __runHomebrewQueryBenchmark(
+ rounds: number,
+ auditNetwork?: boolean,
+ ): Promise;
+ }
+}
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+const browserRoot = resolve(repoRoot, "apps/browser-demos");
+const BENCHMARK_TIMEOUT_MS = 90 * 60_000;
+
+async function main(): Promise {
+ const options = parseOptions(process.argv.slice(2));
+ const fixtureRoot = dirname(options.fixturePath);
+ const fixtureRoute = "/__homebrew_query_fixture/manifest.json";
+ let server: ViteDevServer | undefined;
+ let browser: Awaited> | undefined;
+ try {
+ server = await createServer({
+ root: browserRoot,
+ configFile: resolve(browserRoot, "vite.config.ts"),
+ logLevel: "warn",
+ server: {
+ port: 0,
+ headers: {
+ "Cross-Origin-Opener-Policy": "same-origin",
+ "Cross-Origin-Embedder-Policy": "require-corp",
+ },
+ },
+ optimizeDeps: {
+ entries: [
+ resolve(browserRoot, "pages/homebrew-benchmark/index.html"),
+ ],
+ },
+ plugins: [fixturePlugin(fixtureRoot, options.fixturePath)],
+ });
+ await server.listen();
+ const address = server.httpServer?.address();
+ if (typeof address !== "object" || address === null) {
+ throw new Error("Vite did not expose its benchmark port");
+ }
+ const origin = `http://127.0.0.1:${address.port}`;
+ let browserVersion: string | undefined;
+ let fixture: HomebrewQueryFixtureManifest | undefined;
+ const rounds: HomebrewQueryScenarioResult[] = [];
+ const externalRequests: string[] = [];
+ for (let index = 0; index < options.rounds; index += 1) {
+ process.stderr.write(
+ `Homebrew query independent Chromium round ${index + 1}/${options.rounds}\n`,
+ );
+ browser = await chromium.launch();
+ browserVersion ??= browser.version();
+ const context = await browser.newContext();
+ try {
+ await context.route("**/*", async (route) => {
+ const url = route.request().url();
+ if (
+ url.startsWith(`${origin}/`) ||
+ url.startsWith(`http://localhost:${address.port}/`)
+ ) {
+ await route.continue();
+ } else {
+ externalRequests.push(url);
+ await route.abort("blockedbyclient");
+ }
+ });
+ const page = await context.newPage();
+ let rejectPageCrash!: (error: Error) => void;
+ const pageCrash = new Promise((_resolve, reject) => {
+ rejectPageCrash = reject;
+ });
+ page.on("crash", () => {
+ rejectPageCrash(new Error(
+ "Chromium renderer crashed during the Homebrew query benchmark",
+ ));
+ });
+ page.on("console", (message) => {
+ if (["log", "info", "warning", "error"].includes(message.type())) {
+ process.stderr.write(`[Chromium] ${message.text()}\n`);
+ }
+ });
+ page.on("pageerror", (error) => {
+ process.stderr.write(`[Chromium page error] ${error.stack ?? error.message}\n`);
+ });
+ await page.goto(
+ `${origin}/pages/homebrew-benchmark/?fixture=${encodeURIComponent(fixtureRoute)}`,
+ { waitUntil: "domcontentloaded", timeout: 30_000 },
+ );
+ await page.waitForFunction(
+ () => window.__homebrewQueryBenchmarkReady === true,
+ undefined,
+ { timeout: 180_000 },
+ );
+ const pageResult = await withRejectingTimeout(
+ Promise.race([
+ page.evaluate(
+ ({ auditNetwork }) => window.__runHomebrewQueryBenchmark(
+ 1,
+ auditNetwork,
+ ),
+ { auditNetwork: index === 0 },
+ ),
+ pageCrash,
+ ]),
+ BENCHMARK_TIMEOUT_MS,
+ `Chromium Homebrew query benchmark timed out after ${BENCHMARK_TIMEOUT_MS}ms`,
+ );
+ if (pageResult.rounds.length !== 1) {
+ throw new Error("Chromium Homebrew query round returned invalid results");
+ }
+ fixture ??= pageResult.fixture;
+ rounds.push(pageResult.rounds[0]!);
+ } finally {
+ try {
+ await context.close();
+ } finally {
+ // WHY: each round must release its renderer, Realms, workers and
+ // SABs. Keeping Chromium alive made independent rounds retain enough
+ // opaque engine state to crash before a three-round run ended.
+ await browser.close();
+ browser = undefined;
+ }
+ }
+ }
+ if (externalRequests.length > 0) {
+ throw new Error(
+ "Chromium Homebrew query benchmark attempted external requests:\n" +
+ [...new Set(externalRequests)].join("\n"),
+ );
+ }
+ if (browserVersion === undefined || fixture === undefined) {
+ throw new Error("Chromium Homebrew query benchmark produced no rounds");
+ }
+ const result: HomebrewQueryBenchmarkResult = {
+ schema: 1,
+ kind: "kandelo-homebrew-query-benchmark-result",
+ host: "chromium",
+ hostVersion: browserVersion,
+ kandeloCommit: gitHead(),
+ recordedAt: new Date().toISOString(),
+ machine: {
+ platform: `${platform()} ${release()}`,
+ architecture: arch(),
+ cpu: cpus()[0]?.model ?? "unknown",
+ },
+ fixture,
+ rounds,
+ median: medianMetrics(rounds),
+ };
+ const encoded = `${JSON.stringify(result, null, 2)}\n`;
+ if (options.outputPath) {
+ mkdirSync(dirname(options.outputPath), { recursive: true });
+ writeFileSync(options.outputPath, encoded);
+ process.stderr.write(`Wrote ${options.outputPath}\n`);
+ }
+ process.stdout.write(encoded);
+ } finally {
+ await browser?.close();
+ await server?.close();
+ }
+}
+
+function fixturePlugin(fixtureRoot: string, manifestPath: string): Plugin {
+ const root = resolve(fixtureRoot);
+ return {
+ name: "homebrew-query-fixture",
+ configureServer(server) {
+ server.middlewares.use("/__homebrew_query_fixture/", (request, response) => {
+ const requestPath = decodeURIComponent(
+ (request.url ?? "").split("?", 1)[0]!.replace(/^\/+/, ""),
+ );
+ const path = requestPath === "manifest.json"
+ ? manifestPath
+ : resolve(root, requestPath);
+ const relativePath = relative(root, path);
+ if (
+ relativePath === ".." || relativePath.startsWith(`..${sep}`) ||
+ !existsSync(path) || !statSync(path).isFile()
+ ) {
+ response.statusCode = 404;
+ response.end();
+ return;
+ }
+ response.statusCode = 200;
+ response.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+ response.setHeader("Content-Type", contentType(path));
+ response.end(readFileSync(path));
+ });
+ },
+ };
+}
+
+function contentType(path: string): string {
+ switch (extname(path)) {
+ case ".json": return "application/json";
+ case ".wasm": return "application/wasm";
+ default: return "application/octet-stream";
+ }
+}
+
+function gitHead(): string {
+ return execFileSync("git", ["rev-parse", "HEAD"], {
+ cwd: repoRoot,
+ encoding: "utf-8",
+ stdio: ["ignore", "pipe", "inherit"],
+ }).trim();
+}
+
+function parseOptions(argv: string[]): Options {
+ let fixturePath: string | undefined;
+ let outputPath: string | undefined;
+ let rounds = 3;
+ for (let index = 0; index < argv.length; index += 1) {
+ const argument = argv[index]!;
+ const [name, inline] = argument.split("=", 2);
+ const value = inline ?? argv[++index];
+ if (name === "--fixture") fixturePath = value;
+ else if (name === "--output") outputPath = value;
+ else if (name === "--rounds") rounds = Number(value);
+ else usage(`Unknown argument: ${argument}`);
+ }
+ if (!fixturePath) usage("--fixture is required");
+ if (!Number.isSafeInteger(rounds) || rounds <= 0) {
+ usage("--rounds must be a positive integer");
+ }
+ return {
+ fixturePath: resolve(fixturePath),
+ rounds,
+ ...(outputPath === undefined ? {} : { outputPath: resolve(outputPath) }),
+ };
+}
+
+function usage(message: string): never {
+ process.stderr.write(`${message}\n`);
+ process.stderr.write(
+ "Usage: npx tsx benchmarks/homebrew-query/run-browser.ts " +
+ "--fixture PATH [--rounds 3] [--output PATH]\n",
+ );
+ process.exit(2);
+}
+
+void main().catch((error) => {
+ process.stderr.write(
+ `homebrew-query Chromium failed: ${error instanceof Error ? error.stack : error}\n`,
+ );
+ process.exitCode = 1;
+});
diff --git a/benchmarks/homebrew-query/run-node.ts b/benchmarks/homebrew-query/run-node.ts
new file mode 100644
index 0000000000..0223eeca7d
--- /dev/null
+++ b/benchmarks/homebrew-query/run-node.ts
@@ -0,0 +1,357 @@
+#!/usr/bin/env -S npx tsx
+
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { arch, cpus, platform, release } from "node:os";
+import { dirname, resolve } from "node:path";
+
+import { NodeKernelHost } from "../../host/src/node-kernel-host";
+import type { SyscallTraceEvent } from "../../host/src/kernel-worker";
+import type { LazyDownloadEvent } from "../../host/src/vfs/memory-fs";
+import type { ClosedLazyAsset } from "../../host/src/vfs/closed-lazy-assets";
+import {
+ assertHomebrewQueryFixture,
+ commandScript,
+ emptyProcessCounts,
+ medianMetrics,
+ summarizeLazyDownloads,
+ type HomebrewQueryArtifact,
+ type HomebrewQueryBenchmarkResult,
+ type HomebrewQueryCommand,
+ type HomebrewQueryCommandResult,
+ type HomebrewQueryFixtureManifest,
+ type HomebrewQueryNetworkAudit,
+ type HomebrewQueryProcessCounts,
+} from "./contracts";
+import {
+ runHomebrewQueryScenario,
+ type HomebrewQueryMachine,
+ type HomebrewQueryMachineFactory,
+} from "./scenario";
+
+interface Options {
+ fixturePath: string;
+ rounds: number;
+ outputPath?: string;
+}
+
+interface ProcessEvent {
+ kind: "spawn" | "exec" | "exit";
+}
+
+const COMMAND_TIMEOUT_MS = 10 * 60_000;
+const decoder = new TextDecoder("utf-8", { fatal: false });
+
+async function main(): Promise {
+ const options = parseOptions(process.argv.slice(2));
+ const fixtureRoot = dirname(options.fixturePath);
+ const fixture = JSON.parse(readFileSync(options.fixturePath, "utf-8"));
+ assertHomebrewQueryFixture(fixture);
+ const kernel = readVerifiedArtifact(fixtureRoot, fixture.kernel);
+ const lazyAssets = fixture.lazyAssets.map((artifact) => ({
+ url: artifact.url,
+ sha256: artifact.sha256,
+ size: artifact.bytes,
+ bytes: readVerifiedArtifact(fixtureRoot, artifact),
+ } satisfies ClosedLazyAsset));
+ const factory = new NodeHomebrewQueryMachineFactory(
+ fixtureRoot,
+ fixture,
+ kernel,
+ lazyAssets,
+ );
+ const rounds = [];
+ for (let index = 0; index < options.rounds; index += 1) {
+ process.stderr.write(`Homebrew query Node round ${index + 1}/${options.rounds}\n`);
+ rounds.push(await runHomebrewQueryScenario({
+ fixture,
+ machines: factory,
+ auditNetwork: index === 0,
+ }));
+ }
+ const result: HomebrewQueryBenchmarkResult = {
+ schema: 1,
+ kind: "kandelo-homebrew-query-benchmark-result",
+ host: "node",
+ hostVersion: process.version,
+ kandeloCommit: gitHead(),
+ recordedAt: new Date().toISOString(),
+ machine: {
+ platform: `${platform()} ${release()}`,
+ architecture: arch(),
+ cpu: cpus()[0]?.model ?? "unknown",
+ },
+ fixture,
+ rounds,
+ median: medianMetrics(rounds),
+ };
+ const encoded = `${JSON.stringify(result, null, 2)}\n`;
+ if (options.outputPath) {
+ mkdirSync(dirname(options.outputPath), { recursive: true });
+ writeFileSync(options.outputPath, encoded);
+ process.stderr.write(`Wrote ${options.outputPath}\n`);
+ }
+ process.stdout.write(encoded);
+}
+
+class NodeHomebrewQueryMachineFactory implements HomebrewQueryMachineFactory {
+ constructor(
+ private readonly fixtureRoot: string,
+ private readonly fixture: HomebrewQueryFixtureManifest,
+ private readonly kernel: Uint8Array,
+ private readonly lazyAssets: ClosedLazyAsset[],
+ ) {}
+
+ async create(image: "lazy" | "eager"): Promise {
+ const artifact = image === "lazy"
+ ? this.fixture.rootfs
+ : this.fixture.eagerRootfs;
+ if (!artifact) throw new Error("Eager Homebrew query image is unavailable");
+ return new NodeHomebrewQueryMachine(
+ this.fixture,
+ readVerifiedArtifact(this.fixtureRoot, artifact),
+ this.kernel,
+ image === "lazy" ? this.lazyAssets : undefined,
+ );
+ }
+}
+
+class NodeHomebrewQueryMachine implements HomebrewQueryMachine {
+ private readonly stdout: Uint8Array[] = [];
+ private readonly stderr: Uint8Array[] = [];
+ private readonly processEvents: ProcessEvent[] = [];
+ private readonly lazyEvents: LazyDownloadEvent[] = [];
+ private readonly host: NodeKernelHost;
+
+ constructor(
+ private readonly fixture: HomebrewQueryFixtureManifest,
+ image: Uint8Array,
+ private readonly kernel: Uint8Array,
+ lazyAssets?: ClosedLazyAsset[],
+ ) {
+ this.host = new NodeKernelHost({
+ maxWorkers: 4,
+ rootfsImage: image,
+ rootfsLazyUrlBase: fixture.lazyUrlBase,
+ ...(lazyAssets === undefined ? {} : { rootfsLazyAssets: lazyAssets }),
+ // A successful audited query with this backend disabled cannot have
+ // depended on an external request.
+ enableTcpNetwork: false,
+ onStdout: (_pid, value) => this.stdout.push(value.slice()),
+ onStderr: (_pid, value) => this.stderr.push(value.slice()),
+ onProcessEvent: (event) => this.processEvents.push(event),
+ onLazyDownload: (event) => this.lazyEvents.push(event),
+ });
+ }
+
+ async start(): Promise {
+ const startedAt = performance.now();
+ await this.host.init(wholeArrayBuffer(this.kernel));
+ return performance.now() - startedAt;
+ }
+
+ async run(command: HomebrewQueryCommand): Promise {
+ const stdoutStart = this.stdout.length;
+ const stderrStart = this.stderr.length;
+ const processStart = this.processEvents.length;
+ const lazyStart = this.lazyEvents.length;
+ const startedAt = performance.now();
+ const spawned = await this.host.spawnFromVfs(
+ this.fixture.shell.path,
+ [this.fixture.shell.argv0, "-l", "-c", commandScript(command)],
+ {
+ env: this.fixture.homebrew.environment,
+ cwd: "/home/user",
+ uid: 1000,
+ gid: 1000,
+ stdin: new Uint8Array(),
+ },
+ );
+ const status = await withTimeout(
+ spawned.exit,
+ COMMAND_TIMEOUT_MS,
+ `Homebrew query timed out: ${command.id}`,
+ );
+ const elapsedMs = performance.now() - startedAt;
+ const stdout = concatenate(this.stdout.slice(stdoutStart));
+ const stderr = concatenate(this.stderr.slice(stderrStart));
+ const invalidQueryOutput = command.id !== "shell_boot" && (
+ stdout.byteLength === 0 || stderr.byteLength !== 0
+ );
+ if (status !== 0 || invalidQueryOutput) {
+ throw new Error(
+ `Homebrew query ${command.id} did not produce clean output ` +
+ `(status=${status}, stdout=${stdout.byteLength}, ` +
+ `stderr=${stderr.byteLength}): ` +
+ decoder.decode(stderr).slice(-4_000),
+ );
+ }
+ return {
+ id: command.id,
+ argv: command.argv,
+ elapsedMs,
+ status,
+ stdoutBytes: stdout.byteLength,
+ stderrBytes: stderr.byteLength,
+ stdoutSha256: sha256(stdout),
+ stderrSha256: sha256(stderr),
+ processCounts: countProcessEvents(this.processEvents.slice(processStart)),
+ lazy: summarizeLazyDownloads(this.lazyEvents.slice(lazyStart)),
+ };
+ }
+
+ async auditNetwork(
+ commands: readonly HomebrewQueryCommand[],
+ ): Promise {
+ const events: SyscallTraceEvent[] = [];
+ const unsubscribe = this.host.subscribeSyscalls((event) => events.push(event));
+ try {
+ const output: HomebrewQueryNetworkAudit["commands"] = [];
+ for (const command of commands) {
+ const start = events.length;
+ const result = await this.run(command);
+ // Trace delivery is deliberately batched outside the syscall hot path.
+ await delay(350);
+ output.push({
+ id: command.id,
+ status: result.status,
+ networkSyscalls: countNetworkSyscalls(events.slice(start)),
+ });
+ }
+ return { commands: output };
+ } finally {
+ unsubscribe();
+ }
+ }
+
+ destroy(): Promise {
+ return this.host.destroy();
+ }
+}
+
+function countNetworkSyscalls(
+ events: readonly SyscallTraceEvent[],
+): Record {
+ const counts: Record = {};
+ for (const event of events) {
+ const name = event.decoded?.match(
+ /\]\s+(socket|connect|send|sendto|sendmsg|recv|recvfrom|recvmsg)\b/,
+ )?.[1];
+ if (name) counts[name] = (counts[name] ?? 0) + 1;
+ }
+ return counts;
+}
+
+function countProcessEvents(
+ events: readonly ProcessEvent[],
+): HomebrewQueryProcessCounts {
+ const counts = emptyProcessCounts();
+ for (const event of events) counts[event.kind] += 1;
+ return counts;
+}
+
+function readVerifiedArtifact(
+ fixtureRoot: string,
+ artifact: HomebrewQueryArtifact,
+): Uint8Array {
+ const path = resolve(fixtureRoot, artifact.file);
+ const value = readFileSync(path);
+ const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+ if (bytes.byteLength !== artifact.bytes || sha256(bytes) !== artifact.sha256) {
+ throw new Error(`Homebrew query artifact changed identity: ${path}`);
+ }
+ return bytes;
+}
+
+function concatenate(chunks: readonly Uint8Array[]): Uint8Array {
+ const output = new Uint8Array(
+ chunks.reduce((total, chunk) => total + chunk.byteLength, 0),
+ );
+ let offset = 0;
+ for (const chunk of chunks) {
+ output.set(chunk, offset);
+ offset += chunk.byteLength;
+ }
+ return output;
+}
+
+function wholeArrayBuffer(value: Uint8Array): ArrayBuffer {
+ return value.buffer.slice(
+ value.byteOffset,
+ value.byteOffset + value.byteLength,
+ ) as ArrayBuffer;
+}
+
+function sha256(value: Uint8Array): string {
+ return createHash("sha256").update(value).digest("hex");
+}
+
+function gitHead(): string {
+ return execFileSync("git", ["rev-parse", "HEAD"], {
+ encoding: "utf-8",
+ stdio: ["ignore", "pipe", "inherit"],
+ }).trim();
+}
+
+function delay(ms: number): Promise {
+ return new Promise((resolveDelay) => setTimeout(resolveDelay, ms));
+}
+
+async function withTimeout(
+ promise: Promise,
+ timeoutMs: number,
+ message: string,
+): Promise {
+ let timer: ReturnType | undefined;
+ try {
+ return await Promise.race([
+ promise,
+ new Promise((_resolve, reject) => {
+ timer = setTimeout(() => reject(new Error(message)), timeoutMs);
+ }),
+ ]);
+ } finally {
+ if (timer !== undefined) clearTimeout(timer);
+ }
+}
+
+function parseOptions(argv: string[]): Options {
+ let fixturePath: string | undefined;
+ let outputPath: string | undefined;
+ let rounds = 3;
+ for (let index = 0; index < argv.length; index += 1) {
+ const argument = argv[index]!;
+ const [name, inline] = argument.split("=", 2);
+ const value = inline ?? argv[++index];
+ if (name === "--fixture") fixturePath = value;
+ else if (name === "--output") outputPath = value;
+ else if (name === "--rounds") rounds = Number(value);
+ else usage(`Unknown argument: ${argument}`);
+ }
+ if (!fixturePath) usage("--fixture is required");
+ if (!Number.isSafeInteger(rounds) || rounds <= 0) {
+ usage("--rounds must be a positive integer");
+ }
+ return {
+ fixturePath: resolve(fixturePath),
+ rounds,
+ ...(outputPath === undefined ? {} : { outputPath: resolve(outputPath) }),
+ };
+}
+
+function usage(message: string): never {
+ process.stderr.write(`${message}\n`);
+ process.stderr.write(
+ "Usage: npx tsx benchmarks/homebrew-query/run-node.ts " +
+ "--fixture PATH [--rounds 3] [--output PATH]\n",
+ );
+ process.exit(2);
+}
+
+void main().catch((error) => {
+ process.stderr.write(
+ `homebrew-query Node failed: ${error instanceof Error ? error.stack : error}\n`,
+ );
+ process.exitCode = 1;
+});
diff --git a/benchmarks/homebrew-query/scenario.ts b/benchmarks/homebrew-query/scenario.ts
new file mode 100644
index 0000000000..e8b5bfcdd8
--- /dev/null
+++ b/benchmarks/homebrew-query/scenario.ts
@@ -0,0 +1,101 @@
+import type {
+ HomebrewQueryCommand,
+ HomebrewQueryCommandResult,
+ HomebrewQueryFixtureManifest,
+ HomebrewQueryNetworkAudit,
+ HomebrewQueryScenarioResult,
+} from "./contracts";
+
+export interface HomebrewQueryMachine {
+ start(): Promise;
+ run(command: HomebrewQueryCommand): Promise;
+ auditNetwork(
+ commands: readonly HomebrewQueryCommand[],
+ ): Promise;
+ destroy(): Promise;
+}
+
+export interface HomebrewQueryMachineFactory {
+ create(image: "lazy" | "eager"): Promise;
+}
+
+const SHELL_BOOT_COMMAND: HomebrewQueryCommand = {
+ id: "shell_boot",
+ argv: [":"],
+};
+
+export async function runHomebrewQueryScenario(options: {
+ fixture: HomebrewQueryFixtureManifest;
+ machines: HomebrewQueryMachineFactory;
+ auditNetwork: boolean;
+}): Promise {
+ const focus = options.fixture.commands.find(
+ (command) => command.id === options.fixture.focusCommandId,
+ )!;
+
+ const coldStartedAt = performance.now();
+ const coldMachine = await options.machines.create("lazy");
+ let cold: HomebrewQueryScenarioResult["cold"];
+ try {
+ const machineBootMs = await coldMachine.start();
+ const first = await coldMachine.run(focus);
+ const machineBootAndFirstBrewMs = performance.now() - coldStartedAt;
+ const warm = await coldMachine.run(focus);
+ cold = {
+ machineBootMs,
+ machineBootAndFirstBrewMs,
+ first,
+ warm,
+ };
+ } finally {
+ await coldMachine.destroy();
+ }
+
+ const bootedMachine = await options.machines.create("lazy");
+ try {
+ const bootedMachineBootMs = await bootedMachine.start();
+ const shellBoot = await bootedMachine.run(SHELL_BOOT_COMMAND);
+ const first: HomebrewQueryCommandResult[] = [];
+ const repeated: HomebrewQueryCommandResult[] = [];
+ for (const command of options.fixture.commands) {
+ first.push(await bootedMachine.run(command));
+ }
+ for (const command of options.fixture.commands) {
+ repeated.push(await bootedMachine.run(command));
+ }
+ const networkAudit = options.auditNetwork
+ ? await bootedMachine.auditNetwork(options.fixture.commands)
+ : undefined;
+
+ let eager: HomebrewQueryScenarioResult["eager"];
+ if (options.fixture.eagerRootfs !== undefined) {
+ const eagerMachine = await options.machines.create("eager");
+ try {
+ const machineBootMs = await eagerMachine.start();
+ const eagerShellBoot = await eagerMachine.run(SHELL_BOOT_COMMAND);
+ eager = {
+ machineBootMs,
+ shellBootMs: eagerShellBoot.elapsedMs,
+ first: await eagerMachine.run(focus),
+ warm: await eagerMachine.run(focus),
+ };
+ } finally {
+ await eagerMachine.destroy();
+ }
+ }
+
+ return {
+ cold,
+ booted: {
+ machineBootMs: bootedMachineBootMs,
+ shellBootMs: shellBoot.elapsedMs,
+ first,
+ warm: repeated,
+ },
+ ...(eager === undefined ? {} : { eager }),
+ ...(networkAudit === undefined ? {} : { networkAudit }),
+ };
+ } finally {
+ await bootedMachine.destroy();
+ }
+}
diff --git a/crates/wasm-local-root-spill/Cargo.toml b/crates/wasm-local-root-spill/Cargo.toml
index f08b281954..f7bbc82752 100644
--- a/crates/wasm-local-root-spill/Cargo.toml
+++ b/crates/wasm-local-root-spill/Cargo.toml
@@ -18,8 +18,8 @@ path = "src/lib.rs"
anyhow = "1"
clap = { version = "4", features = ["derive"] }
walrus = "0.26"
+wasmparser = "0.247"
[dev-dependencies]
-wasmparser = "0.247"
wasmprinter = "0.247"
wat = "1"
diff --git a/crates/wasm-local-root-spill/README.md b/crates/wasm-local-root-spill/README.md
index 63f54819f7..c37ffa3545 100644
--- a/crates/wasm-local-root-spill/README.md
+++ b/crates/wasm-local-root-spill/README.md
@@ -107,7 +107,9 @@ and browser hosts diverge.
These are deliberate limits of the first Ruby-focused implementation:
- only the `ruby` profile is accepted;
-- only wasm32 modules with a mutable `i32` `__stack_pointer` are supported;
+- wasm32 main modules must expose a mutable `i32` `__stack_pointer`; a
+ `dylink.0` side module whose linker omitted an otherwise-unused stack pointer
+ imports the process-wide global before spill frames are added;
- only 32-bit `VALUE`-like roots are spilled;
- `i64`, `f32`, `f64`, `v128`, and reference-typed values are not root slots;
- memory64 and runtimes that depend on Wasm GC refs are unsupported;
diff --git a/crates/wasm-local-root-spill/src/lib.rs b/crates/wasm-local-root-spill/src/lib.rs
index f144810662..13bf55533e 100644
--- a/crates/wasm-local-root-spill/src/lib.rs
+++ b/crates/wasm-local-root-spill/src/lib.rs
@@ -30,6 +30,7 @@ use walrus::{
TryTable, TryTableCatch, UnaryOp, Value,
},
};
+use wasmparser::{Parser, Payload};
#[derive(Debug, Clone)]
pub struct Options {
@@ -84,7 +85,8 @@ pub fn spill(input: &[u8], opts: &Options) -> Result> {
let mut module =
Module::from_buffer(input).context("failed to parse input wasm module for root spill")?;
- let stack_pointer = find_stack_pointer(&module)?;
+ let stack_pointer =
+ find_or_import_stack_pointer(&mut module, input_starts_with_dylink(input)?)?;
let memory = find_wasm32_memory(&module)?;
let targets: Vec = module
@@ -101,7 +103,79 @@ pub fn spill(input: &[u8], opts: &Options) -> Result> {
.with_context(|| format!("spilling {}", function_name(&module, func_id)))?;
}
- Ok(module.emit_wasm())
+ let output = module.emit_wasm();
+ restore_leading_dylink_section(input, output)
+}
+
+/// Walrus emits raw custom sections after the standard sections. Ruby native
+/// extensions are Wasm side modules, whose `dylink.0` section must remain the
+/// first section for the dynamic loader to recognize them. Preserve that
+/// input ordering after adding root spill frames; otherwise protecting a
+/// native extension from GC would make the same extension unloadable.
+fn restore_leading_dylink_section(input: &[u8], output: Vec) -> Result> {
+ if !input_starts_with_dylink(input)? {
+ return Ok(output);
+ }
+
+ let mut dylink_range = None;
+ for payload in Parser::new(0).parse_all(&output) {
+ if let Payload::CustomSection(section) = payload? {
+ if section.name() != "dylink.0" {
+ continue;
+ }
+ ensure!(
+ dylink_range.is_none(),
+ "root-spilled module contains more than one dylink.0 section"
+ );
+ dylink_range = Some(section.range());
+ }
+ }
+
+ let payload_range = dylink_range.context(
+ "input shared module started with dylink.0, but the root-spilled output lost it",
+ )?;
+ let payload_len = u32::try_from(payload_range.len())
+ .context("dylink.0 section is too large for a wasm section")?;
+ let section_header_len = 1 + u32_leb_len(payload_len);
+ let section_start = payload_range
+ .start
+ .checked_sub(section_header_len)
+ .context("dylink.0 section range does not include a valid header")?;
+ ensure!(
+ section_start >= 8 && output.get(section_start) == Some(&0),
+ "dylink.0 section does not have a valid custom-section header"
+ );
+ if section_start == 8 {
+ return Ok(output);
+ }
+
+ let mut reordered = Vec::with_capacity(output.len());
+ reordered.extend_from_slice(&output[..8]);
+ reordered.extend_from_slice(&output[section_start..payload_range.end]);
+ reordered.extend_from_slice(&output[8..section_start]);
+ reordered.extend_from_slice(&output[payload_range.end..]);
+ Ok(reordered)
+}
+
+fn input_starts_with_dylink(input: &[u8]) -> Result {
+ let mut payloads = Parser::new(0).parse_all(input);
+ let _version = payloads
+ .next()
+ .transpose()
+ .context("parsing input wasm header")?;
+ Ok(matches!(
+ payloads.next().transpose()?,
+ Some(Payload::CustomSection(section)) if section.name() == "dylink.0"
+ ))
+}
+
+fn u32_leb_len(mut value: u32) -> usize {
+ let mut len = 1;
+ while value >= 0x80 {
+ value >>= 7;
+ len += 1;
+ }
+ len
}
fn spill_function(
@@ -1199,7 +1273,7 @@ fn emit_store_local(
push(out, store_i32(memory, offset), loc());
}
-fn find_stack_pointer(module: &Module) -> Result {
+fn find_or_import_stack_pointer(module: &mut Module, is_side_module: bool) -> Result {
let from_export = module.exports.iter().find_map(|export| match export.item {
ExportItem::Global(id) if export.name == "__stack_pointer" => Some(id),
_ => None,
@@ -1211,7 +1285,22 @@ fn find_stack_pointer(module: &Module) -> Result {
.find(|global| global.name.as_deref() == Some("__stack_pointer"))
.map(|global| global.id())
});
- let id = id.context("mutable i32 `__stack_pointer` global not found")?;
+ let id = match id {
+ Some(id) => id,
+ None if is_side_module => {
+ // WHY: wasm-ld omits __stack_pointer from a side module when the
+ // original object code needs no linear stack. Root spilling can
+ // still need a frame for live GC roots, as in a call-bearing Ruby
+ // extension initializer. Import the process's existing stack
+ // pointer exactly as wasm-ld does for side modules that happened
+ // to use stack storage; this adds no private stack or host ABI.
+ let (id, _) =
+ module.add_import_global("env", "__stack_pointer", ValType::I32, true, false);
+ module.exports.add("__stack_pointer", id);
+ id
+ }
+ None => bail!("mutable i32 `__stack_pointer` global not found"),
+ };
let global = module.globals.get(id);
ensure!(
global.ty == ValType::I32 && global.mutable,
diff --git a/crates/wasm-local-root-spill/tests/root_spill.rs b/crates/wasm-local-root-spill/tests/root_spill.rs
index d287394ad4..df2b1e5e21 100644
--- a/crates/wasm-local-root-spill/tests/root_spill.rs
+++ b/crates/wasm-local-root-spill/tests/root_spill.rs
@@ -1,5 +1,5 @@
use walrus::{
- ExportItem, FunctionId, FunctionKind, GlobalId, LocalFunction, Module,
+ ExportItem, FunctionId, FunctionKind, GlobalId, ImportKind, LocalFunction, Module,
ir::{self, Instr, InstrSeqId},
};
use wasm_local_root_spill::{Options, SpillSet, spill};
@@ -225,6 +225,61 @@ fn rejects_missing_stack_pointer() {
assert!(format!("{err:#}").contains("__stack_pointer"));
}
+#[test]
+fn imports_process_stack_pointer_for_stackless_side_module() {
+ let wat = r#"
+ (module
+ (@custom "dylink.0" (before first) "test metadata")
+ (import "env" "memory" (memory 1))
+ (import "env" "alloc" (func $alloc))
+ (func $main (export "main") (param $root i32) (result i32)
+ call $alloc
+ local.get $root))
+ "#;
+
+ let bytes = spill_wat(wat);
+ validate(&bytes);
+ let module = module(&bytes);
+ let stack_pointer = stack_pointer(&module);
+
+ assert!(module.imports.iter().any(|import| {
+ import.module == "env"
+ && import.name == "__stack_pointer"
+ && matches!(import.kind, ImportKind::Global(id) if id == stack_pointer)
+ }));
+ assert_eq!(count_stack_pointer_sets(&module, "main"), 2);
+}
+
+#[test]
+fn keeps_side_module_dylink_section_first() {
+ let wat = r#"
+ (module
+ (@custom "dylink.0" (before first) "test metadata")
+ (memory (export "memory") 1)
+ (global $__stack_pointer
+ (export "__stack_pointer") (mut i32) (i32.const 65536))
+ (func $alloc)
+ (func $main (export "main") (param $root i32) (result i32)
+ call $alloc
+ local.get $root))
+ "#;
+
+ let bytes = spill_wat(wat);
+ validate(&bytes);
+ let mut payloads = wasmparser::Parser::new(0).parse_all(&bytes);
+ assert!(matches!(
+ payloads.next().unwrap().unwrap(),
+ wasmparser::Payload::Version { .. }
+ ));
+ match payloads.next().unwrap().unwrap() {
+ wasmparser::Payload::CustomSection(section) => {
+ assert_eq!(section.name(), "dylink.0");
+ assert_eq!(section.data(), b"test metadata");
+ }
+ other => panic!("dylink.0 must remain the first section, got {other:?}"),
+ }
+}
+
#[test]
fn spills_operand_stack_i32_carryover_across_call() {
let wat = fixture(
diff --git a/docs/homebrew-packaging-system.md b/docs/homebrew-packaging-system.md
index 3eb96b5780..a32db1cb74 100644
--- a/docs/homebrew-packaging-system.md
+++ b/docs/homebrew-packaging-system.md
@@ -488,9 +488,17 @@ not turn an arbitrary URL in VFS metadata into network authority.
Guest Homebrew has two separate inputs:
1. `homebrew-bootstrap` contains one reviewed upstream Homebrew source
- tree plus Kandelo's guest-platform patch and environment policy.
-2. A bottle-backed runtime-support closure supplies Ruby and the
- ordinary tools that Homebrew needs.
+ tree plus Kandelo's guest-platform patch, environment policy, and the
+ source-selected portable Ruby as separate authenticated outputs.
+2. A bottle-backed runtime-support closure supplies the ordinary tools that
+ Homebrew needs.
+
+Portable Ruby uses Homebrew's standard
+`Library/Homebrew/vendor/portable-ruby/` layout and `current`
+symlink. The version is read from the exact Homebrew source tree, and the
+guest prefix is derived from the authenticated deferred-tree descriptor.
+Neither the compatibility prefix nor the future canonical prefix is encoded
+in the portable-Ruby composition logic.
The base shell can expose `/usr/bin/brew` as a lazy activation
reference. A user who never runs `brew` does not pay the bootstrap and
diff --git a/docs/homebrew-publishing.md b/docs/homebrew-publishing.md
index 5ebba2ae7c..3968ad15d1 100644
--- a/docs/homebrew-publishing.md
+++ b/docs/homebrew-publishing.md
@@ -147,20 +147,33 @@ for dispatch, recovery, seal-last publication, and mutation handling.
## Guest Homebrew Bootstrap Bottle
The patched Homebrew Ruby tree used by a guest is the support-data Formula
-`homebrew-bootstrap`. Its bottle contains two declared `libexec` members:
+`homebrew-bootstrap`. Its bottle contains three declared `libexec` members:
`homebrew-bootstrap.zip`, built from one sealed Homebrew checkout and the
reviewed guest-platform patch, and `homebrew-brew.env`, which owns the matching
-architecture and system-environment policy. The tap-native recipe lock at
-`Kandelo/recipes/homebrew-bootstrap/source-lock.json` binds both outputs by
-path, SHA-256, and byte count.
+architecture and system-environment policy, plus
+`homebrew-portable-ruby.zip`. The latter packages the source-selected Ruby
+dependency in Homebrew's standard versioned vendor layout, including the
+`current` symlink and the real Bootsnap and msgpack gems. Bootsnap's only
+guest-platform patch extends its upstream supported-platform test to Ruby's
+Wasm target; the cache and loader remain Bootsnap's implementation. The
+tap-native recipe lock at
+`Kandelo/recipes/homebrew-bootstrap/source-lock.json` binds all three outputs
+by path, SHA-256, and byte count.
The product shell fetches that public bottle anonymously. The shared typed
extractor binds the exact tap checkout, aggregate catalog and Formula sidecar,
recipe lock, link manifest, bottle digest and size, keg identity, immutable
-build receipt, and both output members. The shell composer reruns the same
+build receipt, and all three output members. The shell composer reruns the same
typed verifier against the detached files before embedding its canonical
report. It does not consult the Kandelo package registry for these bytes.
+The composer reads
+`Library/Homebrew/vendor/portable-ruby-version` from the authenticated source
+ZIP and requires the portable-Ruby output to expose that exact version. It
+derives the vendor mount and executable from the bootstrap descriptor's guest
+prefix. This preserves Homebrew's normal portable-Ruby detection and startup
+without encoding either the compatibility or canonical Kandelo prefix.
+
Browser builds preserve that ownership. Their publication workflows
extract `homebrew-bootstrap.zip` from the verified support-data bottle
and stage it at the same-origin `homebrew-bootstrap.zip` URL used by the
@@ -3776,6 +3789,15 @@ hardlink aliases for `@@HOMEBREW_PREFIX@@`, `@@HOMEBREW_CELLAR@@`,
receipt-selected `@@HOMEBREW_JAVA@@` replacement. The eager composer uses the
same browser-safe relocation implementation.
+Read-only package discovery must not activate an otherwise unused bottle just
+to read its standard metadata. For every deferred Formula, the shell composer
+therefore copies the exact authenticated `.brew/.rb` and
+`INSTALL_RECEIPT.json` bytes from the verified pour into the image. It removes
+only those guest entries from the deferred projection; the complete bottle
+source inventory, payload digest, and byte count remain authoritative. The
+materialization evidence hashes the eager metadata independently. This is an
+exact projection of upstream bottle members, not reconstructed Homebrew state.
+
First use still fetches and verifies the complete unmodified `.tar.gz`; the
content digest and byte count never describe relocated or recompressed bytes.
After decoding and complete source-inventory validation, the runtime requires
@@ -4032,13 +4054,13 @@ or stale compatibility link fail before browser acceptance.
The shell closure does not by itself claim that `/usr/bin/brew` can run.
`homebrew/main-shell-homebrew-runtime-support.json` declares a second,
first-use atomic layer. It binds the lazy `homebrew-bootstrap` bottle's
-extracted source and launcher outputs to seven reviewed runtime roots—Ruby,
-Git, curl, Findutils, Gawk, Tar, and `posix-utils-lite`—and to their exact
-dependency-first closure derived from the selected tap metadata. Dependencies
-already present in the complete shell remain shared. Any additional dependency
-is another atomic lazy bottle tree; for example, a Ruby bottle that declares
-`libyaml` adds both `libyaml` and Ruby beyond the base closure. The finalizer
-derives this difference instead of preserving a stale hand-counted inventory.
+extracted source, launcher, and portable-Ruby outputs to six reviewed Formula
+roots—Git, curl, Findutils, Gawk, Tar, and `posix-utils-lite`—and to their
+exact dependency-first closure derived from the selected tap metadata.
+Dependencies already present in the complete shell remain shared. Any
+additional Formula dependency is another atomic lazy bottle tree. The
+finalizer derives this difference instead of preserving a stale hand-counted
+inventory.
The availability audit includes every Formula considered during the runtime
rollout plus any newly selected runtime dependency. Every member must have an
diff --git a/docs/measurements/2026-08-04-homebrew-query-performance.md b/docs/measurements/2026-08-04-homebrew-query-performance.md
new file mode 100644
index 0000000000..63de972689
--- /dev/null
+++ b/docs/measurements/2026-08-04-homebrew-query-performance.md
@@ -0,0 +1,399 @@
+# In-guest Homebrew query performance — 2026-08-04
+
+## Status and scope
+
+This record contains the final three-round focused benchmark and the required
+repository-wide before/after benchmark. The implementation commit is
+`58e0c41e63d46f403d211c0aabfe7bb51baa9987`, based on protected `main`
+commit `880e5be7d2dbd3772602ff7eaed952c0b8c6608f`. The focused fixture records
+producer commit `5a025d98a5f6f1856618f0309c4ad7144dc78e52`. The deployed rev22
+compatibility-shell baseline records commit
+`00e30e1aeb9a1b691b2fd8ffcf0cf7ef561aab3c`.
+
+The rev22 and candidate shell images necessarily contain different runtime
+artifacts and tap-core revisions, so their focused numbers are a deployed
+product comparison, not an exact-artifact A/B. Each individual Node/browser
+pair used the same immutable image, kernel, taps, lazy bytes, command inputs,
+and environment. The repository-wide comparison used freshly built hosts at
+protected `main` and the candidate with identical benchmark workload
+artifacts, whose digests are recorded by the benchmark runner.
+
+The retained implementation does not reuse JavaScript Realms. A process may
+consume a pristine prestarted Worker, but that Worker is one-shot and is
+terminated after the process retires. Unused reserve Workers contain no guest
+memory. This preserves process isolation and lets Kandelo release every
+reference it owns to the process `SharedArrayBuffer` (SAB) and
+`WebAssembly.Memory`.
+
+## Exact diagnostic inputs
+
+The final focused Node and Chromium results were recorded on 2026-08-04 at
+`2026-08-04T20:37:42.645Z` and `2026-08-04T20:43:45.208Z` with:
+
+- Apple M5 Max, arm64, Darwin 25.6.0;
+- Node.js `v24.15.0`;
+- Chrome for Testing `149.0.7827.55` for the matched browser attempt;
+- kernel SHA-256
+ `bf11b2a61959cacfb05fb3f21cdbba8b8109ea56231379c07adf1f4f4365ecfd`;
+- lazy rootfs SHA-256
+ `b270afb52a0c36e6c23c95290c1c24fed295d9998e2e70fa60921bf821f9f571`;
+- eager rootfs SHA-256
+ `b5c819b196a1d8953f059f4b95135116581cb6bb271f6baa56e81e4bd6e865dc`;
+- `kandelo-dev/tap-core` commit
+ `28ddbc5352749f217ad89bf010e0f16b7e4b3d81`; and
+- `brandonpayton/kandelo-canary` commit
+ `b86d1810c68e3ab17bdab218856da3a7516ec95c`.
+
+The fixture used the deployed compatibility prefix
+`/home/linuxbrew/.linuxbrew`. The implementation derives that prefix from
+authenticated descriptors; the benchmark and runtime do not assume it.
+
+Every command received:
+
+```text
+HOMEBREW_NO_AUTO_UPDATE=1
+HOMEBREW_NO_INSTALL_FROM_API=1
+HOMEBREW_NO_ANALYTICS=1
+```
+
+The workload covered `brew --version`, `brew config`, both text and JSON v2
+`brew info` for `kandelo-dev/tap-core/dash`, `brew list --versions`, and
+`brew info brandonpayton/kandelo-canary/m4-canary`.
+
+Node ran with its TCP backend disabled. The first round also traced guest
+socket syscalls. Every measured command reported an empty network-syscall
+map. Chromium served only the closed local fixture and rejected other
+requests. No measured query depended on the public network.
+
+## Final focused result
+
+These are host-side monotonic medians from three independent rounds. Each
+Chromium round launched a fresh browser so a prior renderer, Worker, Realm,
+memory, or shared buffer could not survive into the next sample:
+
+| Phase | Node | Chromium |
+| --- | ---: | ---: |
+| Machine boot | 867 ms | 1,109 ms |
+| Cold first invocation | 9,586 ms | 9,106 ms |
+| Cold boot plus first invocation | 10,455 ms | 10,232 ms |
+| Immediate repeat on that machine | 4,920 ms | 5,335 ms |
+| First invocation after a shell was booted | 5,616 ms | 5,385 ms |
+| Repeated warm invocation | 4,616 ms | 5,005 ms |
+| Eager-image first invocation | 7,110 ms | 6,415 ms |
+| Eager-image warm invocation | 4,594 ms | 5,059 ms |
+
+The cold query fetched seven closed lazy assets totaling 28,040,511 bytes.
+Those assets were the Homebrew source tree, portable Ruby, and the ordinary
+tools actually executed by the runtime. The warm query fetched zero bytes.
+Thus a second `brew info` is not waiting on the already materialized lazy
+references; it repeats process startup, Ruby loading, discovery, and parsing.
+
+Warm values for the complete command set were:
+
+| Command | Node | Chromium |
+| --- | ---: | ---: |
+| `brew --version` | 484 ms | 914 ms |
+| `brew config` | 5,570 ms | 15,532 ms |
+| text `brew info` | 4,616 ms | 5,005 ms |
+| JSON v2 `brew info` | 4,908 ms | 5,544 ms |
+| `brew list --versions` | 3,729 ms | 3,789 ms |
+| canary `brew info` | 5,399 ms | 6,181 ms |
+
+Every command completed successfully with nonempty standard output and empty
+standard error. Node and Chromium produced the same output digest for each
+command. The Chromium `brew config` result remained unusually noisy and slow;
+the table reports its median rather than treating the earlier low sample as
+representative.
+
+The deployed rev22 Node baseline and candidate compare as follows. This is a
+product-level comparison with the exact revisions disclosed above, not an
+exact-artifact micro A/B:
+
+| Metric | Rev22 | Candidate | Reduction |
+| --- | ---: | ---: | ---: |
+| Cold boot plus first `brew info` | 27,052 ms | 10,455 ms | 61.4% (2.59x) |
+| Immediate warm `brew info` | 26,081 ms | 4,920 ms | 81.1% (5.30x) |
+| Booted warm `brew info` | 25,560 ms | 4,616 ms | 81.9% (5.54x) |
+| Warm JSON v2 `brew info` | 28,633 ms | 4,908 ms | 82.9% (5.83x) |
+| Warm `brew config` | 30,814 ms | 5,570 ms | 81.9% (5.53x) |
+| Warm `brew list --versions` | 20,390 ms | 3,729 ms | 81.7% (5.47x) |
+| Warm canary `brew info` | 31,745 ms | 5,399 ms | 83.0% (5.88x) |
+
+Chrome 149 consistently lost the renderer on rev22 before the harness could
+produce one valid complete round. Required-unused rootfs bytes and disabling
+Wasm tier-up did not make rev22 complete, so there is no honest Chromium
+"before" duration. The candidate completed all three isolated Chromium rounds;
+its values are reported above without fabricating a speedup ratio.
+
+## Attribution
+
+### Warm Ruby and syscall timeline
+
+A sampled 6,674.7 ms Ruby worker profile attributed self time as follows:
+
+| Ruby worker frame | Sampled self time |
+| --- | ---: |
+| libc syscall path | 3,728.3 ms |
+| Ruby parser | 591.6 ms |
+| Ruby VM core | 179.3 ms |
+| Ruby lexer | 92.7 ms |
+| compiler helper | 63.5 ms |
+
+The syscall figure includes time waiting for the kernel Worker. A separate
+host-side timing of the synchronous kernel work for a 5,960.6 ms warm query
+accounted for 1,367.3 ms:
+
+| Operation | Calls | Kernel time |
+| --- | ---: | ---: |
+| `open` | 4,694 | 1,064.6 ms |
+| `stat` | 2,068 | 169.7 ms |
+| `realpath` | 1,236 | 71.8 ms |
+| `read` | 4,055 | 8.9 ms |
+| `readlink` | 170 | 6.6 ms |
+| `close` | 3,120 | 5.8 ms |
+
+The difference between Ruby's syscall-wait samples and synchronous kernel
+work is channel transfer, scheduling, wakeup, and time spent behind other
+processes. The file bytes are already memory-resident on a warm run, but each
+POSIX call still crosses from Wasm libc through the shared channel to the
+dedicated kernel Worker and back. Thousands of individually cheap lookups
+therefore remain expensive.
+
+### Why so many absent paths are opened
+
+This is mostly normal CRuby and Homebrew behavior, amplified by Kandelo's
+per-syscall cost:
+
+- Homebrew's generated Bundler setup adds 85 vendor load paths that are absent
+ in this production runtime. There are 107 Ruby load-path entries in total;
+ 22 exist.
+- For a feature backed by a native extension, CRuby searches `.rb` candidates
+ across load paths before searching `.so` candidates. Bootsnap itself is a
+ concrete example: the genuine extension exists, but ordinary lookup probes
+ earlier Ruby-source candidates first.
+- RubyGems, Git, curl, Bash login startup, and Homebrew command discovery also
+ test optional configuration and platform paths whose absence is meaningful.
+
+Classifying the 4,694 open paths against the resulting VFS found 3,115 calls
+to paths absent after the run, including 2,135 under Homebrew's vendor bundle.
+A separate full result trace observed about 2,500 actual `ENOENT` opens per
+warm invocation. These failed opens are not VFS corruption: returning
+`ENOENT` is the required observable result. Removing candidates in Kandelo or
+lying about their existence would change Ruby/Homebrew behavior.
+
+Bootsnap is now the real upstream gem in the real portable-Ruby layout. It
+reduces repeated load-path scans where Homebrew enables it, but it cannot make
+every optional-path probe disappear. Preloading a generated Bootsnap cache
+added about 2 MiB to the image and did not improve the controlled workload.
+
+### Process cost and Ruby's `posix_spawn` patch
+
+The text `brew info` command created 159 processes and performed 55 execs in
+the focused result. A detailed trace counted 158 forks. Of those, 90 occurred
+inside Bash-based Git shims, 32 inside the Bash curl shim, and 29 in the outer
+`brew.sh` path. Only four were issued by Ruby; three belonged to the outer
+`bin/brew` path. Ruby also created seven threads.
+
+Therefore the Ruby patch that selects `posix_spawn()` instead of `vfork()` is
+not the primary cause of this query's fork count. Bash uses ordinary `fork()`
+for these scripts and has no relevant build-time switch that converts them to
+`posix_spawn()`. An ABI-43 `vfork()` experiment reduced the focused query by
+only about 2.3–2.4% and regressed broader startup controls by 37–50%. That
+candidate is not part of this ABI-42 work.
+
+### Lazy metadata and image cost
+
+`INSTALL_RECEIPT.json` and `.brew/.rb` are upstream bottle members.
+Previously, reading either from a deferred Formula activated the complete
+bottle transport. The candidate embeds those exact authenticated member bytes
+while retaining the complete source inventory and bottle digest for later
+whole-archive validation.
+
+The measured compressed shell image grew from 5,754,898 to 5,782,818 bytes:
+27,920 bytes. In a closed zlib control this avoided a 107,543-byte bottle
+fetch. Local wall time was neutral because the closed asset had no network
+latency and Ruby startup dominated, but the ownership and transfer behavior
+are now correct for metadata-only access.
+
+The immutable benchmark fixture's portable-Ruby artifact costs:
+
+| Artifact | Size |
+| --- | ---: |
+| Lazy ZIP download | 12,184,183 bytes (11.62 MiB) |
+| Expanded portable tree | 41,331,702 bytes (39.42 MiB) |
+| Main `ruby.wasm` within the tree | 21,365,256 bytes (20.38 MiB) |
+| Files in the expanded tree | 2,493 |
+
+This is paid only on first Homebrew activation in the lazy shell. It supplies
+Homebrew's standard versioned Ruby tree plus the real Bootsnap and msgpack
+gems. A narrow Bootsnap patch adds Ruby's Wasm platform to its upstream
+supported-platform predicate; it does not replace the load-path cache. There
+is no separate system-Ruby compatibility path.
+
+The final clean package rebuild produced a 12,184,488-byte (11.62 MiB)
+portable-Ruby ZIP, a 41,331,878-byte (39.42 MiB) expanded tree with 2,493
+members, and a 21,365,814-byte (20.38 MiB) main `ruby.wasm`. The fixture is
+305 bytes smaller because it predates the final build-tool-only correction;
+the runtime composition and measured behavior are the same.
+
+### Upstream patch accounting
+
+This work does not patch `brew info`, formula discovery, Ruby `require`,
+Bundler's generated paths, or Bootsnap's cache algorithm. It uses upstream
+Homebrew, CRuby, msgpack, and Bootsnap through their normal runtime paths.
+
+Kandelo already carried three reviewed compatibility changes before this
+investigation:
+
+- Homebrew's source is patched to recognize Kandelo's Wasm bottle tags and
+ prefix relocation contract;
+- CRuby selects Kandelo's non-forking `posix_spawn()` path for commands whose
+ requested process attributes can be represented faithfully; and
+- CRuby keeps command-line `-r` library roots visible across Kandelo's
+ fork-instrumented startup path.
+
+The only new patch to upstream source is
+`packages/registry/ruby/patches/bootsnap-wasm-platform.patch`. It adds `wasm`
+to three existing supported-platform regular expressions. Bootsnap 1.24.5
+otherwise rejects the target before running its genuine loader and compile
+caches. The patch changes no cache, path, or fallback semantics.
+
+The remaining Ruby work is build configuration and Kandelo platform support:
+the package follows Homebrew's portable-Ruby directory layout, stages the
+exact upstream msgpack and Bootsnap gems by digest, builds their ordinary
+native extensions as Wasm side modules, and loads those modules through
+Kandelo's general `dlopen()` implementation. That support is not conditional
+on Homebrew or on a Brew subcommand.
+
+## Retained improvements
+
+The old system-Ruby diagnostic took 23,601 ms and emitted 92,678 traced
+syscalls, including 54,206 opens and 9,070 readlinks. A comparable instrumented
+portable-Ruby diagnostic took 7,050 ms with 29,221 traced syscalls, 4,694
+opens, and 170 readlinks. The final uninstrumented three-round warm medians are
+4,616 ms on Node and 5,005 ms on Chromium. The traced pair identifies the
+dominant improvement: use Homebrew's real portable Ruby and upstream load-path
+cache path.
+
+Two platform-owned changes have separate controlled evidence:
+
+- resolving an existing HostFS prefix without redundant component-by-component
+ host calls reduced a cold query from about 12.13 s to 8.97 s, roughly 3.2 s;
+ the fast path falls back whenever a symlink or missing component requires
+ full POSIX resolution; and
+- pristine one-shot prestarted process Workers saved about 1.5–1.8 s without
+ reusing a Realm or retaining a used Worker's process memory.
+
+Directory indexes, cached channel views, syscall classification, polling,
+main-thread kernel execution, and Realm reuse are not part of the retained
+implementation. Experiments with broader SharedFS indexing and cache
+preloading were wall-time neutral or worse and were reverted.
+
+## Chromium boundary
+
+Chrome for Testing 149 originally lost the renderer after repeatedly compiling
+the same 20.38 MiB Ruby module in fresh process Workers. Stock Ruby reproduced
+the failure on launch 13; a diagnostic Ruby with a smaller linear memory
+reproduced it on launch 4. Disabling V8's Wasm tier-up made 20 launches
+complete, which isolated the failure from guest linear-memory retention.
+
+The retained candidate caches the immutable compiled `WebAssembly.Module` in
+the machine's centralized kernel Worker. It does not reuse process Workers,
+Realms, memories, or syscall channels. A rapid stock-Ruby test with ordinary
+V8 tiering completed 20 of 20 launches. It created 65 Workers, peaked at seven
+live Workers, and ended with only the centralized kernel Worker alive.
+
+Cache hits compare the current VFS executable byte-for-byte against a private
+copy before reusing compiled code. Exact content reached through several paths
+shares one entry; path and `argv[0]` behavior do not change. This matters for
+multicall programs: seven coreutils paths in the trace were the same 4.75 MiB
+executable, and both Bash paths were the same 3.35 MiB executable. A path-only
+cache exceeded its 64 MiB budget, evicted Ruby, and reproduced the crash on the
+second query. Content deduplication held the complete query working set as
+eight unique modules and 16 aliases in 44,845,570 comparison bytes with zero
+evictions.
+
+The stock Ruby comparison took about 3.4 ms per lookup in a Node
+micro-measurement. Ruby accounts for 21,365,256 of the retained comparison
+bytes, plus V8-owned compiled code whose size is not exposed. The cache is
+bounded to 16 content entries, 256 path aliases, and 64 MiB of comparison bytes
+per machine. A clean Node A/B/A used five invocations per machine. The four
+warm values were 4,738–4,916 ms with the cache, 6,701–8,354 ms with capacity
+set to zero, and 4,729–4,930 ms after restoring it. Warm medians were 4,804,
+7,460, and 4,831 ms respectively: about a 35% reduction in this focused
+control. Cold values were 10,088, 10,398, and 9,834 ms. This is evidence for
+the mechanism, not the required three-round performance result.
+
+With exact-content deduplication, the three independent complete Chromium
+rounds covered cold and warm machines, every command, the eager control, and
+the network audit without a renderer loss. Their medians were 9,106 ms cold,
+5,335 ms immediate warm, 5,385 ms first on the booted command-sequence
+machine, 5,005 ms repeated warm, 6,415 ms eager first, and 5,059 ms eager
+warm. All six audited commands reported zero network syscalls.
+
+Stock Ruby still grows one process memory to 303,300,608 bytes (289.25 MiB).
+Exactly 256 MiB comes from CRuby 4.0.5's optional red-black object-shape cache:
+native Ruby reserves it through sparse `mmap`, while Wasm linear memory grows
+contiguously. A no-cache diagnostic reduced the final memory to 33.25 MiB, but
+no Ruby source special case is retained. That upstream/configuration boundary
+is separate from the compiled-module lifecycle fix.
+
+The remaining 256 MiB Ruby object-shape reservation is not retained by a
+terminated process Worker, but it makes every live Ruby process expensive.
+Changing that upstream/configuration choice remains follow-up work rather than
+part of this performance claim.
+
+## Repository-wide performance contract
+
+Freshly built protected `main` and candidate hosts ran these required commands
+with three rounds and matching workload artifacts:
+
+```text
+npx tsx benchmarks/run.ts --rounds=3
+npx tsx benchmarks/run.ts --host=browser --rounds=3
+npx tsx benchmarks/compare.ts BEFORE.json AFTER.json
+```
+
+The final Node comparison improved process `clone`, `fork`, and `spawn` by
+91.0%, 85.8%, and 88.8%; `exec` improved 10.5%. WordPress improved 0.4% for
+its CLI path and 0.5% for first HTTP response. File reads improved 6.0%, while
+writes fell 9.4%. Median syscall latency increased by 1.08 us, or 7.8%.
+
+The full candidate-first/main-second Node pair showed several 5.0–16.1%
+MariaDB query differences, especially in `mariadb-innodb-64`. An immediately
+following three-round control of that exact suite and those exact artifact
+digests put candidate queries between 1.6% faster and 3.0% slower, with
+bootstrap 3.0% faster. An earlier reverse-order control was similarly within
+1.9%. The full-suite values are therefore sensitive to surrounding run state;
+they remain disclosed rather than supporting a universal regression-free
+claim.
+
+The final Chromium comparison improved process `clone`, `fork`, and `spawn`
+by 63.6%, 57.1%, and 38.5%. WordPress boot changed by +0.9%, while first HTTP
+response improved 49.6%. MariaDB bootstrap improved 7.0–8.4% across variants.
+Median syscall latency increased from 14 to 18 us, file writes fell 11.1%,
+and pipe throughput improved 111.1%. Some sub-14 ms SQL operations produced
+large percentages because of timer quantization: the largest candidate
+increase was 4.9 ms, while most select and join medians improved. These
+results support the measured Homebrew and process-start claims, not a claim
+that every microbenchmark improved.
+
+## Remaining work, ranked by measured impact
+
+1. Reduce the remaining 159 process launches, 55 execs, and roughly 29,000
+ syscalls in a warm text query through general process and channel work.
+ Preserve the dedicated kernel Worker, wakeup draining, POSIX semantics, and
+ host parity. ABI batching work is the likely owner if this requires an ABI
+ change.
+2. Investigate Chromium's remaining 0.39 s warm text-query gap and 9.96 s
+ `brew config` gap relative to Node. The same output and process counts point
+ to host scheduling or compilation behavior, not a different Homebrew path.
+3. Bound V8-owned compiled-code memory, whose size V8 does not expose. The
+ complete Chromium query suite and focused 20-launch control are stable
+ without Realm reuse, but only comparison bytes have an explicit 64 MiB cap.
+4. Continue general VFS lookup optimization only where exact symlink,
+ mutation, and `ENOENT` behavior can be proved. The accepted HostFS fast
+ path is one such case; speculative negative caches are not.
+5. Revisit Ruby parsing after the syscall/process costs. The measured parser
+ opportunity is about 0.6 s; the Prism control currently traps on a Psych
+ path and is not a valid product candidate.
diff --git a/docs/package-management.md b/docs/package-management.md
index f1ccfed401..668c2f12cb 100644
--- a/docs/package-management.md
+++ b/docs/package-management.md
@@ -686,14 +686,16 @@ remain unfetched until a path owned by that dependency is used.
The guest `brew` implementation is distributed as the
`homebrew-bootstrap` support-data Formula bottle. Its tap-native recipe
-declares two `libexec` outputs: `homebrew-bootstrap.zip`, a deterministic
+declares three `libexec` outputs: `homebrew-bootstrap.zip`, a deterministic
archive of one exact upstream Homebrew commit plus Kandelo's reviewed
-guest-platform patch, and `homebrew-brew.env`, the architecture tag and system
-environment policy consumed with that exact tree. Consumers extract both from
-the same immutable public bottle; they must not reconstruct the environment
-file or combine it with a ZIP from another build. Neither output is Wasm, so
-the Formula uses the support-data bottle test contract rather than claiming
-Node or browser execution evidence.
+guest-platform patch; `homebrew-brew.env`, the architecture tag and system
+environment policy consumed with that exact tree; and
+`homebrew-portable-ruby.zip`, the source-selected Ruby runtime in Homebrew's
+ordinary versioned vendor layout. Consumers extract all three from the same
+immutable public bottle; they must not reconstruct the environment file or
+combine outputs from different builds. These support-data outputs use the
+support-data bottle test contract rather than making an execution claim about
+the ZIP or environment members themselves.
The generic support-data extractor verifies the exact checkout, catalog and
Formula sidecar, tap recipe lock, link manifest, keg, bottle digest and size,
@@ -704,23 +706,30 @@ checkout commit, aggregate metadata publication commit, and bottle
Formula SHA-256 and Homebrew's `.brew` receipt SHA-256 are separate too,
because the receipt canonically omits the finalized bottle block.
-The bootstrap archive is not a bundled Homebrew runtime. It contains neither
-Ruby nor Git, curl, extraction tools, or their data/dependencies. The base
-shell therefore registers `/usr/bin/brew` as a lazy activation reference
-without claiming the bootstrap source can execute by itself.
+The bootstrap source archive is not a bundled Homebrew runtime. It contains
+neither Ruby nor Git, curl, extraction tools, or their data/dependencies.
+Portable Ruby remains a separate, digest-bound output. Its exact version comes
+from the source archive's
+`Library/Homebrew/vendor/portable-ruby-version`; the image derives both its
+mount and executable paths from the authenticated bootstrap descriptor rather
+than assuming a guest prefix. The output exposes the standard
+`Library/Homebrew/vendor/portable-ruby/` tree and `current` symlink,
+so Homebrew follows its normal portable-Ruby and Bootsnap startup path.
+
+The base shell therefore registers `/usr/bin/brew` as a lazy activation
+reference without claiming the bootstrap source can execute by itself.
`homebrew/main-shell-homebrew-runtime-support.json` owns the separate atomic
-runtime-support closure. Its seven reviewed roots resolve through the exact
-closed-selection metadata that the shell consumes. Dependencies already in the
-complete shell remain shared; additional dependencies become part of the same
-atomic lazy group. This matters when a Formula changes its real dependency
-graph—for example, Ruby now requires `libyaml`. The selection-aware release
-finalizer derives the new order and base-relative difference, requires an
-admitted public ABI-42 bottle for every member, and seals the selection and
-artifact locks together. The base keeps the active layer deferred; an opt-in
-demo may materialize the same layer. A guest lifecycle is valid only when
-every declared tree has an exact admitted ABI/digest/size identity, all
-support bytes come from that declaration, and the independent-tap Formula is
-installed live rather than smuggled into the image.
+runtime-support closure. Portable Ruby and six reviewed Formula roots resolve
+through the exact closed-selection metadata that the shell consumes.
+Dependencies already in the complete shell remain shared; additional Formula
+dependencies become part of the same atomic lazy group. The selection-aware
+release finalizer derives the new order and base-relative difference, requires
+an admitted public ABI-42 bottle for every Formula member, and seals the
+selection and artifact locks together. The base keeps the active layer
+deferred; an opt-in demo may materialize the same layer. A guest lifecycle is
+valid only when every declared tree has an exact admitted ABI/digest/size
+identity, all support bytes come from that declaration, and the
+independent-tap Formula is installed live rather than smuggled into the image.
`Kandelo/recipes/homebrew-bootstrap/source-lock.json` in the tap is the
Formula's reviewed source/output identity. It binds the prepared source inputs
diff --git a/homebrew/main-shell-homebrew-runtime-support.json b/homebrew/main-shell-homebrew-runtime-support.json
index 97f46dc85a..d1b8f0a907 100644
--- a/homebrew/main-shell-homebrew-runtime-support.json
+++ b/homebrew/main-shell-homebrew-runtime-support.json
@@ -57,7 +57,8 @@
"name": "homebrew-bootstrap",
"outputs": [
"homebrew-bootstrap.zip",
- "homebrew-brew.env"
+ "homebrew-brew.env",
+ "homebrew-portable-ruby.zip"
],
"required_kernel_abi": 42
},
@@ -65,10 +66,6 @@
"demo_variant": "may-materialize"
},
"formula_roots": [
- {
- "package": "kandelo-dev/tap-core/ruby",
- "reason": "Homebrew executes its Ruby command implementation after the Bash launcher."
- },
{
"package": "kandelo-dev/tap-core/git",
"reason": "Stock brew tap and exact-revision lifecycle operations use Git."
@@ -95,8 +92,6 @@
}
],
"formula_order": [
- "kandelo-dev/tap-core/zlib",
- "kandelo-dev/tap-core/ruby",
"kandelo-dev/tap-core/coreutils",
"kandelo-dev/tap-core/dash",
"kandelo-dev/tap-core/ed",
@@ -106,6 +101,7 @@
"kandelo-dev/tap-core/ncurses",
"kandelo-dev/tap-core/less",
"kandelo-dev/tap-core/openssl",
+ "kandelo-dev/tap-core/zlib",
"kandelo-dev/tap-core/libcurl",
"kandelo-dev/tap-core/sed",
"kandelo-dev/tap-core/vim",
@@ -117,15 +113,8 @@
"kandelo-dev/tap-core/tar",
"kandelo-dev/tap-core/posix-utils-lite"
],
- "additional_formula_order": [
- "kandelo-dev/tap-core/ruby"
- ],
+ "additional_formula_order": [],
"required_commands": [
- {
- "path": "/usr/bin/ruby",
- "package": "kandelo-dev/tap-core/ruby",
- "reason": "Homebrew's Bash launcher transfers control to Ruby."
- },
{
"path": "/usr/bin/git",
"package": "kandelo-dev/tap-core/git",
@@ -163,14 +152,13 @@
"metadata_sha256": "34f1cb2454ff6d9c134195302a5c5fcac85b9502f2522d3e584bf55d539c9a7d",
"metadata_tap_commit": "b5ffda55d9b0e27efdfdec30ebb38d48a21518c4",
"kandelo_commit": "c647adda31d0918de944135543fb94039135cef1",
- "runtime_bottle_provenance_sha256": "b9070afcb5ddcdc112c1b994c16f8f46251d78dff3877e01adf30b226e4c31d2",
+ "runtime_bottle_provenance_sha256": "a1269194b223c47c97ccc0504369b889357f77dc0675bb7245d14c587de082dd",
"kandelo_abi": 42,
"release_tag": "bottles-abi-v42",
"required_arch": "wasm32"
},
"reusable_public_abi42": [
"kandelo-dev/tap-core/zlib",
- "kandelo-dev/tap-core/ruby",
"kandelo-dev/tap-core/coreutils",
"kandelo-dev/tap-core/dash",
"kandelo-dev/tap-core/ed",
diff --git a/homebrew/main-shell-lazy-artifact-lock.json b/homebrew/main-shell-lazy-artifact-lock.json
index 0933dd6671..e221beda81 100644
--- a/homebrew/main-shell-lazy-artifact-lock.json
+++ b/homebrew/main-shell-lazy-artifact-lock.json
@@ -9,8 +9,8 @@
"demo_config_sha256": "6a09a53f0b169400948aa4f5c9c7a4b904ed7007ad0912d9cd73a66f7b57e455",
"materialization_policy_sha256": "fb170c25f71e6e7fdd3470901b3ab3a42e7765648d55f62fad38230e30461fe0",
"migration_lock_sha256": "92b6c3946e40e9384de0ed98c13b6f9ec595e487a5112cc8a450bc2ac3ea524e",
- "runtime_support_sha256": "4ee373429d0f26e459cd9fe5ea16901d1769f9947f89cffeaee262b94e403616",
- "selection_lock_sha256": "7811caefed4ca503b49fb2bd7e338d6e7c21e3dd3ecdfc4783ea9d24514f5b73",
+ "runtime_support_sha256": "9d4f185b58f0c8e99f58c3785be095921fb75ee5016c733f9be6a5b98e756c78",
+ "selection_lock_sha256": "13bb84866474be01dcf2cb942060e16df5651fdb0db9cdc05414c4e16bb60e84",
"shell_config_sha256": "bc3c4027b5f83fd74178364bf0b073b546eca5a098bf8bf47bc38a555b4cfe0c"
},
"image": null
diff --git a/homebrew/main-shell-selection-lock.json b/homebrew/main-shell-selection-lock.json
index 6152bc5361..c850d65781 100644
--- a/homebrew/main-shell-selection-lock.json
+++ b/homebrew/main-shell-selection-lock.json
@@ -15,7 +15,7 @@
},
"runtime_support": {
"path": "homebrew/main-shell-homebrew-runtime-support.json",
- "sha256": "4ee373429d0f26e459cd9fe5ea16901d1769f9947f89cffeaee262b94e403616"
+ "sha256": "9d4f185b58f0c8e99f58c3785be095921fb75ee5016c733f9be6a5b98e756c78"
}
},
"kind": "kandelo-homebrew-main-shell-closed-selection-lock",
diff --git a/homebrew/test/homebrew_guest_lifecycle_browser.ts b/homebrew/test/homebrew_guest_lifecycle_browser.ts
index aa4ffe1f68..272e350759 100644
--- a/homebrew/test/homebrew_guest_lifecycle_browser.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_browser.ts
@@ -105,6 +105,8 @@ export async function runHomebrewGuestLifecycleInBrowser(options: {
bootstrapSpecBytes: loaded.bootstrapSpecBytes,
bootstrapArchiveBytes: loaded.bootstrapArchiveBytes,
bootstrapArchiveSha256: fixture.bootstrap.archive.sha256,
+ portableRubyArchiveBytes: loaded.portableRubyArchiveBytes,
+ portableRubyArchiveSha256: fixture.bootstrap.portableRuby.sha256,
bootstrapEnvironmentBytes: loaded.bootstrapEnvironmentBytes,
coreRevision: fixture.revisions.coreRevision,
transportMode: fixture.transportMode,
@@ -115,6 +117,8 @@ export async function runHomebrewGuestLifecycleInBrowser(options: {
...(publicTransport
? {
expectedBootstrapTransportUrl: fixture.bootstrap.archive.url,
+ expectedPortableRubyTransportUrl:
+ fixture.bootstrap.portableRuby.url,
}
: {
closedBottleAssets: loaded.closedBottleAssets!,
diff --git a/homebrew/test/homebrew_guest_lifecycle_browser_fixture.test.ts b/homebrew/test/homebrew_guest_lifecycle_browser_fixture.test.ts
index 4a098d192b..3bde167c96 100644
--- a/homebrew/test/homebrew_guest_lifecycle_browser_fixture.test.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_browser_fixture.test.ts
@@ -124,6 +124,10 @@ test("loads every exact fixture byte and binds payloads to the mirror plan", asy
assert.deepEqual(loaded.imageBytes, fixture.imageBytes);
assert.deepEqual(loaded.bootstrapSpecBytes, fixture.specBytes);
assert.deepEqual(loaded.bootstrapArchiveBytes, fixture.archiveBytes);
+ assert.deepEqual(
+ loaded.portableRubyArchiveBytes,
+ fixture.portableRubyBytes,
+ );
assert.deepEqual(loaded.bootstrapEnvironmentBytes, fixture.environmentBytes);
assert.deepEqual(loaded.bottleMirrorPlanBytes, fixture.planBytes);
assert.deepEqual(loaded.closedBottleAssets, [{
@@ -379,7 +383,7 @@ test("preserves caller cancellation during public plan identity validation", asy
data: BufferSource,
): Promise => {
digestCalls += 1;
- if (digestCalls === 6) {
+ if (digestCalls === 7) {
markIdentityStarted();
await identityGate;
}
@@ -463,6 +467,7 @@ function createFixture() {
const imageBytes = new Uint8Array([1, 2]);
const specBytes = new Uint8Array([3]);
const archiveBytes = new Uint8Array([4]);
+ const portableRubyBytes = new Uint8Array([9, 10]);
const environmentBytes = new Uint8Array([5]);
const payloadBytes = new Uint8Array([6, 7, 8]);
const repository = "example/project";
@@ -497,6 +502,7 @@ function createFixture() {
image: "https://example.test/main-shell.vfs.zst",
spec: "https://example.test/main-shell-brew-package-tree.json",
archive: "https://example.test/homebrew-bootstrap.zip",
+ portableRuby: "https://example.test/homebrew-portable-ruby.zip",
environment: "https://example.test/homebrew-brew.env",
plan: `${releaseRoot}/${HOMEBREW_BOTTLE_MIRROR_PLAN_ASSET}`,
};
@@ -508,6 +514,7 @@ function createFixture() {
bootstrap: {
spec: exact(urls.spec, specBytes),
archive: exact(urls.archive, archiveBytes),
+ portableRuby: exact(urls.portableRuby, portableRubyBytes),
environment: exact(urls.environment, environmentBytes),
},
bottleMirror: {
@@ -527,6 +534,7 @@ function createFixture() {
[urls.image, imageBytes],
[urls.spec, specBytes],
[urls.archive, archiveBytes],
+ [urls.portableRuby, portableRubyBytes],
[urls.environment, environmentBytes],
[urls.plan, planBytes],
[plan.assets[0]!.url, payloadBytes],
@@ -537,6 +545,7 @@ function createFixture() {
imageBytes,
specBytes,
archiveBytes,
+ portableRubyBytes,
environmentBytes,
payloadBytes,
plan,
diff --git a/homebrew/test/homebrew_guest_lifecycle_browser_fixture.ts b/homebrew/test/homebrew_guest_lifecycle_browser_fixture.ts
index 70a6954605..9b645c006e 100644
--- a/homebrew/test/homebrew_guest_lifecycle_browser_fixture.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_browser_fixture.ts
@@ -38,6 +38,7 @@ export interface HomebrewGuestLifecycleBrowserFixture {
bootstrap: {
spec: HomebrewGuestLifecycleExactAsset;
archive: HomebrewGuestLifecycleExactAsset;
+ portableRuby: HomebrewGuestLifecycleExactAsset;
environment: HomebrewGuestLifecycleExactAsset;
};
bottleMirror: {
@@ -53,6 +54,7 @@ export interface LoadedHomebrewGuestLifecycleBrowserFixture {
imageBytes: Uint8Array;
bootstrapSpecBytes: Uint8Array;
bootstrapArchiveBytes: Uint8Array;
+ portableRubyArchiveBytes: Uint8Array;
bootstrapEnvironmentBytes: Uint8Array;
bottleMirrorPlanBytes: Uint8Array;
closedBottleAssets?: readonly ClosedLazyAsset[];
@@ -127,13 +129,18 @@ const TOP_LEVEL_KEYS = [
"revisions",
"timeoutMs",
] as const;
-const BOOTSTRAP_KEYS = ["spec", "archive", "environment"] as const;
+const BOOTSTRAP_KEYS = [
+ "spec",
+ "archive",
+ "portableRuby",
+ "environment",
+] as const;
const MIRROR_KEYS = ["plan", "payloads"] as const;
const REVISION_KEYS = ["coreRevision", "canaryRevision"] as const;
const ASSET_KEYS = ["url", "sha256", "bytes"] as const;
const PAYLOAD_KEYS = ["asset", "url", "sha256", "bytes"] as const;
const SHA256_RE = /^[0-9a-f]{64}$/;
-const FIXED_EXACT_ASSET_COUNT = 5;
+const FIXED_EXACT_ASSET_COUNT = 6;
/**
* Reject ambient or partially specified live inputs before any browser fetch.
@@ -220,6 +227,10 @@ export function projectHomebrewGuestLifecycleBrowserFixture(
value.bootstrap.archive,
"bootstrap archive",
),
+ portableRuby: projectExactAsset(
+ value.bootstrap.portableRuby,
+ "portable Ruby archive",
+ ),
environment: projectExactAsset(
value.bootstrap.environment,
"bootstrap environment",
@@ -258,6 +269,7 @@ async function loadHomebrewGuestLifecycleBrowserFixtureImpl(
fixture.image,
fixture.bootstrap.spec,
fixture.bootstrap.archive,
+ fixture.bootstrap.portableRuby,
fixture.bootstrap.environment,
fixture.bottleMirror.plan,
...payloads,
@@ -287,12 +299,14 @@ async function loadHomebrewGuestLifecycleBrowserFixtureImpl(
image,
bootstrapSpec,
bootstrapArchive,
+ portableRubyArchive,
bootstrapEnvironment,
bottleMirrorPlan,
] = loadedFixedAssets;
const imageBytes = image!.bytes;
const bootstrapSpecBytes = bootstrapSpec!.bytes;
const bootstrapArchiveBytes = bootstrapArchive!.bytes;
+ const portableRubyArchiveBytes = portableRubyArchive!.bytes;
const bootstrapEnvironmentBytes = bootstrapEnvironment!.bytes;
const bottleMirrorPlanBytes = bottleMirrorPlan!.bytes;
const plan = decodeHomebrewBottleMirrorPlan(
@@ -314,6 +328,7 @@ async function loadHomebrewGuestLifecycleBrowserFixtureImpl(
imageBytes,
bootstrapSpecBytes,
bootstrapArchiveBytes,
+ portableRubyArchiveBytes,
bootstrapEnvironmentBytes,
bottleMirrorPlanBytes,
};
@@ -381,6 +396,7 @@ async function loadHomebrewGuestLifecycleBrowserFixtureImpl(
imageBytes,
bootstrapSpecBytes,
bootstrapArchiveBytes,
+ portableRubyArchiveBytes,
bootstrapEnvironmentBytes,
bottleMirrorPlanBytes,
closedBottleAssets,
diff --git a/homebrew/test/homebrew_guest_lifecycle_node.ts b/homebrew/test/homebrew_guest_lifecycle_node.ts
index 68abff29c5..b356a30979 100644
--- a/homebrew/test/homebrew_guest_lifecycle_node.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_node.ts
@@ -8,6 +8,8 @@ import { pathToFileURL } from "node:url";
import { NodeKernelHost } from "../../host/src/node-kernel-host";
import type { LazyDownloadEvent } from "../../host/src/vfs/memory-fs";
import { assertHomebrewBottleMirrorPlan } from "../../host/src/homebrew-vfs-composer";
+import { deriveHomebrewPortableRubyTree } from
+ "../../host/src/homebrew-portable-ruby";
import {
assertPackageDeferredZipTreeState,
derivePackageDeferredZipTree,
@@ -51,6 +53,7 @@ interface Options extends HomebrewGuestLifecycleRevisions {
imagePath: string;
bootstrapSpecPath: string;
bootstrapArchivePath: string;
+ portableRubyArchivePath: string;
bootstrapEnvironmentPath: string;
transportMode: "closed" | "public";
bottleMirrorPlanPath?: string;
@@ -166,6 +169,10 @@ async function loadRootfsRuntimeInputs(
options.bootstrapArchivePath,
"Homebrew bootstrap archive",
);
+ const portableRubyArchiveBytes = readRegularFile(
+ options.portableRubyArchivePath,
+ "Homebrew portable Ruby archive",
+ );
const bootstrapEnvironmentBytes = readRegularFile(
options.bootstrapEnvironmentPath,
"Homebrew bootstrap environment",
@@ -181,23 +188,39 @@ async function loadRootfsRuntimeInputs(
parseJson(bootstrapSpecBytes, options.bootstrapSpecPath),
bootstrapArchiveBytes,
);
+ const portableRubyTree = deriveHomebrewPortableRubyTree(
+ bootstrapTree,
+ bootstrapArchiveBytes,
+ portableRubyArchiveBytes,
+ );
const bootstrapArchiveSha256 = createHash("sha256")
.update(bootstrapArchiveBytes)
.digest("hex");
+ const portableRubyArchiveSha256 = createHash("sha256")
+ .update(portableRubyArchiveBytes)
+ .digest("hex");
const lazyUrlBase = options.transportMode === "closed"
? "https://closed.kandelo.invalid/homebrew-guest-lifecycle/"
: pathToFileURL(`${dirname(options.bootstrapArchivePath)}/`).toString();
return await deriveHomebrewGuestLifecycleRuntimeInputs({
imageBytes,
- validateImageFileSystem: (imageFileSystem) =>
+ validateImageFileSystem: (imageFileSystem) => {
assertPackageDeferredZipTreeState(
imageFileSystem,
bootstrapTree,
"deferred",
- ),
+ );
+ assertPackageDeferredZipTreeState(
+ imageFileSystem,
+ portableRubyTree,
+ "deferred",
+ );
+ },
bootstrapSpecBytes,
bootstrapArchiveBytes,
bootstrapArchiveSha256,
+ portableRubyArchiveBytes,
+ portableRubyArchiveSha256,
bootstrapEnvironmentBytes,
coreRevision: options.coreRevision,
transportMode: options.transportMode,
@@ -208,6 +231,9 @@ async function loadRootfsRuntimeInputs(
expectedBootstrapTransportUrl: pathToFileURL(
options.bootstrapArchivePath,
).toString(),
+ expectedPortableRubyTransportUrl: pathToFileURL(
+ options.portableRubyArchivePath,
+ ).toString(),
}
: {
loadClosedBottleAssets: (embeddedPlanBytes, pendingBottleTrees) =>
@@ -539,6 +565,7 @@ function parseOptions(args: string[]): Options {
"--image",
"--homebrew-bootstrap-spec",
"--homebrew-bootstrap-archive",
+ "--homebrew-portable-ruby-archive",
"--homebrew-bootstrap-env",
"--transport-mode",
"--bottle-mirror-plan",
@@ -564,6 +591,9 @@ function parseOptions(args: string[]): Options {
const image = values.get("--image");
const bootstrapSpec = values.get("--homebrew-bootstrap-spec");
const bootstrapArchive = values.get("--homebrew-bootstrap-archive");
+ const portableRubyArchive = values.get(
+ "--homebrew-portable-ruby-archive",
+ );
const bootstrapEnvironment = values.get("--homebrew-bootstrap-env");
const transportMode = values.get("--transport-mode");
const bottleMirrorPlan = values.get("--bottle-mirror-plan");
@@ -578,6 +608,7 @@ function parseOptions(args: string[]): Options {
!image ||
!bootstrapSpec ||
!bootstrapArchive ||
+ !portableRubyArchive ||
!bootstrapEnvironment ||
!coreRevision ||
!canaryRevision ||
@@ -604,6 +635,7 @@ function parseOptions(args: string[]): Options {
imagePath: resolve(image),
bootstrapSpecPath: resolve(bootstrapSpec),
bootstrapArchivePath: resolve(bootstrapArchive),
+ portableRubyArchivePath: resolve(portableRubyArchive),
bootstrapEnvironmentPath: resolve(bootstrapEnvironment),
transportMode,
proofMode,
@@ -625,6 +657,7 @@ function usage(): never {
"--image " +
"--homebrew-bootstrap-spec " +
"--homebrew-bootstrap-archive " +
+ "--homebrew-portable-ruby-archive " +
"--homebrew-bootstrap-env " +
"--transport-mode " +
"[--bottle-mirror-plan ] " +
diff --git a/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.test.ts b/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.test.ts
index 2ba8e559df..dc297cf0c7 100644
--- a/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.test.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.test.ts
@@ -13,6 +13,8 @@ import {
} from "../../host/src/homebrew-bottle-mirror-plan";
import { homebrewRuntimeLayerPayloadAsset } from
"../../host/src/homebrew-runtime-layer-limits";
+import { deriveHomebrewPortableRubyTree } from
+ "../../host/src/homebrew-portable-ruby";
import { MemoryFileSystem } from "../../host/src/vfs/memory-fs";
import {
derivePackageDeferredZipTree,
@@ -32,14 +34,21 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
const bootstrapArchive = zipSync({
"bin/": zipEntry(new Uint8Array(), 0o040755),
"bin/brew": zipEntry(encoder.encode("#!/bin/sh\n"), 0o100755),
+ "Library/": zipEntry(new Uint8Array(), 0o040755),
+ "Library/Homebrew/": zipEntry(new Uint8Array(), 0o040755),
+ "Library/Homebrew/vendor/": zipEntry(new Uint8Array(), 0o040755),
+ "Library/Homebrew/vendor/portable-ruby-version": zipEntry(
+ encoder.encode("4.0.5\n"),
+ 0o100644,
+ ),
}, { level: 9 });
const bootstrapSpec = {
schema: 1,
kind: "kandelo-package-deferred-zip-tree",
- id: "shell/homebrew-bootstrap",
+ id: "homebrew-bootstrap/source-tree",
content_role: "source-tree",
package: {
- name: "shell",
+ name: "homebrew-bootstrap",
output: "homebrew-bootstrap.zip",
},
archive: {
@@ -59,6 +68,17 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
bootstrapSpec,
bootstrapArchive,
);
+ const portableRubyArchive = zipSync({
+ "4.0.5/": zipEntry(new Uint8Array(), 0o040755),
+ "4.0.5/bin/": zipEntry(new Uint8Array(), 0o040755),
+ "4.0.5/bin/ruby": zipEntry(encoder.encode("ruby-wasm\n"), 0o100755),
+ current: zipEntry(encoder.encode("4.0.5"), 0o120777),
+ }, { level: 9 });
+ const portableRubyTree = deriveHomebrewPortableRubyTree(
+ bootstrapTree,
+ bootstrapArchive,
+ portableRubyArchive,
+ );
const bottleBytes = new Uint8Array([42]);
const mirror = createMirrorPlan(bottleBytes);
const mirrorBytes = encodeHomebrewBottleMirrorPlan(mirror);
@@ -117,6 +137,7 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
);
writeFile(fs, HOMEBREW_BOTTLE_MIRROR_PLAN_VFS_PATH, mirrorBytes);
registerPackageDeferredZipTree(fs, bootstrapTree);
+ registerPackageDeferredZipTree(fs, portableRubyTree);
fs.registerLazyTree(
{
decoder: "zip-v1",
@@ -151,6 +172,7 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
await fs.sealLazyAtomicGroup("homebrew-runtime-support", [
bootstrapTree.descriptor.id,
"bottle-test",
+ portableRubyTree.descriptor.id,
]);
const imageBytes = await fs.saveImage();
@@ -158,6 +180,8 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
bootstrapSpecBytes: encoder.encode(JSON.stringify(bootstrapSpec)),
bootstrapArchiveBytes: bootstrapArchive,
bootstrapArchiveSha256: sha256(bootstrapArchive),
+ portableRubyArchiveBytes: portableRubyArchive,
+ portableRubyArchiveSha256: sha256(portableRubyArchive),
bootstrapEnvironmentBytes: environmentBytes,
coreRevision,
transportMode: "closed" as const,
@@ -186,15 +210,27 @@ test("binds verified bootstrap bytes and bottle payloads to one exact image", as
"https://closed.kandelo.invalid/lifecycle/homebrew-bootstrap.zip",
);
assert.equal(runtime.bootstrapBytes, bootstrapArchive.byteLength);
- assert.deepEqual(runtime.runtimeSupportTrees, [{
- url: mirror.assets[0]!.url,
- bytes: bottleBytes.byteLength,
- }]);
- assert.equal(runtime.lazyAssets?.length, 2);
+ assert.deepEqual(runtime.runtimeSupportTrees, [
+ {
+ url: mirror.assets[0]!.url,
+ bytes: bottleBytes.byteLength,
+ },
+ {
+ url:
+ "https://closed.kandelo.invalid/lifecycle/" +
+ "homebrew-portable-ruby.zip",
+ bytes: portableRubyArchive.byteLength,
+ },
+ ]);
+ assert.equal(runtime.lazyAssets?.length, 3);
assert.equal(
runtime.lazyAssets?.[1]?.sha256,
bootstrapTree.content.sha256,
);
+ assert.equal(
+ runtime.lazyAssets?.[2]?.sha256,
+ portableRubyTree.content.sha256,
+ );
assert.deepEqual(validatedMirror, mirror);
for (const [forgery, expected] of [
diff --git a/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.ts b/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.ts
index e868cee17b..bd00631b09 100644
--- a/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.ts
+++ b/homebrew/test/homebrew_guest_lifecycle_runtime_inputs.ts
@@ -20,6 +20,13 @@ import {
assertHomebrewGuestLifecycleCatalog,
resolveHomebrewGuestLifecycleShell,
} from "./homebrew_guest_lifecycle_runtime_contract";
+import {
+ HOMEBREW_PORTABLE_RUBY_OUTPUT,
+ HOMEBREW_PORTABLE_RUBY_TREE_ID,
+ homebrewPortableRubyExecutable,
+ homebrewPortableRubyMountPrefix,
+ readHomebrewPortableRubyVersion,
+} from "../../host/src/homebrew-portable-ruby-contract";
export type HomebrewGuestLifecycleTransportMode = "closed" | "public";
@@ -36,7 +43,7 @@ export interface HomebrewGuestLifecycleRuntimeInputs {
lazyAssets?: readonly ClosedLazyAsset[];
bootstrapTransportUrl: string;
bootstrapBytes: number;
- /** Bottle trees committed by the same first-use transaction as bootstrap. */
+ /** Trees committed by the same first-use transaction as Brew's source. */
runtimeSupportTrees?: readonly { url: string; bytes: number }[];
}
@@ -52,11 +59,14 @@ export interface DeriveHomebrewGuestLifecycleRuntimeInputs {
bootstrapSpecBytes: Uint8Array;
bootstrapArchiveBytes: Uint8Array;
bootstrapArchiveSha256: string;
+ portableRubyArchiveBytes: Uint8Array;
+ portableRubyArchiveSha256: string;
bootstrapEnvironmentBytes: Uint8Array;
coreRevision: string;
transportMode: HomebrewGuestLifecycleTransportMode;
lazyUrlBase: string;
expectedBootstrapTransportUrl?: string;
+ expectedPortableRubyTransportUrl?: string;
expectedEmbeddedBottlePlanBytes?: Uint8Array;
validateEmbeddedBottlePlan?: (plan: HomebrewBottleMirrorPlan) => void;
closedBottleAssets?: readonly ClosedLazyAsset[];
@@ -89,9 +99,11 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
);
if (
!SHA256_RE.test(input.bootstrapArchiveSha256) ||
- input.bootstrapArchiveBytes.byteLength === 0
+ input.bootstrapArchiveBytes.byteLength === 0 ||
+ !SHA256_RE.test(input.portableRubyArchiveSha256) ||
+ input.portableRubyArchiveBytes.byteLength === 0
) {
- throw new Error("Homebrew bootstrap archive identity is invalid");
+ throw new Error("Homebrew runtime archive identity is invalid");
}
const fs = MemoryFileSystem.fromImage(input.imageBytes);
// WHY: callbacks and closed-asset binding act on exported lazy metadata;
@@ -112,12 +124,14 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
const pendingTrees = classifyPendingTrees(fs.exportLazyArchiveEntries());
if (
pendingTrees.bootstrap.length !== 1 ||
+ pendingTrees.portableRuby.length !== 1 ||
pendingTrees.unclassified.length !== 0
) {
throw new Error(
`lifecycle image has ${pendingTrees.bootstrap.length} pending Homebrew ` +
- `source trees and ${pendingTrees.unclassified.length} unclassified ` +
- `package trees`,
+ `source trees, ${pendingTrees.portableRuby.length} portable Ruby ` +
+ `trees, and ${pendingTrees.unclassified.length} unclassified package ` +
+ `trees`,
);
}
assertBootstrapTreeBinding(
@@ -127,6 +141,17 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
input.bootstrapArchiveSha256,
input.bootstrapArchiveBytes.byteLength,
);
+ const portableRubyVersion = readHomebrewPortableRubyVersion(
+ input.bootstrapArchiveBytes,
+ );
+ assertPortableRubyTreeBinding(
+ fs,
+ pendingTrees.portableRuby[0]!,
+ bootstrapSpec,
+ portableRubyVersion,
+ input.portableRubyArchiveSha256,
+ input.portableRubyArchiveBytes.byteLength,
+ );
const embeddedPlanBytes = readVfsFile(
fs,
@@ -157,19 +182,23 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
);
const bootstrapAtomicGroup =
pendingTrees.bootstrap[0]!.activation?.atomicGroup;
- const runtimeSupportTrees = bootstrapAtomicGroup === undefined
+ const runtimeSupportBottleTrees = bootstrapAtomicGroup === undefined
? []
: pendingTrees.bottles.filter(
(tree) =>
tree.activation?.atomicGroup?.id === bootstrapAtomicGroup.id,
);
+ const portableRubyTree = pendingTrees.portableRuby[0]!;
+ const runtimeSupportTrees = [
+ ...runtimeSupportBottleTrees,
+ portableRubyTree,
+ ];
if (
- bootstrapAtomicGroup !== undefined &&
+ bootstrapAtomicGroup === undefined ||
(
bootstrapAtomicGroup.descriptorSha256 === undefined ||
bootstrapAtomicGroup.expectedCount !== runtimeSupportTrees.length + 1 ||
bootstrapAtomicGroup.cohortSha256 === undefined ||
- runtimeSupportTrees.length === 0 ||
runtimeSupportTrees.some(
(tree) =>
tree.activation?.mode !== "first-use" ||
@@ -191,6 +220,10 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
bootstrapSpec.archive.url,
input.lazyUrlBase,
).toString();
+ const portableRubyTransportUrl = new URL(
+ HOMEBREW_PORTABLE_RUBY_OUTPUT,
+ input.lazyUrlBase,
+ ).toString();
if (
input.expectedBootstrapTransportUrl !== undefined &&
bootstrapTransportUrl !== input.expectedBootstrapTransportUrl
@@ -200,6 +233,16 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
`expected ${input.expectedBootstrapTransportUrl}`,
);
}
+ if (
+ input.expectedPortableRubyTransportUrl !== undefined &&
+ portableRubyTransportUrl !== input.expectedPortableRubyTransportUrl
+ ) {
+ throw new Error(
+ `Homebrew portable Ruby transport resolves to ` +
+ `${portableRubyTransportUrl}, expected ` +
+ input.expectedPortableRubyTransportUrl,
+ );
+ }
const lazyAssets = bindClosedLifecycleAssets(
input,
@@ -209,6 +252,9 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
bootstrapTransportUrl,
input.bootstrapArchiveSha256,
input.bootstrapArchiveBytes.byteLength,
+ portableRubyTransportUrl,
+ input.portableRubyArchiveSha256,
+ input.portableRubyArchiveBytes.byteLength,
);
input.validateImageFileSystem?.(fs);
@@ -223,10 +269,16 @@ export async function deriveHomebrewGuestLifecycleRuntimeInputs(
...(lazyAssets === undefined ? {} : { lazyAssets }),
bootstrapTransportUrl,
bootstrapBytes: input.bootstrapArchiveBytes.byteLength,
- runtimeSupportTrees: runtimeSupportTrees.map((tree) => ({
- url: tree.content!.transports[0]!,
- bytes: tree.content!.bytes,
- })),
+ runtimeSupportTrees: [
+ ...runtimeSupportBottleTrees.map((tree) => ({
+ url: tree.content!.transports[0]!,
+ bytes: tree.content!.bytes,
+ })),
+ {
+ url: portableRubyTransportUrl,
+ bytes: portableRubyTree.content!.bytes,
+ },
+ ],
};
}
@@ -337,6 +389,120 @@ function assertBootstrapTreeBinding(
}
}
+function assertPortableRubyTreeBinding(
+ fs: MemoryFileSystem,
+ tree: SerializedLazyArchiveEntry,
+ sourceSpec: PackageDeferredZipTreeSpec,
+ version: string,
+ archiveSha256: string,
+ archiveBytes: number,
+): void {
+ const content = tree.content;
+ const inventory = tree.inventory;
+ const inventoryBytes = inventory?.reduce(
+ (total, entry) => total + entry.size,
+ 0,
+ );
+ const mountPrefix = homebrewPortableRubyMountPrefix(
+ sourceSpec.mount_prefix,
+ );
+ const rubyPath = homebrewPortableRubyExecutable(
+ sourceSpec.mount_prefix,
+ version,
+ );
+ const currentPath = `${mountPrefix}/current`;
+ const atomicGroup = tree.activation?.atomicGroup;
+ const sourceAtomicGroup = sourceSpec.activation.atomicGroup;
+ const current = inventory?.find((entry) => entry.vfsPath === currentPath);
+ const ruby = inventory?.find((entry) => entry.vfsPath === rubyPath);
+ const allowedTopLevel = new Set([version, "current"]);
+ if (
+ sourceSpec.package.name !== "homebrew-bootstrap" ||
+ sourceSpec.package.output !== "homebrew-bootstrap.zip" ||
+ sourceAtomicGroup === undefined ||
+ tree.kind !== "kandelo-deferred-tree-v3" ||
+ tree.materialized ||
+ tree.mountPrefix !== mountPrefix ||
+ tree.url !== HOMEBREW_PORTABLE_RUBY_OUTPUT ||
+ content === undefined ||
+ content.decoder !== "zip-v1" ||
+ content.mediaType !== "application/zip" ||
+ content.sha256 !== archiveSha256 ||
+ content.bytes !== archiveBytes ||
+ content.expandedBytes !== inventoryBytes ||
+ content.sourceEntryCount !== inventory?.length ||
+ content.transports.length !== 1 ||
+ content.transports[0] !== HOMEBREW_PORTABLE_RUBY_OUTPUT ||
+ content.modePolicy !== "portable-posix-v1" ||
+ content.source !== undefined ||
+ inventory === undefined ||
+ inventory.length === 0 ||
+ tree.activation?.mode !== "first-use" ||
+ JSON.stringify(tree.activation.capabilities) !==
+ JSON.stringify(["homebrew:runtime"]) ||
+ JSON.stringify(tree.activation.roots) !== JSON.stringify([rubyPath]) ||
+ atomicGroup?.id !== sourceAtomicGroup.id ||
+ atomicGroup.member !== HOMEBREW_PORTABLE_RUBY_TREE_ID ||
+ atomicGroup.descriptorSha256 === undefined ||
+ atomicGroup.expectedCount === undefined ||
+ atomicGroup.cohortSha256 === undefined ||
+ current?.type !== "symlink" ||
+ current.target !== version ||
+ ruby?.type !== "file" ||
+ ruby.size <= 0 ||
+ (ruby.mode & 0o111) === 0 ||
+ inventory.some((entry) => {
+ if (!entry.vfsPath.startsWith(`${mountPrefix}/`)) return true;
+ const relative = entry.vfsPath.slice(mountPrefix.length + 1);
+ return !allowedTopLevel.has(relative.split("/", 1)[0]!);
+ })
+ ) {
+ throw new Error(
+ "Homebrew portable Ruby deferred tree changed descriptor: " +
+ JSON.stringify({
+ kind: tree.kind,
+ materialized: tree.materialized,
+ mountPrefix: tree.mountPrefix,
+ url: tree.url,
+ content,
+ inventoryBytes,
+ inventoryLength: inventory?.length,
+ activation: tree.activation,
+ }),
+ );
+ }
+
+ for (const entry of inventory) {
+ if (entry.type === "hardlink") {
+ throw new Error(
+ "Homebrew portable Ruby ZIP tree contains a hardlink inventory entry",
+ );
+ }
+ const stat = fs.lstat(entry.vfsPath);
+ const expectedType = entry.type === "directory"
+ ? S_IFDIR
+ : entry.type === "symlink"
+ ? S_IFLNK
+ : S_IFREG;
+ if (
+ (stat.mode & S_IFMT) !== expectedType ||
+ (stat.mode & 0o7777) !== entry.mode ||
+ stat.uid !== sourceSpec.owner.uid ||
+ stat.gid !== sourceSpec.owner.gid ||
+ (entry.type !== "directory" && stat.size !== entry.size) ||
+ (entry.type === "file" && !fs.isPathDeferred(entry.vfsPath)) ||
+ (
+ entry.type === "symlink" &&
+ fs.readlink(entry.vfsPath) !== entry.target
+ )
+ ) {
+ throw new Error(
+ `Homebrew portable Ruby deferred tree changed ${entry.vfsPath}`,
+ );
+ }
+ }
+}
+
function bindClosedLifecycleAssets(
input: DeriveHomebrewGuestLifecycleRuntimeInputs,
plan: HomebrewBottleMirrorPlan,
@@ -345,6 +511,9 @@ function bindClosedLifecycleAssets(
bootstrapTransportUrl: string,
bootstrapSha256: string,
bootstrapBytes: number,
+ portableRubyTransportUrl: string,
+ portableRubySha256: string,
+ portableRubyBytes: number,
): readonly ClosedLazyAsset[] | undefined {
if (input.transportMode === "public") {
if (
@@ -377,6 +546,12 @@ function bindClosedLifecycleAssets(
size: bootstrapBytes,
bytes: input.bootstrapArchiveBytes,
},
+ {
+ url: portableRubyTransportUrl,
+ sha256: portableRubySha256,
+ size: portableRubyBytes,
+ bytes: input.portableRubyArchiveBytes,
+ },
];
}
@@ -412,6 +587,7 @@ function assertClosedBottleAssets(
function classifyPendingTrees(entries: readonly SerializedLazyArchiveEntry[]): {
bottles: SerializedLazyArchiveEntry[];
bootstrap: SerializedLazyArchiveEntry[];
+ portableRuby: SerializedLazyArchiveEntry[];
unclassified: SerializedLazyArchiveEntry[];
} {
const pending = entries.filter((tree) => tree.content !== undefined);
@@ -420,12 +596,15 @@ function classifyPendingTrees(entries: readonly SerializedLazyArchiveEntry[]): {
const bottleCapabilities = capabilities.filter((capability) =>
capability.startsWith("homebrew-bottle:")
);
+ const ownershipCapabilities = [
+ bottleCapabilities.length > 0,
+ capabilities.includes("homebrew:bootstrap"),
+ capabilities.includes("homebrew:runtime") &&
+ !capabilities.includes("homebrew:bootstrap"),
+ ].filter(Boolean).length;
if (
bottleCapabilities.length > 1 ||
- (
- bottleCapabilities.length === 1 &&
- capabilities.includes("homebrew:bootstrap")
- )
+ ownershipCapabilities > 1
) {
throw new Error(
`pending tree ${tree.mountPrefix} has ambiguous Homebrew ownership`,
@@ -440,10 +619,20 @@ function classifyPendingTrees(entries: readonly SerializedLazyArchiveEntry[]): {
const bootstrap = pending.filter((tree) =>
tree.activation?.capabilities.includes("homebrew:bootstrap")
);
+ const portableRuby = pending.filter((tree) =>
+ tree.activation?.capabilities.includes("homebrew:runtime") &&
+ !tree.activation.capabilities.includes("homebrew:bootstrap") &&
+ !tree.activation.capabilities.some((capability) =>
+ capability.startsWith("homebrew-bottle:")
+ )
+ );
const unclassified = pending.filter(
- (tree) => !bottles.includes(tree) && !bootstrap.includes(tree),
+ (tree) =>
+ !bottles.includes(tree) &&
+ !bootstrap.includes(tree) &&
+ !portableRuby.includes(tree),
);
- return { bottles, bootstrap, unclassified };
+ return { bottles, bootstrap, portableRuby, unclassified };
}
function readVfsFile(fs: MemoryFileSystem, path: string): Uint8Array {
diff --git a/homebrew/test/run_homebrew_guest_shipping_scope.sh b/homebrew/test/run_homebrew_guest_shipping_scope.sh
index bdc45ddd59..53c0ae7d4a 100755
--- a/homebrew/test/run_homebrew_guest_shipping_scope.sh
+++ b/homebrew/test/run_homebrew_guest_shipping_scope.sh
@@ -17,6 +17,7 @@ esac
: "${IMAGE:?missing public Homebrew image}"
: "${BOOTSTRAP:?missing public Homebrew bootstrap archive}"
+: "${PORTABLE_RUBY:?missing public Homebrew portable Ruby archive}"
: "${BOOTSTRAP_ENV:?missing public Homebrew bootstrap environment}"
: "${TAP_CATALOG_REF:?missing sealed tap catalog revision}"
: "${CANARY_REF:?missing canary revision}"
@@ -94,6 +95,7 @@ bash scripts/dev-shell.sh npx tsx \
--homebrew-bootstrap-spec \
homebrew/main-shell-brew-package-tree.json \
--homebrew-bootstrap-archive "$BOOTSTRAP" \
+ --homebrew-portable-ruby-archive "$PORTABLE_RUBY" \
--homebrew-bootstrap-env "$BOOTSTRAP_ENV" \
--transport-mode public \
--proof-mode "$scope" \
diff --git a/host/src/browser-kernel-worker-entry.ts b/host/src/browser-kernel-worker-entry.ts
index ea6be65aed..beb4bca8ac 100644
--- a/host/src/browser-kernel-worker-entry.ts
+++ b/host/src/browser-kernel-worker-entry.ts
@@ -24,6 +24,7 @@ import type {
} from "./kernel-worker";
import type { KernelPointer } from "./kernel";
import { BrowserWorkerAdapter } from "./worker-adapter-browser";
+import { prestartedWorkerPoolSize } from "./prestarted-worker-pool";
import { DeferredWorkerHandle } from "./deferred-worker-handle";
import {
readPreparedPlatformFile,
@@ -38,7 +39,10 @@ import { BrowserTimeProvider } from "./vfs/time";
import { restoreBrowserKernelInitMounts } from "./browser-kernel-vfs-init";
import type { MountConfig } from "./vfs/types";
import { TlsNetworkBackend } from "./networking/tls-network-backend";
-import { patchWasmForThread } from "./worker-main";
+import {
+ detectChannelBaseTlsOffset,
+ patchWasmForThread,
+} from "./worker-main";
import { detectPtrWidth, extractAbiVersion, extractHeapBase, isWasmModuleBytes } from "./constants";
import { ThreadExitCoordinator } from "./thread-exit-coordinator";
import {
@@ -56,6 +60,7 @@ import {
createWorkerQuiescence,
type WorkerQuiescence,
waitForExecRetirement as waitForExecRetirementFence,
+ waitForThreadExecRetirement,
waitForWorkerQuiescence as waitForWorkerQuiescenceFence,
} from "./worker-quiescence";
import { RootfsSnapshotGate } from "./rootfs-snapshot-gate";
@@ -90,6 +95,12 @@ import type {
KernelToMainMessage,
} from "./browser-kernel-protocol";
import { kernelRealmDestroyResult } from "./kernel-realm-destroy";
+import {
+ DEFAULT_EXECUTABLE_MODULE_CACHE_MAX_ALIASES,
+ DEFAULT_EXECUTABLE_MODULE_CACHE_MAX_ENTRIES,
+ DEFAULT_EXECUTABLE_MODULE_CACHE_MAX_RETAINED_BYTES,
+ ExecutableModuleCache,
+} from "./executable-module-cache";
const PAGE_SIZE = 65536;
// State
@@ -142,7 +153,9 @@ interface ProcessInfo extends ProcessGenerationOwnership {
/** Exact browser-main alias teardown, shared by competing failure paths. */
framebufferRelease?: Promise;
programBytes: ArrayBuffer;
- programModule?: WebAssembly.Module;
+ programModule: WebAssembly.Module;
+ programAbiVersion: number | null;
+ channelBaseTlsOffset: number;
worker: ReturnType;
argv: string[];
channelOffset: number;
@@ -189,6 +202,18 @@ const DESTROY_KILL_DRAIN_POLL_MS = 15;
const intentionallyTerminated = new WeakSet