Lightweight conformance
"; + return `data:text/html;charset=utf-8,${encodeURIComponent(html)}`; +} + +function passed(details = {}) { return { passed: true, ...details }; } +function failed(reason) { return { passed: false, reason: String(reason).slice(0, 1_024) }; } +function errorMessage(error) { return error instanceof Error ? error.message : String(error); } + +async function timed(target, name, operation) { + const started = performance.now(); + try { return await operation(); } + finally { target[name] = performance.now() - started; } +} + +function distribution(values) { + const finite = values.filter(Number.isFinite).sort((a, b) => a - b); + if (!finite.length) return { median: null, p95: null, min: null, max: null }; + return { + median: percentile(finite, 0.5), + p95: percentile(finite, 0.95), + min: finite[0], + max: finite.at(-1) + }; +} + +function percentile(values, point) { + const index = Math.min(values.length - 1, Math.max(0, Math.ceil(values.length * point) - 1)); + return values[index]; +} + +async function sha256(path) { + const hash = createHash("sha256"); + for await (const chunk of createReadStream(path)) hash.update(chunk); + return hash.digest("hex"); +} + +async function collectSourceIdentity(outputPath) { + const commit = await gitOutput(repositoryRoot, ["rev-parse", "HEAD"]); + const status = await gitOutput(repositoryRoot, ["status", "--porcelain=v1", "--untracked-files=all"]); + const listed = (await gitOutput(repositoryRoot, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"])) + .split("\0") + .filter(Boolean) + .map((path) => resolve(repositoryRoot, path)); + const excludedOutput = resolve(outputPath); + const generatedArtifactRoots = [ + resolve(repositoryRoot, "docs", "benchmarks", "artifacts"), + resolve(repositoryRoot, "output", "resource-benchmarks") + ]; + const sourceFiles = []; + for (const path of listed) { + if (path === excludedOutput) continue; + if (generatedArtifactRoots.some((root) => isBelow(root, path))) continue; + if (!isProofInput(repositoryRoot, path)) continue; + if ((await stat(path).catch(() => undefined))?.isFile()) sourceFiles.push(path); + } + const runtimeFiles = await filesBelow(resolve(repositoryRoot, "dist")); + return { + gitCommit: commit.trim(), + workingTreeDirty: Boolean(status.trim()), + sourceScope: "Runtime, schemas, benchmark/package/build configuration, and tests; generated documentation and benchmark artifacts are excluded.", + identityNormalization: "Relative paths use forward slashes and text line endings are normalized to LF before hashing.", + sourceFileCount: sourceFiles.length, + sourceTreeSha256: await sha256Files(repositoryRoot, sourceFiles), + runtimeBuildFileCount: runtimeFiles.length, + runtimeBuildSha256: await sha256Files(repositoryRoot, runtimeFiles), + benchmarkScriptSha256: await sha256CanonicalText(new URL(import.meta.url)) + }; +} + +function isProofInput(repositoryRoot, path) { + const candidate = relative(repositoryRoot, path).replaceAll("\\", "/"); + if (candidate.startsWith("src/") || candidate.startsWith("schemas/") || candidate.startsWith("scripts/") || candidate.startsWith("test/")) { + return true; + } + return candidate === "package.json" + || candidate === "package-lock.json" + || candidate === "server.json" + || /^tsconfig(?:\.[^.]+)?\.json$/.test(candidate); +} + +function isBelow(root, path) { + const candidate = relative(root, path); + return candidate !== "" && candidate !== ".." && !candidate.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(candidate); +} + +async function gitOutput(root, arguments_) { + const result = await execute("git", ["-C", root, ...arguments_], { + encoding: "utf8", + timeout: 15_000, + windowsHide: true, + maxBuffer: 16 * 1024 * 1024 + }); + return String(result.stdout); +} + +async function filesBelow(root) { + const files = []; + const visit = async (directory) => { + for (const entry of await readdir(directory, { withFileTypes: true })) { + const path = resolve(directory, entry.name); + if (entry.isDirectory()) await visit(path); + else if (entry.isFile()) files.push(path); + } + }; + await visit(root); + return files.sort(); +} + +async function sha256Files(root, files) { + const hash = createHash("sha256"); + for (const path of [...files].sort()) { + hash.update(relative(root, path).replaceAll("\\", "/")); + hash.update("\0"); + hash.update((await readFile(path, "utf8")).replace(/\r\n?/g, "\n")); + hash.update("\0"); + } + return hash.digest("hex"); +} + +async function sha256CanonicalText(path) { + return createHash("sha256") + .update((await readFile(path, "utf8")).replace(/\r\n?/g, "\n")) + .digest("hex"); +} + +async function binaryVersion(path) { + for (const versionArgs of [["--version"], ["version"]]) { + try { + const result = await execute(path, versionArgs, { timeout: 5_000, windowsHide: true, maxBuffer: 64 * 1024 }); + const text = `${result.stdout}\n${result.stderr}`.trim(); + if (text) return text.slice(0, 2_048); + } catch { + // Try the next conventional version command. + } + } + return "unavailable"; +} + +function parseArguments(values) { + const executable = value(values, "--executable"); + if (!executable) throw new Error("--executable is required."); + const implementation = value(values, "--implementation") ?? "obscura"; + if (implementation !== "obscura" && implementation !== "lightpanda") { + throw new Error("--implementation must be obscura or lightpanda."); + } + const sha = value(values, "--sha256"); + if (sha && !/^(?:sha256:)?[a-f0-9]{64}$/i.test(sha)) throw new Error("--sha256 must contain 64 hexadecimal characters."); + const resourceProfile = value(values, "--resource-profile") ?? "standard"; + if (resourceProfile !== "standard" && resourceProfile !== "constrained") { + throw new Error("--resource-profile must be standard or constrained."); + } + if (implementation !== "obscura" && resourceProfile === "constrained") { + throw new Error("--resource-profile constrained is available only for Obscura."); + } + return { + executable, + implementation, + resourceProfile, + ...(sha ? { sha256: sha } : {}), + iterations: integer(values, "--iterations", 5, 1, 100), + warmup: integer(values, "--warmup", 1, 0, 20), + settleMs: integer(values, "--settle-ms", 500, 0, 60_000), + targetMiB: integer(values, "--target-mib", 30, 1, 32_768), + startupTimeoutMs: integer(values, "--startup-timeout-ms", 15_000, 250, 120_000), + actionTimeoutMs: integer(values, "--action-timeout-ms", 10_000, 250, 120_000), + teardownTimeoutMs: integer(values, "--teardown-timeout-ms", 5_000, 250, 120_000), + resourceSamples: integer(values, "--resource-samples", 3, 1, 20), + resourceSampleIntervalMs: integer(values, "--resource-sample-interval-ms", 100, 25, 10_000), + output: value(values, "--output") ?? `output/resource-benchmarks/lightweight-${implementation}-${resourceProfile}-${new Date().toISOString().replaceAll(":", "-")}.json` + }; +} + +function value(values, name) { + const index = values.indexOf(name); + return index >= 0 ? values[index + 1] : undefined; +} + +function integer(values, name, fallback, minimum, maximum) { + const raw = value(values, name); + if (raw === undefined) return fallback; + const parsed = Number(raw); + if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) { + throw new Error(`${name} must be an integer between ${minimum} and ${maximum}.`); + } + return parsed; +} + +function delay(ms) { return new Promise((settle) => setTimeout(settle, ms)); } + +function settlesWithin(promise, timeoutMs) { + return new Promise((settle) => { + let settled = false; + const finish = (value) => { + if (settled) return; + settled = true; + clearTimeout(timer); + settle(value); + }; + const timer = setTimeout(() => finish(false), timeoutMs); + Promise.resolve(promise).then(() => finish(true), () => finish(true)); + }); +} diff --git a/scripts/build-whitepaper-pdf.py b/scripts/build-whitepaper-pdf.py index 3953d4c..7b425f3 100644 --- a/scripts/build-whitepaper-pdf.py +++ b/scripts/build-whitepaper-pdf.py @@ -4,8 +4,12 @@ from __future__ import annotations import html +import hashlib +import json import re import shutil +import subprocess +import sys from pathlib import Path from reportlab import rl_config @@ -34,9 +38,16 @@ ROOT = Path(__file__).resolve().parents[1] SOURCE = ROOT / "docs" / "whitepaper.md" -OUTPUT = ROOT / "output" / "pdf" / "Cockroach-Browser-Technical-White-Paper-v1.1.pdf" +PAPER_VERSION = "1.2" +IMPLEMENTATION_VERSION = "0.5.0-rc.1" +PUBLICATION_DATE = "2026-09-03" +OUTPUT = ROOT / "output" / "pdf" / "Cockroach-Browser-Technical-White-Paper-v1.2.pdf" PUBLIC_COPY = ROOT / "docs" / OUTPUT.name SITE_COPY = ROOT / "site" / "paper" / OUTPUT.name +BUILD_MANIFEST = ROOT / "docs" / "Cockroach-Browser-Technical-White-Paper-v1.2-build.json" +CHECKSUM = ROOT / "docs" / "Cockroach-Browser-Technical-White-Paper-v1.2.sha256" +SITE_BUILD_MANIFEST = ROOT / "site" / "paper" / BUILD_MANIFEST.name +SITE_CHECKSUM = ROOT / "site" / "paper" / CHECKSUM.name LOGO = ROOT / "site" / "assets" / "logo.png" PAGE_WIDTH, PAGE_HEIGHT = A4 @@ -58,6 +69,9 @@ rl_config.invariant = 1 +FONT_FILES: list[Path] = [] + + def register_fonts() -> tuple[str, str, str, str]: choices = [ ("C:/Windows/Fonts/arial.ttf", "C:/Windows/Fonts/arialbd.ttf", @@ -68,6 +82,7 @@ def register_fonts() -> tuple[str, str, str, str]: for regular, bold, italic, mono in choices: paths = [Path(value) for value in (regular, bold, italic, mono)] if all(path.exists() for path in paths): + FONT_FILES.extend(paths) pdfmetrics.registerFont(TTFont("CBBody", str(paths[0]))) pdfmetrics.registerFont(TTFont("CBBody-Bold", str(paths[1]))) pdfmetrics.registerFont(TTFont("CBBody-Italic", str(paths[2]))) @@ -141,9 +156,9 @@ def __init__(self, filename: str): rightMargin=RIGHT, topMargin=TOP, bottomMargin=BOTTOM, - title="Cockroach Browser: A Local-First Browser Runtime for AI Agents", + title="Cockroach Browser: A Governed Multi-Engine Runtime for AI Agents", author="Ajnas N B", - subject="A local-first, authenticated browser runtime for AI agents", + subject="A governed multi-engine browser runtime for AI agents", creator="Cockroach Browser white-paper build", pageCompression=1, ) @@ -170,7 +185,7 @@ def cover_page(canvas, _doc): canvas.setFillColor(colors.HexColor("#91A49E")) canvas.setFont(MONO, 7.2) canvas.drawString(LEFT, 10 * mm, "COCKROACH BROWSER / TECHNICAL PAPER") - canvas.drawRightString(PAGE_WIDTH - RIGHT, 10 * mm, "AUGUST 2026") + canvas.drawRightString(PAGE_WIDTH - RIGHT, 10 * mm, "SEPTEMBER 3, 2026") canvas.restoreState() @staticmethod @@ -190,7 +205,7 @@ def body_page(canvas, doc): canvas.setStrokeColor(RULE) canvas.line(LEFT, 13 * mm, PAGE_WIDTH - RIGHT, 13 * mm) canvas.setFont(BODY, 7.2) - canvas.drawString(LEFT, 8 * mm, "Ajnas N B - Technical white paper v1.1") + canvas.drawString(LEFT, 8 * mm, "Ajnas N B - Technical white paper v1.2") canvas.drawRightString(PAGE_WIDTH - RIGHT, 8 * mm, str(doc.page)) canvas.restoreState() @@ -366,18 +381,18 @@ def cover_story() -> list: Spacer(1, 19 * mm), logo, Spacer(1, 10 * mm), - Paragraph("COCKROACH BROWSER / VERSION 0.3.0", STYLES["cover-kicker"]), - Paragraph("A local-first browser runtime for AI agents", STYLES["cover-title"]), + Paragraph("COCKROACH BROWSER / VERSION 0.5.0-RC.1", STYLES["cover-kicker"]), + Paragraph("A governed multi-engine runtime for AI agents", STYLES["cover-title"]), Paragraph( - "The browser runtime your AI agents can use without inheriting your whole machine.", + "Full browsers for fidelity. A verified lightweight lane for compatible non-visual work. Explicit authority for both.", STYLES["cover-subtitle"], ), HRFlowable(width="100%", thickness=0.8, color=colors.HexColor("#24433C")), Spacer(1, 8 * mm), Paragraph( "Author: Ajnas N B" - "Paper version: 1.1
" - "Date: August 2026
" + "Paper version: 1.2
" + "Date: September 3, 2026
" "Concept DOI: 10.5281/zenodo.21701791
" "Software: AGPL-3.0-or-later
" "Paper: Creative Commons Attribution 4.0 International
" @@ -415,6 +430,13 @@ def toc_story() -> list: def build() -> None: + replace = "--replace" in sys.argv[1:] + authored = [OUTPUT, PUBLIC_COPY, SITE_COPY, BUILD_MANIFEST, CHECKSUM, + SITE_BUILD_MANIFEST, SITE_CHECKSUM] + existing = [path for path in authored if path.exists()] + if existing and not replace: + joined = ", ".join(str(path.relative_to(ROOT)) for path in existing) + raise FileExistsError(f"Refusing to overwrite v1.2 artifacts: {joined}. Pass --replace explicitly.") text = SOURCE.read_text(encoding="utf-8") start = text.find("## Abstract") if start < 0: @@ -422,9 +444,67 @@ def build() -> None: OUTPUT.parent.mkdir(parents=True, exist_ok=True) story = cover_story() + toc_story() + parse_markdown(text[start:]) PaperTemplate(str(OUTPUT)).multiBuild(story) + PUBLIC_COPY.parent.mkdir(parents=True, exist_ok=True) + SITE_COPY.parent.mkdir(parents=True, exist_ok=True) shutil.copyfile(OUTPUT, PUBLIC_COPY) shutil.copyfile(OUTPUT, SITE_COPY) - print(OUTPUT) + write_provenance() + print(json.dumps({ + "pdf": str(PUBLIC_COPY), + "sha256": sha256(PUBLIC_COPY), + "manifest": str(BUILD_MANIFEST), + }, indent=2)) + + +def sha256(path: Path) -> str: + digest = hashlib.sha256() + with path.open("rb") as handle: + for chunk in iter(lambda: handle.read(1024 * 1024), b""): + digest.update(chunk) + return digest.hexdigest() + + +def write_provenance() -> None: + git_commit = subprocess.run( + ["git", "rev-parse", "HEAD"], cwd=ROOT, check=True, + capture_output=True, text=True, + ).stdout.strip() + git_dirty = bool(subprocess.run( + ["git", "status", "--porcelain"], cwd=ROOT, check=True, + capture_output=True, text=True, + ).stdout.strip()) + inputs = [SOURCE, Path(__file__).resolve(), LOGO, *FONT_FILES] + pdf_digest = sha256(OUTPUT) + manifest = { + "schemaVersion": "cockroach.white-paper-build.v1", + "paperVersion": PAPER_VERSION, + "implementationVersion": IMPLEMENTATION_VERSION, + "publicationDate": PUBLICATION_DATE, + "gitBaseCommit": git_commit, + "workingTreeDirty": git_dirty, + "inputs": [ + { + "path": str(path.relative_to(ROOT)).replace("\\", "/") + if path.is_relative_to(ROOT) else str(path).replace("\\", "/"), + "bytes": path.stat().st_size, + "sha256": sha256(path), + } + for path in inputs + ], + "outputs": [ + { + "path": str(path.relative_to(ROOT)).replace("\\", "/"), + "bytes": path.stat().st_size, + "sha256": sha256(path), + } + for path in (OUTPUT, PUBLIC_COPY, SITE_COPY) + ], + "pdfSha256": pdf_digest, + } + BUILD_MANIFEST.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8") + CHECKSUM.write_text(f"{pdf_digest} {PUBLIC_COPY.name}\n", encoding="utf-8") + shutil.copyfile(BUILD_MANIFEST, SITE_BUILD_MANIFEST) + shutil.copyfile(CHECKSUM, SITE_CHECKSUM) if __name__ == "__main__": diff --git a/scripts/check-package.mjs b/scripts/check-package.mjs index 5b1083c..0881978 100644 --- a/scripts/check-package.mjs +++ b/scripts/check-package.mjs @@ -8,6 +8,7 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); const packageJson = await json("package.json"); const packageLock = await json("package-lock.json"); const server = await json("server.json"); +const publicSchemaFiles = ["action.schema.json", "browser-memory.schema.json", "session.schema.json"]; assert(packageJson.name === "cockroach-browser", "package name must be cockroach-browser"); assert(/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(packageJson.version), "package version must be valid semver"); @@ -16,6 +17,10 @@ assert(packageJson.author === "Ajnas NB", "package author must identify Ajnas NB assert(packageJson.mcpName === "io.github.AjnasNB/cockroach-browser", "mcpName must match the authorized, case-sensitive MCP registry identity"); assert(packageJson.engines?.node === "^22.0.0 || ^24.0.0 || ^26.0.0", "Node support must remain 22, 24, and 26"); assert(packageLock.name === packageJson.name && packageLock.version === packageJson.version, "package-lock identity is stale"); +for (const schemaFile of publicSchemaFiles) { + const subpath = `./schemas/${schemaFile}`; + assert(packageJson.exports?.[subpath] === subpath, `package exports are missing ${subpath}`); +} assert(server.name === packageJson.mcpName, "server.json name must match package mcpName"); assert(server.version === packageJson.version, "server.json version must match package version"); assert( @@ -66,7 +71,9 @@ const requiredSourceFiles = [ "dist/integrations/qarinah.js", "dist/integrations/crawler.js", "dist/integrations/productloop.js", + "schemas/action.schema.json", "schemas/browser-memory.schema.json", + "schemas/session.schema.json", "docs/compatibility/browser-api-surface.json", "sdks/python/cockroach_browser/client.py", "sdks/java/src/main/java/io/cockroach/browser/Client.java", diff --git a/scripts/test-packed-consumer.mjs b/scripts/test-packed-consumer.mjs index f2e7ba2..0b87609 100644 --- a/scripts/test-packed-consumer.mjs +++ b/scripts/test-packed-consumer.mjs @@ -38,7 +38,9 @@ import { BrowserAgent } from "cockroach-browser/agent"; import { OpenAICompatibleModelGateway } from "cockroach-browser/model-gateway"; import { BrowserFleet, LocalBrowserFleetProvider } from "cockroach-browser/fleet"; import { createRawCdpSession } from "cockroach-browser/cdp"; +import actionSchema from "cockroach-browser/schemas/action.schema.json" with { type: "json" }; import memorySchema from "cockroach-browser/schemas/browser-memory.schema.json" with { type: "json" }; +import sessionSchema from "cockroach-browser/schemas/session.schema.json" with { type: "json" }; import server from "cockroach-browser/server.json" with { type: "json" }; if (CAPABILITIES.length < 73) throw new Error("operator capabilities missing"); if (typeof BrowserClient !== "function") throw new Error("client missing"); @@ -54,7 +56,9 @@ if (typeof playwrightTest !== "function" || typeof playwrightExpect !== "functio for (const exported of [BidiSession, WebDriverClient, BrowserAgent, OpenAICompatibleModelGateway, BrowserFleet, LocalBrowserFleetProvider, createRawCdpSession]) { if (typeof exported !== "function") throw new Error("expanded platform export missing"); } -if (memorySchema.properties?.schemaVersion?.const !== "cockroach.browser-memory.v1") throw new Error("memory schema mismatch"); +if (actionSchema.$id !== "https://cockroachbrowser.com/schemas/action.schema.json" || !actionSchema.$defs?.actionKind) throw new Error("action schema mismatch"); +if (memorySchema.properties?.schemaVersion?.const !== "cockroach.browser-memory.v2") throw new Error("memory schema mismatch"); +if (sessionSchema.$id !== "https://cockroachbrowser.com/schemas/session.schema.json" || !sessionSchema.properties?.browserProvider) throw new Error("session schema mismatch"); if (server.name !== "io.github.AjnasNB/cockroach-browser") throw new Error("MCP identity mismatch"); process.stdout.write(JSON.stringify({ ok: true, capabilities: CAPABILITIES.length }) + "\\n"); ` diff --git a/scripts/verify-lightweight-proof.mjs b/scripts/verify-lightweight-proof.mjs new file mode 100644 index 0000000..c033376 --- /dev/null +++ b/scripts/verify-lightweight-proof.mjs @@ -0,0 +1,338 @@ +import { createHash } from "node:crypto"; +import { execFile } from "node:child_process"; +import { createReadStream } from "node:fs"; +import { readFile, readdir, stat } from "node:fs/promises"; +import { dirname, isAbsolute, relative, resolve } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; + +const execute = promisify(execFile); +const root = resolve(dirname(fileURLToPath(import.meta.url)), ".."); +const paths = [ + resolve(root, process.argv[2] ?? "docs/benchmarks/artifacts/obscura-0.2.1-constrained-non-visual-30mib-2026-09-03-rc1.json"), + resolve(root, process.argv[3] ?? "docs/benchmarks/artifacts/obscura-0.2.1-constrained-non-visual-25mib-2026-09-03-rc1.json") +]; +const proofRecordPath = resolve(root, "docs/benchmarks/obscura-non-visual-2026-09-03.md"); +const readmePath = resolve(root, "README.md"); +const reports = await Promise.all(paths.map(async (path) => JSON.parse(await readFile(path, "utf8")))); +const artifactDigests = await Promise.all(paths.map(sha256)); + +assertReport(reports[0], 30, true); +assertReport(reports[1], 25, undefined); +for (const key of [ + "gitCommit", + "workingTreeDirty", + "sourceScope", + "identityNormalization", + "sourceFileCount", + "sourceTreeSha256", + "runtimeBuildFileCount", + "runtimeBuildSha256", + "benchmarkScriptSha256" +]) { + assert(reports[0].sourceIdentity[key] === reports[1].sourceIdentity[key], `proof artifacts disagree on sourceIdentity.${key}`); +} +assert(reports[0].executable.sha256 === reports[1].executable.sha256, "proof artifacts used different binaries"); +for (const key of ["name", "bytes", "version"]) { + assert(reports[0].executable[key] === reports[1].executable[key], `proof artifacts disagree on executable.${key}`); +} +for (const key of ["platform", "architecture", "release", "logicalCpuCount", "cpuModel", "totalMemoryBytes", "node"]) { + assert(equalJson(reports[0].machine[key], reports[1].machine[key]), `proof artifacts were not measured on the same machine: machine.${key}`); +} +for (const key of [ + "warmup", + "iterations", + "settleMs", + "startupTimeoutMs", + "actionTimeoutMs", + "teardownTimeoutMs", + "resourceSamples", + "resourceSampleIntervalMs", + "targetDefinition", + "memoryDefinition", + "renderingControl", + "workload", + "requiredChecks", + "optionalChecks" +]) { + assert(equalJson(reports[0].methodology[key], reports[1].methodology[key]), `proof artifacts disagree on methodology.${key}`); +} + +const current = await collectCurrentIdentity(paths); +for (const key of [ + "sourceFileCount", + "sourceTreeSha256", + "runtimeBuildFileCount", + "runtimeBuildSha256", + "benchmarkScriptSha256" +]) { + assert(reports[0].sourceIdentity[key] === current[key], `proof artifact is stale: sourceIdentity.${key}`); +} +await assertNarrativeConsistency(reports, paths, artifactDigests, current); + +process.stdout.write(`${JSON.stringify({ + ok: true, + artifacts: paths.map((path, index) => ({ + path: relative(root, path).replaceAll("\\", "/"), + sha256: artifactDigests[index] + })), + sourceTreeSha256: current.sourceTreeSha256, + runtimeBuildSha256: current.runtimeBuildSha256, + outcomes: reports.map((report) => ({ + targetMiB: report.methodology.targetMiB, + passed: report.verdict.passed, + maxObservedBrowserTreeRssBytes: report.verdict.maxObservedBrowserTreeRssBytes + })) +}, null, 2)}\n`); + +function assertReport(report, targetMiB, requiredVerdict) { + assert(report?.schemaVersion === "cockroach.lightweight-browser-benchmark.v2", "unexpected benchmark schema"); + assert(report.implementation === "obscura", "proof must use Obscura"); + assert(report.resourceProfile === "constrained", "proof must use the constrained profile"); + assert(report.renderingPolicy === "visual-actions-denied", "proof must identify the visual-action policy without asserting renderer state"); + assert(report.executable?.name === "obscura.exe", "proof must disclose the binary name"); + assert(report.executable?.version === "obscura 0.2.1", "proof must use Obscura 0.2.1"); + assert(report.executable?.sha256 === "5b609fb46bc00da79e450fb0fbd34bd442e565b1394f4af95433e0b341078221", "proof must use the reviewed binary digest"); + assert(Number.isSafeInteger(report.executable?.bytes) && report.executable.bytes > 0, "proof must disclose a positive executable size"); + assert(Number.isFinite(Date.parse(report.generatedAt)), "proof generatedAt must be an ISO timestamp"); + assert(/^[a-f0-9]{40}$/.test(report.sourceIdentity?.gitCommit ?? ""), "proof must identify its Git base commit"); + assert(report.sourceIdentity?.workingTreeDirty === true || report.sourceIdentity?.workingTreeDirty === false, "proof must disclose working-tree state"); + assert(report.sourceIdentity?.identityNormalization === "Relative paths use forward slashes and text line endings are normalized to LF before hashing.", "proof must disclose its portable identity normalization"); + assert(/^[a-f0-9]{64}$/.test(report.sourceIdentity?.sourceTreeSha256 ?? ""), "proof must identify its source tree"); + assert(/^[a-f0-9]{64}$/.test(report.sourceIdentity?.runtimeBuildSha256 ?? ""), "proof must identify its runtime build"); + assert(/^[a-f0-9]{64}$/.test(report.sourceIdentity?.benchmarkScriptSha256 ?? ""), "proof must identify its benchmark harness"); + assert(typeof report.machine?.platform === "string" && report.machine.platform.length > 0, "proof must disclose its operating-system platform"); + assert(typeof report.machine?.architecture === "string" && report.machine.architecture.length > 0, "proof must disclose its CPU architecture"); + assert(typeof report.machine?.release === "string" && report.machine.release.length > 0, "proof must disclose its operating-system release"); + assert(typeof report.machine?.node === "string" && report.machine.node.length > 0, "proof must disclose its Node.js version"); + assert(report.methodology?.warmup === 1, "proof must include one warmup run"); + assert(report.methodology?.iterations === 20, "proof must include twenty measured runs"); + assert(report.methodology?.resourceSamples === 10, "proof must include ten explicit steady-state samples per run"); + assert(report.methodology?.resourceSampleIntervalMs === 25, "proof must sample at 25 ms intervals"); + assert(Number.isSafeInteger(report.methodology?.teardownTimeoutMs) && report.methodology.teardownTimeoutMs >= 250, "proof must disclose a bounded teardown timeout"); + assert(report.methodology?.targetMiB === targetMiB, `proof target must be ${targetMiB} MiB`); + assert(report.methodology?.renderingControl?.includes("does not assert"), "proof must disclaim unverified engine renderer state"); + assert(!/renderer (?:is|was|has been) disabled/i.test(report.methodology?.renderingControl ?? ""), "proof must not claim that the engine renderer was disabled"); + assert(report.methodology?.energy?.available === false, "proof must not invent energy measurements"); + assert(Array.isArray(report.samples) && report.samples.length === 20, "proof must retain all measured samples"); + const requiredChecks = ["connect", "javascript", "dom", "forms", "screenshot", "teardown"]; + assert(equalJson(report.methodology?.requiredChecks, requiredChecks), "proof requiredChecks must include visual-policy enforcement and teardown"); + assert(equalJson(report.methodology?.optionalChecks, []), "proof must not label a verdict-critical visual-policy check as optional"); + const targetBytes = targetMiB * 1024 ** 2; + let maximum = 0; + for (const [index, sample] of report.samples.entries()) { + const observations = sample?.browserTree?.observations; + assert(Array.isArray(observations) && observations.length >= 10, `sample ${index + 1} did not retain enough raw resource observations`); + assert(sample.browserTree.sampleCount === observations.length, `sample ${index + 1} sampleCount does not match retained observations`); + let samplePeakRss = 0; + let samplePeakCpu = 0; + let samplePeakProcesses = 0; + for (const [observationIndex, observation] of observations.entries()) { + assert(Number.isFinite(Date.parse(observation?.sampledAt)), `sample ${index + 1} observation ${observationIndex + 1} has no timestamp`); + assert(Number.isSafeInteger(observation?.rssBytes) && observation.rssBytes > 0, `sample ${index + 1} observation ${observationIndex + 1} has invalid RSS`); + assert(Number.isFinite(observation?.cpuTimeMs) && observation.cpuTimeMs >= 0, `sample ${index + 1} observation ${observationIndex + 1} has invalid CPU time`); + assert(Number.isSafeInteger(observation?.processCount) && observation.processCount >= 1, `sample ${index + 1} observation ${observationIndex + 1} has no owned browser process`); + samplePeakRss = Math.max(samplePeakRss, observation.rssBytes); + samplePeakCpu = Math.max(samplePeakCpu, observation.cpuTimeMs); + samplePeakProcesses = Math.max(samplePeakProcesses, observation.processCount); + } + assert(sample.browserTree.peakRssBytes === samplePeakRss, `sample ${index + 1} peak RSS is inconsistent with retained observations`); + assert(sample.browserTree.cpuTimeMs === samplePeakCpu, `sample ${index + 1} CPU time is inconsistent with retained observations`); + assert(sample.browserTree.processCount === samplePeakProcesses, `sample ${index + 1} process count is inconsistent with retained observations`); + for (const check of requiredChecks) { + assert(sample.conformance?.[check]?.passed === true, `sample ${index + 1} failed required check ${check}`); + } + assert(sample.conformance.teardown.rootProcessExited === true, `sample ${index + 1} did not verify root-process exit`); + assert(sample.conformance.teardown.transportDisposed === true, `sample ${index + 1} did not verify bounded CDP transport disposal`); + assert(sample.conformance?.screenshot?.passed === true && sample.conformance.screenshot.supported === false, `sample ${index + 1} did not enforce the visual-action preflight`); + for (const timing of ["launchMs", "connectMs", "workloadMs", "shutdownMs"]) { + assert(Number.isFinite(sample.timings?.[timing]) && sample.timings[timing] >= 0, `sample ${index + 1} has invalid ${timing}`); + } + assert(Number.isSafeInteger(sample.coordinator?.peakRssBytes) && sample.coordinator.peakRssBytes > 0, `sample ${index + 1} has invalid coordinator RSS`); + assert(Number.isFinite(sample.coordinator?.cpuTimeMs) && sample.coordinator.cpuTimeMs >= 0, `sample ${index + 1} has invalid coordinator CPU time`); + assert(!Object.hasOwn(sample, "failure"), `sample ${index + 1} retained an operation failure despite a passing conformance set`); + maximum = Math.max(maximum, samplePeakRss); + } + const everyRunWithinTarget = report.samples.every((sample) => + sample.browserTree.observations.every((observation) => observation.rssBytes <= targetBytes) + ); + assert(report.verdict?.targetBytes === targetBytes, "verdict targetBytes is inconsistent"); + assert(report.verdict?.maxObservedBrowserTreeRssBytes === maximum, "verdict maximum is inconsistent with retained samples"); + assert(report.verdict?.everyRunWithinTarget === everyRunWithinTarget, "memory verdict is inconsistent with retained samples"); + assert(report.verdict?.requiredConformancePassed === true, "required conformance verdict must pass"); + assert(report.verdict?.passed === everyRunWithinTarget, "combined verdict is inconsistent"); + if (requiredVerdict !== undefined) assert(report.verdict.passed === requiredVerdict, `the ${targetMiB} MiB proof has the wrong verdict`); + assertDistribution(report.summary?.peakBrowserTreeRssBytes, report.samples.map((sample) => sample.browserTree.peakRssBytes), "peak browser-tree RSS"); + assertDistribution(report.summary?.browserCpuTimeMs, report.samples.map((sample) => sample.browserTree.cpuTimeMs), "browser CPU time"); + assertDistribution(report.summary?.processCount, report.samples.map((sample) => sample.browserTree.processCount), "process count"); + assertDistribution(report.summary?.launchMs, report.samples.map((sample) => sample.timings.launchMs), "launch timing"); + assertDistribution(report.summary?.connectMs, report.samples.map((sample) => sample.timings.connectMs), "connect timing"); + assertDistribution(report.summary?.workloadMs, report.samples.map((sample) => sample.timings.workloadMs), "workload timing"); + assertDistribution(report.summary?.shutdownMs, report.samples.map((sample) => sample.timings.shutdownMs), "shutdown timing"); + assertDistribution(report.summary?.coordinatorPeakRssBytes, report.samples.map((sample) => sample.coordinator.peakRssBytes), "coordinator peak RSS"); +} + +async function assertNarrativeConsistency(reports, artifactPaths, artifactDigests, current) { + const [readme, proofRecord] = await Promise.all([ + readFile(readmePath, "utf8"), + readFile(proofRecordPath, "utf8") + ]); + const proofLink = "docs/benchmarks/obscura-non-visual-2026-09-03.md"; + assert(readme.replaceAll("\\", "/").includes(proofLink), "README must link to the current non-visual proof record"); + assert(readme.includes(reports[0].executable.sha256), "README must identify the reviewed Obscura digest"); + assert(readme.split(/\r?\n/).some((line) => /whole[- ]app/i.test(line) && /not|doesn't|does not/i.test(line)), "README must disclaim a whole-app memory guarantee"); + for (const report of reports) assertTargetNarrative(readme, report, reports, "README"); + + for (const [index, artifactPath] of artifactPaths.entries()) { + const artifact = relative(root, artifactPath).replaceAll("\\", "/"); + assert(proofRecord.replaceAll("\\", "/").includes(artifact), `proof record must name ${artifact}`); + assert(proofRecord.includes(artifactDigests[index]), `proof record must identify the SHA-256 of ${artifact}`); + } + for (const hash of [ + reports[0].executable.sha256, + current.sourceTreeSha256, + current.runtimeBuildSha256, + reports[0].sourceIdentity.benchmarkScriptSha256 + ]) { + assert(proofRecord.includes(hash), `proof record must bind narrative claims to ${hash}`); + } + assert(/does not assert[^\n]*renderer|renderer[^\n]*does not assert/i.test(proofRecord), "proof record must disclaim unverified renderer state"); + assert(proofRecord.split(/\r?\n/).some((line) => /coordinator/i.test(line) && /separate/i.test(line)), "proof record must disclose coordinator memory separately"); + for (const report of reports) assertTargetNarrative(proofRecord, report, reports, "proof record"); +} + +function assertTargetNarrative(text, report, allReports, label) { + const target = report.methodology.targetMiB; + const maximum = report.verdict.maxObservedBrowserTreeRssBytes; + const verdict = report.verdict.passed ? /pass(?:ed|es|ing)?/i : /fail(?:ed|s|ing)?/i; + const otherTargets = allReports.map((candidate) => candidate.methodology.targetMiB).filter((candidate) => candidate !== target); + const lines = text.split(/\r?\n/).filter((line) => + new RegExp(`${target}\\s*MiB`, "i").test(line) + && otherTargets.every((other) => !new RegExp(`${other}\\s*MiB`, "i").test(line)) + ); + assert(lines.length > 0, `${label} must name the ${target} MiB result`); + assert(lines.some((line) => containsNumber(line, maximum)), `${label} must state the exact ${target} MiB maximum of ${maximum} bytes`); + assert(lines.some((line) => verdict.test(line)), `${label} must state the honest ${target} MiB verdict`); +} + +function containsNumber(text, value) { + return new RegExp(`(?:^|\\D)${value}(?!\\d)`).test(text.replace(/[,_]/g, "")); +} + +function assertDistribution(actual, values, label) { + const expected = distribution(values); + assert(equalJson(actual, expected), `summary ${label} distribution is inconsistent with retained samples`); +} + +function distribution(values) { + const finite = values.filter(Number.isFinite).sort((left, right) => left - right); + if (finite.length === 0) return { median: null, p95: null, min: null, max: null }; + return { + median: percentile(finite, 0.5), + p95: percentile(finite, 0.95), + min: finite[0], + max: finite.at(-1) + }; +} + +function percentile(values, point) { + const index = Math.min(values.length - 1, Math.max(0, Math.ceil(values.length * point) - 1)); + return values[index]; +} + +function equalJson(left, right) { + return JSON.stringify(left) === JSON.stringify(right); +} + +async function collectCurrentIdentity(artifactPaths) { + const listed = (await gitOutput(["ls-files", "-z", "--cached", "--others", "--exclude-standard"])) + .split("\0") + .filter(Boolean) + .map((path) => resolve(root, path)); + const artifactRoots = [ + resolve(root, "docs", "benchmarks", "artifacts"), + resolve(root, "output", "resource-benchmarks") + ]; + const excluded = new Set(artifactPaths); + const sourceFiles = []; + for (const path of listed) { + if (excluded.has(path) || artifactRoots.some((artifactRoot) => isBelow(artifactRoot, path))) continue; + if (!isProofInput(path)) continue; + if ((await stat(path).catch(() => undefined))?.isFile()) sourceFiles.push(path); + } + const runtimeFiles = await filesBelow(resolve(root, "dist")); + return { + sourceFileCount: sourceFiles.length, + sourceTreeSha256: await sha256Files(sourceFiles), + runtimeBuildFileCount: runtimeFiles.length, + runtimeBuildSha256: await sha256Files(runtimeFiles), + benchmarkScriptSha256: await sha256CanonicalText(resolve(root, "scripts", "benchmark-lightweight.mjs")) + }; +} + +function isProofInput(path) { + const candidate = relative(root, path).replaceAll("\\", "/"); + return candidate.startsWith("src/") + || candidate.startsWith("schemas/") + || candidate.startsWith("scripts/") + || candidate.startsWith("test/") + || candidate === "package.json" + || candidate === "package-lock.json" + || candidate === "server.json" + || /^tsconfig(?:\.[^.]+)?\.json$/.test(candidate); +} + +function isBelow(parent, path) { + const candidate = relative(parent, path); + return candidate !== "" && candidate !== ".." && !candidate.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`) && !isAbsolute(candidate); +} + +async function gitOutput(arguments_) { + const result = await execute("git", ["-C", root, ...arguments_], { + encoding: "utf8", + timeout: 15_000, + windowsHide: true, + maxBuffer: 16 * 1024 * 1024 + }); + return String(result.stdout); +} + +async function filesBelow(directory) { + const files = []; + const visit = async (current) => { + for (const entry of await readdir(current, { withFileTypes: true })) { + const path = resolve(current, entry.name); + if (entry.isDirectory()) await visit(path); + else if (entry.isFile()) files.push(path); + } + }; + await visit(directory); + return files.sort(); +} + +async function sha256(path) { + const hash = createHash("sha256"); + for await (const chunk of createReadStream(path)) hash.update(chunk); + return hash.digest("hex"); +} + +async function sha256Files(files) { + const hash = createHash("sha256"); + for (const path of [...files].sort()) { + hash.update(relative(root, path).replaceAll("\\", "/")); + hash.update("\0"); + hash.update((await readFile(path, "utf8")).replace(/\r\n?/g, "\n")); + hash.update("\0"); + } + return hash.digest("hex"); +} + +async function sha256CanonicalText(path) { + return createHash("sha256") + .update((await readFile(path, "utf8")).replace(/\r\n?/g, "\n")) + .digest("hex"); +} + +function assert(condition, message) { + if (!condition) throw new Error(message); +} diff --git a/sdks/dotnet/CockroachBrowser/CockroachBrowser.csproj b/sdks/dotnet/CockroachBrowser/CockroachBrowser.csproj index 7d2ad98..d64e696 100644 --- a/sdks/dotnet/CockroachBrowser/CockroachBrowser.csproj +++ b/sdks/dotnet/CockroachBrowser/CockroachBrowser.csproj @@ -4,6 +4,6 @@
Cockroach Browser
- 0.4.1
+ 0.5.0-rc.1