Normalise tracked text files and formatter scope

Releasing 0.25.83

.gitattributes

@@ -13,6 +13,11 @@
 *.mjs text eol=lf
 *.css text eol=lf
 
+# Extensionless text files
+.gitignore text eol=lf
+.dockerignore text eol=lf
+Dockerfile text eol=lf
+
 # Binary files — no line ending conversion
 *.png binary
 *.jpg binary
@@ -21,4 +26,3 @@
 *.ico binary
 *.woff2 binary
 *.woff binary
-*.sh text eol=lf

.github/workflows/finalise-release.yml

@@ -60,24 +60,16 @@ jobs:
                     exit 1
                   fi
                   node utils/release-notes.mjs validate "${VERSION}"
-                  git fetch --tags --force
-                  if git rev-parse --verify --quiet "refs/tags/${VERSION}" >/dev/null; then
-                    echo "Tag already exists: ${VERSION}" >&2
-                    exit 1
-                  fi
-                  if git rev-parse --verify --quiet "refs/tags/${VERSION}-cli" >/dev/null; then
-                    echo "Tag already exists: ${VERSION}-cli" >&2
-                    exit 1
-                  fi
 
-            - name: Create and push release tags
+            - name: Ensure and push release tags
               env:
                   VERSION: ${{ inputs.version }}
+                  EXPECTED_HEAD_SHA: ${{ inputs.expected_head_sha }}
               run: |
                   set -euo pipefail
-                  git tag "${VERSION}"
+                  git fetch --tags --force
-                  git tag "${VERSION}-cli"
+                  node utils/release-tags.mjs ensure "${VERSION}" "${EXPECTED_HEAD_SHA}"
-                  git push origin "${VERSION}" "${VERSION}-cli"
+                  git push --atomic origin "refs/tags/${VERSION}" "refs/tags/${VERSION}-cli"
 
             - name: Dispatch release workflows
               env:
@@ -100,7 +92,7 @@ jobs:
                   VERSION: ${{ inputs.version }}
               run: |
                   {
-                    echo "Created tags \`${VERSION}\` and \`${VERSION}-cli\`."
+                    echo "Ensured tags \`${VERSION}\` and \`${VERSION}-cli\` point to the reviewed release commit."
                     echo ""
                     echo "Dispatched the plug-in release workflow for \`${VERSION}\`. After approval for the release environment, it creates a draft GitHub Release."
                     echo "Dispatched the CLI Docker workflow for \`${VERSION}-cli\`. It publishes the version, major-minor, latest, and SHA-qualified image tags."

.github/workflows/prepare-release.yml

@@ -78,7 +78,6 @@ jobs:
                   git switch -c "${BRANCH}"
                   npm version "${VERSION}" --no-git-tag-version
                   node utils/release-notes.mjs prepare "${VERSION}"
-                  npm run pretty:json
                   npm run build:lib:types
 
                   git add package.json package-lock.json manifest.json versions.json updates.md src/apps/cli/package.json src/apps/webpeer/package.json src/apps/webapp/package.json _types

.github/workflows/release.yml

@@ -1,10 +1,5 @@
 name: Release Obsidian Plugin
 on:
-  push:
-    # Sequence of patterns matched against refs/tags
-    tags:
-    - '*' # Push events to matching any tag format, i.e. 1.0, 20.15.10
-    - '!*-cli' # Exclude command-line interface tags
   workflow_dispatch:
     inputs:
       tag:
@@ -33,29 +28,25 @@ jobs:
     steps:
     - uses: actions/checkout@v4
       with:
-        fetch-depth: 0 # otherwise, you will failed to push refs to dest repo
+        fetch-depth: 0
         submodules: recursive
-        ref: ${{ github.event_name == 'workflow_dispatch' && inputs.tag || github.ref }}
+        ref: ${{ inputs.tag }}
     - name: Use Node.js
       uses: actions/setup-node@v4
       with:
-        node-version: '24.x' # You might need to adjust this value to your own version
+        node-version: '24.x'
-    # Get the version number and put it in a variable
+    - name: Validate release
-    - name: Get Version
+      env:
-      id: version
+        TAG: ${{ inputs.tag }}
       run: |
-        if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+        set -euo pipefail
-          TAG="${{ inputs.tag }}"
+        node utils/release-notes.mjs validate "${TAG}"
-          DRAFT="${{ inputs.draft }}"
+        HEAD_SHA="$(git rev-parse HEAD)"
-          PRERELEASE="${{ inputs.prerelease }}"
+        TAG_SHA="$(git rev-parse "refs/tags/${TAG}^{commit}")"
-        else
+        if [[ "${HEAD_SHA}" != "${TAG_SHA}" ]]; then
-          TAG="${GITHUB_REF_NAME}"
+          echo "Checked-out commit is ${HEAD_SHA}, but tag ${TAG} points to ${TAG_SHA}." >&2
-          DRAFT="true"
+          exit 1
-          PRERELEASE="false"
         fi
-        echo "tag=${TAG}" >> $GITHUB_OUTPUT
-        echo "draft=${DRAFT}" >> $GITHUB_OUTPUT
-        echo "prerelease=${PRERELEASE}" >> $GITHUB_OUTPUT
     # Build the plugin
     - name: Build
       id: build
@@ -84,7 +75,7 @@ jobs:
           main.js
           manifest.json
           styles.css
-        name: ${{ steps.version.outputs.tag }}
+        name: ${{ inputs.tag }}
-        tag_name: ${{ steps.version.outputs.tag }}
+        tag_name: ${{ inputs.tag }}
-        draft: ${{ steps.version.outputs.draft }}
+        draft: ${{ inputs.draft }}
-        prerelease: ${{ steps.version.outputs.prerelease }}
+        prerelease: ${{ inputs.prerelease }}

.prettierignore

@@ -2,3 +2,4 @@ pouchdb-browser.js
 main_org.js
 main.js
 _types/**
+src/lib/**

devs.md

@@ -274,7 +274,8 @@ The `Finalise Release Tags` and `Release Obsidian Plugin` workflows use the `rel
 
 - Run the `Prepare Release PR` workflow with the target version. It creates the release branch, updates versions, regenerates the `_types` fallback definitions used by the community plug-in scan, moves the `## Unreleased` notes to the target version, commits the release preparation, pushes the branch, and opens a draft release PR.
 - Do not tag the release branch when the PR is first created. Polish the release PR first, especially `updates.md`.
-- Once the release PR head is fixed, run the `Finalise Release Tags` workflow with its full head commit SHA. It validates the release branch, pushes both the plug-in tag (for example, `0.25.81`) and the CLI tag (for example, `0.25.81-cli`) to that commit, and explicitly dispatches the plug-in and CLI publishing workflows. An explicit dispatch is required because tags pushed with `GITHUB_TOKEN` do not trigger tag-push workflows.
+- Once the release PR head is fixed, run the `Finalise Release Tags` workflow with its full head commit SHA. It validates the release branch, ensures that both the plug-in tag (for example, `0.25.81`) and the CLI tag (for example, `0.25.81-cli`) point to that commit, and explicitly dispatches the plug-in and CLI publishing workflows. The workflow can be retried when existing tags already point to the reviewed commit, but stops if either tag points elsewhere.
+- The plug-in publishing workflow is intentionally dispatch-only. Pushing a plug-in tag directly does not publish a GitHub Release; use `Finalise Release Tags`, or dispatch `Release Obsidian Plugin` explicitly for recovery or a pre-release. The CLI Docker workflow retains its documented branch, tag, and manual triggers.
 - Approve the `Release Obsidian Plugin` workflow for the `release` environment, then inspect the generated draft GitHub Release. Confirm that the CLI workflow has published the fixed version tag, the major-minor moving tag (for example, `0.25-cli`), `latest`, and the SHA-qualified tag.
 - Publish the draft GitHub Release as the latest stable release while keeping the release PR in draft and leaving `main` unchanged. Record the state in the PR with: 'Release `<version>` has been published as the latest stable release. This pull request intentionally remains in draft, and `main` has not yet been updated. Merge is on hold until BRAT validation is complete.'
 - Validate the published release through BRAT. Confirm start-up, ordinary bidirectional synchronisation, and any regression scenario relevant to the release.

src/apps/_test/storageAdapterContract.ts

@@ -87,7 +87,10 @@ export const storageAdapterContractCases: readonly StorageAdapterContractCase[]
         name: "keeps operations inside the configured root",
         async run(adapter) {
             await assertRejects(() => adapter.exists("../outside"), "parent traversal should be rejected");
-            await assertRejects(() => adapter.write("nested/../outside", "content"), "nested traversal should be rejected");
+            await assertRejects(
+                () => adapter.write("nested/../outside", "content"),
+                "nested traversal should be rejected"
+            );
             await assertRejects(() => adapter.read("/absolute"), "absolute paths should be rejected");
             await assertRejects(() => adapter.read("C:\\absolute"), "drive-qualified paths should be rejected");
             await assertRejects(() => adapter.read("nested\\outside"), "backslash-separated paths should be rejected");
@@ -101,8 +104,14 @@ export const storageAdapterContractCases: readonly StorageAdapterContractCase[]
             assertEqual(await adapter.exists(""), true, "the configured root should exist");
             assertEqual((await adapter.stat(""))?.type, "folder", "the configured root should be a folder");
             assertEqual(await adapter.list(""), { files: [], folders: [] }, "the configured root should be listable");
-            await assertRejects(() => adapter.write("", "content"), "writing over the configured root should be rejected");
+            await assertRejects(
-            await assertRejects(() => adapter.append("", "content"), "appending to the configured root should be rejected");
+                () => adapter.write("", "content"),
+                "writing over the configured root should be rejected"
+            );
+            await assertRejects(
+                () => adapter.append("", "content"),
+                "appending to the configured root should be rejected"
+            );
         },
     },
 ];

src/apps/cli/testdeno/bench-couchdb.ts

@@ -1,17 +1,8 @@
 import { TempDir } from "./helpers/temp.ts";
-import {
+import { applyRemoteSyncSettings, initSettingsFile } from "./helpers/settings.ts";
-    applyRemoteSyncSettings,
-    initSettingsFile,
-} from "./helpers/settings.ts";
 import { assertFilesEqual, runCliOrFail } from "./helpers/cli.ts";
-import {
+import { createCouchdbDatabase, startCouchdb, stopCouchdb } from "./helpers/docker.ts";
-    createCouchdbDatabase,
+import { createDeterministicDataset } from "./helpers/dataset.ts";
-    startCouchdb,
-    stopCouchdb,
-} from "./helpers/docker.ts";
-import {
-    createDeterministicDataset,
-} from "./helpers/dataset.ts";
 import {
     type BenchmarkVerificationMode,
     parseBenchmarkVerificationMode,
@@ -81,10 +72,7 @@ function readEnvStringArray(name: string, fallback: string[]): string[] {
 
     try {
         const parsed = JSON.parse(raw);
-        if (
+        if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
-            Array.isArray(parsed) &&
-            parsed.every((item) => typeof item === "string")
-        ) {
             return parsed;
         }
     } catch {
@@ -119,60 +107,34 @@ function formatBytes(value: number): string {
 function buildConfig(): BenchmarkConfig {
     return {
         caseName: readEnvString("BENCH_CASE", "couchdb-baseline"),
-        couchdbBackendUri: readEnvString(
+        couchdbBackendUri: readEnvString("BENCH_COUCHDB_BACKEND_URI", "http://127.0.0.1:5989"),
-            "BENCH_COUCHDB_BACKEND_URI",
+        couchdbProxyUri: readEnvString("BENCH_COUCHDB_URI", "http://127.0.0.1:15989"),
-            "http://127.0.0.1:5989",
+        couchdbUser: readEnvString("BENCH_COUCHDB_USER", readEnvString("username", "admin")),
-        ),
+        couchdbPassword: readEnvString("BENCH_COUCHDB_PASSWORD", readEnvString("password", "password")),
-        couchdbProxyUri: readEnvString(
+        couchdbDbname: readEnvString("BENCH_COUCHDB_DBNAME", `bench-couchdb-${Date.now()}`),
-            "BENCH_COUCHDB_URI",
-            "http://127.0.0.1:15989",
-        ),
-        couchdbUser: readEnvString(
-            "BENCH_COUCHDB_USER",
-            readEnvString("username", "admin"),
-        ),
-        couchdbPassword: readEnvString(
-            "BENCH_COUCHDB_PASSWORD",
-            readEnvString("password", "password"),
-        ),
-        couchdbDbname: readEnvString(
-            "BENCH_COUCHDB_DBNAME",
-            `bench-couchdb-${Date.now()}`,
-        ),
         datasetDirName: readEnvString("BENCH_DATASET_DIR", "bench-dataset"),
         datasetSeed: readEnvString("BENCH_SEED", "livesync-benchmark-seed"),
         mdFileCount: Math.floor(readEnvNumber("BENCH_MD_FILE_COUNT", 1500)),
-        mdMinSizeBytes: Math.floor(
+        mdMinSizeBytes: Math.floor(readEnvNumber("BENCH_MD_MIN_SIZE_BYTES", 1024)),
-            readEnvNumber("BENCH_MD_MIN_SIZE_BYTES", 1024),
+        mdMaxSizeBytes: Math.floor(readEnvNumber("BENCH_MD_MAX_SIZE_BYTES", 20 * 1024)),
-        ),
-        mdMaxSizeBytes: Math.floor(
-            readEnvNumber("BENCH_MD_MAX_SIZE_BYTES", 20 * 1024),
-        ),
         binFileCount: Math.floor(readEnvNumber("BENCH_BIN_FILE_COUNT", 500)),
-        binSizeBytes: Math.floor(
+        binSizeBytes: Math.floor(readEnvNumber("BENCH_BIN_SIZE_BYTES", 100 * 1024)),
-            readEnvNumber("BENCH_BIN_SIZE_BYTES", 100 * 1024),
-        ),
         syncTimeoutSeconds: readEnvNumber("BENCH_SYNC_TIMEOUT", 240),
         requestedRttMs: Math.floor(readEnvNumber("BENCH_COUCHDB_RTT_MS", 50)),
         passphrase: readEnvString("BENCH_PASSPHRASE", `bench-${Date.now()}`),
         encrypt: readEnvBool("BENCH_ENCRYPT", true),
         managedCouchdb: readEnvBool("BENCH_COUCHDB_MANAGED", true),
         simulationTier: readEnvString("BENCH_SIMULATION_TIER", "1"),
-        networkProfile: readEnvString(
+        networkProfile: readEnvString("BENCH_NETWORK_PROFILE", "http-latency-proxy"),
-            "BENCH_NETWORK_PROFILE",
-            "http-latency-proxy",
-        ),
         networkModel: readEnvString("BENCH_NETWORK_MODEL", "local-http-proxy"),
         measurementScope: readEnvString(
             "BENCH_MEASUREMENT_SCOPE",
-            "Two one-shot synchronisation phases through a CouchDB-compatible remote-store path.",
+            "Two one-shot synchronisation phases through a CouchDB-compatible remote-store path."
         ),
         limitations: readEnvStringArray("BENCH_LIMITATIONS_JSON", [
             "This benchmark result is scoped to the configured dataset, remote store, and network model.",
         ]),
-        verificationMode: parseBenchmarkVerificationMode(
+        verificationMode: parseBenchmarkVerificationMode(Deno.env.get("BENCH_VERIFY_MODE")),
-            Deno.env.get("BENCH_VERIFY_MODE"),
-        ),
         repeatIndex: Math.floor(readEnvNumber("BENCH_REPEAT_INDEX", 1)),
         repeatCount: Math.floor(readEnvNumber("BENCH_REPEAT_COUNT", 1)),
     };
@@ -193,20 +155,17 @@ export type CouchdbProxyHandle = {
     directionalDelayMs: number;
 };
 
-export function startCouchdbProxy(
+export function startCouchdbProxy(options: {
-    options: {
     backendUri: string;
     proxyUri: string;
     requestedRttMs: number;
     delay?: (milliseconds: number) => Promise<void>;
-    },
+}): CouchdbProxyHandle {
-): CouchdbProxyHandle {
     const backend = new URL(options.backendUri);
     const proxy = new URL(options.proxyUri);
     const halfDelayMs = options.requestedRttMs / 2;
-    const delay = options.delay ??
+    const delay =
-        ((milliseconds: number) =>
+        options.delay ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
-            new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
     const controller = new AbortController();
 
     const listener = Deno.serve(
@@ -256,14 +215,13 @@ export function startCouchdbProxy(
                 statusText: upstream.statusText,
                 headers: responseHeaders,
             });
-        },
+        }
     );
 
     return {
         applied: true,
         directionalDelayMs: halfDelayMs,
-        note:
+        note: `local reverse proxy on ${proxy.origin} with ${halfDelayMs}ms request-path and ${halfDelayMs}ms response-path delay`,
-            `local reverse proxy on ${proxy.origin} with ${halfDelayMs}ms request-path and ${halfDelayMs}ms response-path delay`,
         stop: async () => {
             controller.abort();
             await listener.finished.catch(() => {});
@@ -287,21 +245,14 @@ async function main(): Promise<void> {
     await initSettingsFile(settingsB);
 
     if (config.managedCouchdb) {
-        await startCouchdb(
+        await startCouchdb(config.couchdbBackendUri, config.couchdbUser, config.couchdbPassword, config.couchdbDbname);
-            config.couchdbBackendUri,
-            config.couchdbUser,
-            config.couchdbPassword,
-            config.couchdbDbname,
-        );
     } else {
-        console.log(
+        console.log(`[INFO] using externally managed CouchDB: ${config.couchdbBackendUri}`);
-            `[INFO] using externally managed CouchDB: ${config.couchdbBackendUri}`,
-        );
         await createCouchdbDatabase(
             config.couchdbBackendUri,
             config.couchdbUser,
             config.couchdbPassword,
-            config.couchdbDbname,
+            config.couchdbDbname
         );
     }
 
@@ -356,28 +307,15 @@ async function main(): Promise<void> {
         await runCliOrFail(vaultB, "--settings", settingsB, "sync");
         const syncBElapsed = nowMs() - syncBStart;
 
-        const verification = await verifyBenchmarkDataset(
+        const verification = await verifyBenchmarkDataset(seedFiles.entries, config.verificationMode, async (entry) => {
-            seedFiles.entries,
+            const pulledPath = workDir.join(`pulled-${entry.relativePath.split("/").join("_")}`);
-            config.verificationMode,
+            await runCliOrFail(vaultB, "--settings", settingsB, "pull", entry.relativePath, pulledPath);
-            async (entry) => {
-                const pulledPath = workDir.join(
-                    `pulled-${entry.relativePath.split("/").join("_")}`,
-                );
-                await runCliOrFail(
-                    vaultB,
-                    "--settings",
-                    settingsB,
-                    "pull",
-                    entry.relativePath,
-                    pulledPath,
-                );
             await assertFilesEqual(
                 entry.absolutePath,
                 pulledPath,
-                    `file mismatch after CouchDB sync: ${entry.relativePath}`,
+                `file mismatch after CouchDB sync: ${entry.relativePath}`
-                );
-            },
             );
+        });
 
         const result = {
             caseName: config.caseName,
@@ -409,40 +347,24 @@ async function main(): Promise<void> {
             mirrorElapsedMs: Number(mirrorElapsed.toFixed(1)),
             syncAElapsedMs: Number(syncAElapsed.toFixed(1)),
             syncBElapsedMs: Number(syncBElapsed.toFixed(1)),
-            totalSyncElapsedMs: Number(
+            totalSyncElapsedMs: Number((syncAElapsed + syncBElapsed).toFixed(1)),
-                (syncAElapsed + syncBElapsed).toFixed(1),
+            throughputBytesPerSec: Number((seedFiles.totalBytes / ((syncAElapsed + syncBElapsed) / 1000)).toFixed(2)),
-            ),
-            throughputBytesPerSec: Number(
-                (seedFiles.totalBytes / ((syncAElapsed + syncBElapsed) / 1000))
-                    .toFixed(
-                        2,
-                    ),
-            ),
             throughputMiBPerSec: Number(
-                (seedFiles.totalBytes / ((syncAElapsed + syncBElapsed) / 1000) /
+                (seedFiles.totalBytes / ((syncAElapsed + syncBElapsed) / 1000) / 1024 / 1024).toFixed(4)
-                    1024 /
-                    1024).toFixed(4),
             ),
         };
 
         if (resultPath) {
-            await Deno.writeTextFile(
+            await Deno.writeTextFile(resultPath, JSON.stringify(result, null, 2));
-                resultPath,
-                JSON.stringify(result, null, 2),
-            );
         }
 
         console.log(JSON.stringify(result, null, 2));
         console.error(
-            `[Benchmark] couchdb mirrored ${seedFiles.totalFiles} files (${
+            `[Benchmark] couchdb mirrored ${seedFiles.totalFiles} files (${formatBytes(
-                formatBytes(seedFiles.totalBytes)
+                seedFiles.totalBytes
-            }) in ${
+            )}) in ${formatMs(mirrorElapsed)}, synced in ${formatMs(
-                formatMs(
+                syncAElapsed + syncBElapsed
-                    mirrorElapsed,
+            )} (${result.throughputBytesPerSec} B/s, ${result.throughputMiBPerSec} MiB/s)`
-                )
-            }, synced in ${
-                formatMs(syncAElapsed + syncBElapsed)
-            } (${result.throughputBytesPerSec} B/s, ${result.throughputMiBPerSec} MiB/s)`,
         );
     } finally {
         await proxy.stop();

src/apps/cli/testdeno/bench-latency-sweep.ts

@@ -65,9 +65,7 @@ async function runBenchmark(options: {
     repeatIndex: number;
     repeatCount: number;
 }): Promise<Record<string, unknown>> {
-    const suffix = options.repeatCount > 1
+    const suffix = options.repeatCount > 1 ? `-r${String(options.repeatIndex).padStart(2, "0")}` : "";
-        ? `-r${String(options.repeatIndex).padStart(2, "0")}`
-        : "";
     const resultPath = `${options.outputDir}/${options.name}${suffix}.json`;
     const env = {
         ...Deno.env.toObject(),
@@ -156,8 +154,7 @@ async function main(): Promise<void> {
     const summary = {
         generatedAt: new Date().toISOString(),
         outputDir,
-        note:
+        note: "This sweep applies half of each requested CouchDB RTT before forwarding requests and half before returning responses. It is not a full netem model of jitter, loss, MTU, bandwidth, or VPN encapsulation.",
-            "This sweep applies half of each requested CouchDB RTT before forwarding requests and half before returning responses. It is not a full netem model of jitter, loss, MTU, bandwidth, or VPN encapsulation.",
         rtts,
         repeatCount,
         results,

src/apps/cli/testdeno/bench-network-cases.ts

@@ -27,26 +27,16 @@ function timestamp(): string {
     const d = new Date();
     const pad = (n: number) => String(n).padStart(2, "0");
     return (
-        `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${
+        `${d.getUTCFullYear()}${pad(d.getUTCMonth() + 1)}${pad(d.getUTCDate())}-` +
-            pad(d.getUTCDate())
+        `${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${pad(d.getUTCSeconds())}`
-        }-` +
-        `${pad(d.getUTCHours())}${pad(d.getUTCMinutes())}${
-            pad(d.getUTCSeconds())
-        }`
     );
 }
 
 function buildBaseEnv(): Record<string, string> {
     return {
         BENCH_MD_FILE_COUNT: readEnvString("BENCH_MD_FILE_COUNT", "20"),
-        BENCH_MD_MIN_SIZE_BYTES: readEnvString(
+        BENCH_MD_MIN_SIZE_BYTES: readEnvString("BENCH_MD_MIN_SIZE_BYTES", "512"),
-            "BENCH_MD_MIN_SIZE_BYTES",
+        BENCH_MD_MAX_SIZE_BYTES: readEnvString("BENCH_MD_MAX_SIZE_BYTES", "2048"),
-            "512",
-        ),
-        BENCH_MD_MAX_SIZE_BYTES: readEnvString(
-            "BENCH_MD_MAX_SIZE_BYTES",
-            "2048",
-        ),
         BENCH_BIN_FILE_COUNT: readEnvString("BENCH_BIN_FILE_COUNT", "5"),
         BENCH_BIN_SIZE_BYTES: readEnvString("BENCH_BIN_SIZE_BYTES", "8192"),
         BENCH_SYNC_TIMEOUT: readEnvString("BENCH_SYNC_TIMEOUT", "300"),
@@ -59,7 +49,7 @@ function buildBaseEnv(): Record<string, string> {
 
 function withScopeEnv(
     env: Record<string, string>,
-    options: Pick<BenchmarkCase, "measurementScope" | "limitations">,
+    options: Pick<BenchmarkCase, "measurementScope" | "limitations">
 ): Record<string, string> {
     return {
         ...env,
@@ -79,25 +69,15 @@ export function buildCases(): BenchmarkCase[] {
     const base = buildBaseEnv();
     const couchdbRtt = readEnvString("BENCH_COUCHDB_RTT_MS", "20");
     const tetheringVpnRtt = readEnvString("BENCH_TETHERING_VPN_RTT_MS", "120");
-    const localTurnServers = readEnvString(
+    const localTurnServers = readEnvString("BENCH_LOCAL_TURN_SERVERS", "turn:127.0.0.1:3478");
-        "BENCH_LOCAL_TURN_SERVERS",
+    const shimCouchdbUri = readEnvString("BENCH_SHIM_COUCHDB_URI", "http://couchdb-shim:5984");
-        "turn:127.0.0.1:3478",
+    const signallingShimRelay = readEnvString("BENCH_SIGNAL_SHIM_RELAY", "ws://p2p-signalling-shim:7777/");
-    );
-    const shimCouchdbUri = readEnvString(
-        "BENCH_SHIM_COUCHDB_URI",
-        "http://couchdb-shim:5984",
-    );
-    const signallingShimRelay = readEnvString(
-        "BENCH_SIGNAL_SHIM_RELAY",
-        "ws://p2p-signalling-shim:7777/",
-    );
 
     return [
         defineCase({
             name: "couchdb-baseline",
             runner: "couchdb",
-            description:
+            description: "Standard self-hosted CouchDB path through a local latency proxy.",
-                "Standard self-hosted CouchDB path through a local latency proxy.",
             dataPath: "Device A -> CouchDB -> Device B",
             trustBoundary: "CouchDB operator and network path",
             measurementScope:
@@ -115,8 +95,7 @@ export function buildCases(): BenchmarkCase[] {
         defineCase({
             name: "p2p-direct-local",
             runner: "p2p",
-            description:
+            description: "Preferred direct WebRTC P2P path with Nostr signalling and TURN disabled.",
-                "Preferred direct WebRTC P2P path with Nostr signalling and TURN disabled.",
             dataPath: "Device A -> Device B",
             trustBoundary: "Nostr relay for signalling metadata; no TURN relay",
             measurementScope:
@@ -133,8 +112,7 @@ export function buildCases(): BenchmarkCase[] {
                 BENCH_SIMULATION_TIER: "1",
                 BENCH_NETWORK_PROFILE: "local-direct",
                 BENCH_NETWORK_MODEL: "local-runner-webrtc",
-                BENCH_P2P_CANDIDATE_PATH_VERIFICATION:
+                BENCH_P2P_CANDIDATE_PATH_VERIFICATION: "turn-disabled-but-selected-ice-pair-not-collected",
-                    "turn-disabled-but-selected-ice-pair-not-collected",
             },
         }),
         defineCase({
@@ -142,8 +120,7 @@ export function buildCases(): BenchmarkCase[] {
             runner: "couchdb",
             description:
                 "Approximate smartphone tethering/VPN remote-database path using an HTTP latency proxy. This does not model loss, jitter, MTU, or VPN encapsulation.",
-            dataPath:
+            dataPath: "Device A -> VPN/network path -> CouchDB -> VPN/network path -> Device B",
-                "Device A -> VPN/network path -> CouchDB -> VPN/network path -> Device B",
             trustBoundary: "VPN/network path and CouchDB operator",
             measurementScope:
                 "Two one-shot CouchDB synchronisation phases with additional requested RTT through the local HTTP proxy.",
@@ -160,10 +137,8 @@ export function buildCases(): BenchmarkCase[] {
         defineCase({
             name: "couchdb-netem-home-wifi",
             runner: "couchdb",
-            description:
+            description: "Tier 2 CouchDB path through the Compose netem TCP shim using the home-wifi profile.",
-                "Tier 2 CouchDB path through the Compose netem TCP shim using the home-wifi profile.",
+            dataPath: "Device A -> netem TCP shim -> CouchDB -> netem TCP shim -> Device B",
-            dataPath:
-                "Device A -> netem TCP shim -> CouchDB -> netem TCP shim -> Device B",
             trustBoundary: "CouchDB operator and constrained network shim",
             measurementScope:
                 "Tier 2 CouchDB synchronisation through a Compose TCP shim that applies the home-wifi netem profile.",
@@ -184,12 +159,9 @@ export function buildCases(): BenchmarkCase[] {
         defineCase({
             name: "couchdb-netem-tethering-vpn",
             runner: "couchdb",
-            description:
+            description: "Tier 2 CouchDB path through the Compose netem TCP shim using a tethering-vpn profile.",
-                "Tier 2 CouchDB path through the Compose netem TCP shim using a tethering-vpn profile.",
+            dataPath: "Device A -> netem TCP shim -> CouchDB -> netem TCP shim -> Device B",
-            dataPath:
+            trustBoundary: "CouchDB operator and constrained smartphone/VPN-like network shim",
-                "Device A -> netem TCP shim -> CouchDB -> netem TCP shim -> Device B",
-            trustBoundary:
-                "CouchDB operator and constrained smartphone/VPN-like network shim",
             measurementScope:
                 "Tier 2 CouchDB synchronisation through a Compose TCP shim that applies the tethering-vpn netem profile.",
             limitations: [
@@ -211,10 +183,8 @@ export function buildCases(): BenchmarkCase[] {
             runner: "p2p",
             description:
                 "Direct P2P case name for smartphone tethering/VPN measurements. In this local runner it is unshaped and should be treated as a wiring check unless executed on that network.",
-            dataPath:
+            dataPath: "Device A -> Device B when WebRTC direct connectivity succeeds",
-                "Device A -> Device B when WebRTC direct connectivity succeeds",
+            trustBoundary: "Smartphone/VPN routing policy plus Nostr signalling metadata",
-            trustBoundary:
-                "Smartphone/VPN routing policy plus Nostr signalling metadata",
             measurementScope:
                 "Structural placeholder for direct P2P measurements on a real smartphone tethering/VPN path.",
             limitations: [
@@ -237,10 +207,8 @@ export function buildCases(): BenchmarkCase[] {
             runner: "p2p",
             description:
                 "Tier 2 P2P path with only the Nostr signalling relay accessed through the home-wifi netem shim.",
-            dataPath:
+            dataPath: "Device A -> Device B over WebRTC DataChannel; Nostr signalling through netem shim",
-                "Device A -> Device B over WebRTC DataChannel; Nostr signalling through netem shim",
+            trustBoundary: "Nostr signalling metadata through constrained network shim; no TURN relay",
-            trustBoundary:
-                "Nostr signalling metadata through constrained network shim; no TURN relay",
             measurementScope:
                 "One fresh CLI p2p-sync command where only Nostr signalling access is shaped by the home-wifi netem profile; the selected WebRTC note-data path is unshaped.",
             limitations: [
@@ -265,8 +233,7 @@ export function buildCases(): BenchmarkCase[] {
             runner: "p2p",
             description:
                 "Tier 2 P2P path with only the Nostr signalling relay accessed through the tethering-vpn netem shim.",
-            dataPath:
+            dataPath: "Device A -> Device B over WebRTC DataChannel; Nostr signalling through netem shim",
-                "Device A -> Device B over WebRTC DataChannel; Nostr signalling through netem shim",
             trustBoundary:
                 "Nostr signalling metadata through constrained smartphone/VPN-like network shim; no TURN relay",
             measurementScope:
@@ -291,8 +258,7 @@ export function buildCases(): BenchmarkCase[] {
         defineCase({
             name: "p2p-user-turn",
             runner: "p2p",
-            description:
+            description: "Optional fallback path through a local user-controlled TURN server.",
-                "Optional fallback path through a local user-controlled TURN server.",
             dataPath: "Device A -> user-controlled TURN -> Device B",
             trustBoundary: "User-controlled TURN server",
             measurementScope:
@@ -319,11 +285,9 @@ async function runCase(
     testCase: BenchmarkCase,
     outputDir: string,
     repeatIndex: number,
-    repeatCount: number,
+    repeatCount: number
 ): Promise<Record<string, unknown>> {
-    const suffix = repeatCount > 1
+    const suffix = repeatCount > 1 ? `-r${String(repeatIndex).padStart(2, "0")}` : "";
-        ? `-r${String(repeatIndex).padStart(2, "0")}`
-        : "";
     const resultPath = `${outputDir}/${testCase.name}${suffix}.json`;
     const taskName = testCase.runner === "p2p" ? "bench:p2p" : "bench:couchdb";
     const env = {
@@ -334,12 +298,8 @@ async function runCase(
         BENCH_REPEAT_COUNT: String(repeatCount),
     };
 
-    const repeatLabel = repeatCount > 1
+    const repeatLabel = repeatCount > 1 ? ` (${repeatIndex}/${repeatCount})` : "";
-        ? ` (${repeatIndex}/${repeatCount})`
+    console.log(`[bench-cases] running ${testCase.name}${repeatLabel}: ${testCase.description}`);
-        : "";
-    console.log(
-        `[bench-cases] running ${testCase.name}${repeatLabel}: ${testCase.description}`,
-    );
     const command = new Deno.Command("deno", {
         args: ["task", taskName],
         cwd: import.meta.dirname,
@@ -355,10 +315,7 @@ async function runCase(
         throw new Error(`case failed: ${testCase.name} (exit ${status.code})`);
     }
 
-    const result = JSON.parse(await Deno.readTextFile(resultPath)) as Record<
+    const result = JSON.parse(await Deno.readTextFile(resultPath)) as Record<string, unknown>;
-        string,
-        unknown
-    >;
     return {
         ...testCase,
         repeatIndex,
@@ -369,10 +326,7 @@ async function runCase(
 }
 
 function selectCases(allCases: BenchmarkCase[]): BenchmarkCase[] {
-    const requested = readEnvString(
+    const requested = readEnvString("BENCH_CASES", "couchdb-baseline,p2p-direct-local");
-        "BENCH_CASES",
-        "couchdb-baseline,p2p-direct-local",
-    );
     const names = requested
         .split(",")
         .map((v) => v.trim())
@@ -382,9 +336,7 @@ function selectCases(allCases: BenchmarkCase[]): BenchmarkCase[] {
         const found = byName.get(name);
         if (!found) {
             throw new Error(
-                `Unknown BENCH_CASES entry '${name}'. Available: ${
+                `Unknown BENCH_CASES entry '${name}'. Available: ${allCases.map((c) => c.name).join(", ")}`
-                    allCases.map((c) => c.name).join(", ")
-                }`,
             );
         }
         return found;
@@ -392,10 +344,7 @@ function selectCases(allCases: BenchmarkCase[]): BenchmarkCase[] {
 }
 
 async function main(): Promise<void> {
-    const outRoot = readEnvString(
+    const outRoot = readEnvString("BENCH_CASES_ROOT", `${import.meta.dirname}/bench-results`);
-        "BENCH_CASES_ROOT",
-        `${import.meta.dirname}/bench-results`,
-    );
     const outputDir = `${outRoot}/cases-${timestamp()}`;
     await Deno.mkdir(outputDir, { recursive: true });
 
@@ -412,16 +361,14 @@ async function main(): Promise<void> {
                 availableCases: allCases,
             },
             null,
-            2,
+            2
-        ),
+        )
     );
 
     const results: Record<string, unknown>[] = [];
     for (const testCase of cases) {
         for (let repeatIndex = 1; repeatIndex <= repeatCount; repeatIndex++) {
-            results.push(
+            results.push(await runCase(testCase, outputDir, repeatIndex, repeatCount));
-                await runCase(testCase, outputDir, repeatIndex, repeatCount),
-            );
         }
     }
 
@@ -431,10 +378,7 @@ async function main(): Promise<void> {
         repeatCount,
         results,
     };
-    await Deno.writeTextFile(
+    await Deno.writeTextFile(`${outputDir}/summary.json`, JSON.stringify(summary, null, 2));
-        `${outputDir}/summary.json`,
-        JSON.stringify(summary, null, 2),
-    );
     console.log(JSON.stringify(summary, null, 2));
     console.log(`[bench-cases] result directory: ${outputDir}`);
 }

src/apps/cli/testdeno/bench-p2p.ts

@@ -1,9 +1,5 @@
 import { TempDir } from "./helpers/temp.ts";
-import {
+import { applyP2pSettings, applyP2pTestTweaks, initSettingsFile } from "./helpers/settings.ts";
-    applyP2pSettings,
-    applyP2pTestTweaks,
-    initSettingsFile,
-} from "./helpers/settings.ts";
 import { startCliInBackground } from "./helpers/backgroundCli.ts";
 import {
     discoverPeer,
@@ -13,9 +9,7 @@ import {
     stopLocalRelayIfStarted,
 } from "./helpers/p2p.ts";
 import { assertFilesEqual, runCliOrFail } from "./helpers/cli.ts";
-import {
+import { createDeterministicDataset } from "./helpers/dataset.ts";
-    createDeterministicDataset,
-} from "./helpers/dataset.ts";
 import {
     type BenchmarkVerificationMode,
     parseBenchmarkVerificationMode,
@@ -107,10 +101,7 @@ function readEnvStringArray(name: string, fallback: string[]): string[] {
 
     try {
         const parsed = JSON.parse(raw);
-        if (
+        if (Array.isArray(parsed) && parsed.every((item) => typeof item === "string")) {
-            Array.isArray(parsed) &&
-            parsed.every((item) => typeof item === "string")
-        ) {
             return parsed;
         }
     } catch {
@@ -147,48 +138,31 @@ function buildConfig(): BenchmarkConfig {
     return {
         caseName: readEnvString("BENCH_CASE", "p2p-direct-local"),
         relay: readEnvString("BENCH_RELAY", "ws://localhost:4000/"),
-        appId: readEnvString(
+        appId: readEnvString("BENCH_APP_ID", "self-hosted-livesync-cli-benchmark"),
-            "BENCH_APP_ID",
-            "self-hosted-livesync-cli-benchmark",
-        ),
         roomId: readEnvString("BENCH_ROOM_ID", `bench-room-${Date.now()}`),
         passphrase: readEnvString("BENCH_PASSPHRASE", `bench-${Date.now()}`),
         turnServers: readEnvString("BENCH_TURN_SERVERS", ""),
         datasetDirName: readEnvString("BENCH_DATASET_DIR", "bench-dataset"),
         datasetSeed: readEnvString("BENCH_SEED", "livesync-benchmark-seed"),
         mdFileCount: Math.floor(readEnvNumber("BENCH_MD_FILE_COUNT", 1500)),
-        mdMinSizeBytes: Math.floor(
+        mdMinSizeBytes: Math.floor(readEnvNumber("BENCH_MD_MIN_SIZE_BYTES", 1024)),
-            readEnvNumber("BENCH_MD_MIN_SIZE_BYTES", 1024),
+        mdMaxSizeBytes: Math.floor(readEnvNumber("BENCH_MD_MAX_SIZE_BYTES", 20 * 1024)),
-        ),
-        mdMaxSizeBytes: Math.floor(
-            readEnvNumber("BENCH_MD_MAX_SIZE_BYTES", 20 * 1024),
-        ),
         binFileCount: Math.floor(readEnvNumber("BENCH_BIN_FILE_COUNT", 500)),
-        binSizeBytes: Math.floor(
+        binSizeBytes: Math.floor(readEnvNumber("BENCH_BIN_SIZE_BYTES", 100 * 1024)),
-            readEnvNumber("BENCH_BIN_SIZE_BYTES", 100 * 1024),
-        ),
         peersTimeoutSeconds: readEnvNumber("BENCH_PEERS_TIMEOUT", 20),
         syncTimeoutSeconds: readEnvNumber("BENCH_SYNC_TIMEOUT", 240),
         simulationTier: readEnvString("BENCH_SIMULATION_TIER", "1"),
         networkProfile: readEnvString("BENCH_NETWORK_PROFILE", "local-direct"),
-        networkModel: readEnvString(
+        networkModel: readEnvString("BENCH_NETWORK_MODEL", "local-runner-webrtc"),
-            "BENCH_NETWORK_MODEL",
+        candidatePathVerification: readEnvString("BENCH_P2P_CANDIDATE_PATH_VERIFICATION", "not-collected"),
-            "local-runner-webrtc",
-        ),
-        candidatePathVerification: readEnvString(
-            "BENCH_P2P_CANDIDATE_PATH_VERIFICATION",
-            "not-collected",
-        ),
         measurementScope: readEnvString(
             "BENCH_MEASUREMENT_SCOPE",
-            "One fresh CLI p2p-sync command, including process start-up and WebRTC connection establishment; the earlier peer-list observation command is excluded.",
+            "One fresh CLI p2p-sync command, including process start-up and WebRTC connection establishment; the earlier peer-list observation command is excluded."
         ),
         limitations: readEnvStringArray("BENCH_LIMITATIONS_JSON", [
             "This benchmark result is scoped to the configured dataset, network model, and selected ICE path.",
         ]),
-        verificationMode: parseBenchmarkVerificationMode(
+        verificationMode: parseBenchmarkVerificationMode(Deno.env.get("BENCH_VERIFY_MODE")),
-            Deno.env.get("BENCH_VERIFY_MODE"),
-        ),
         repeatIndex: Math.floor(readEnvNumber("BENCH_REPEAT_INDEX", 1)),
         repeatCount: Math.floor(readEnvNumber("BENCH_REPEAT_COUNT", 1)),
     };
@@ -202,9 +176,7 @@ function readOptionalResultPath(): string | undefined {
     return raw;
 }
 
-async function readLatestP2PConnectionStats(
+async function readLatestP2PConnectionStats(statsPath: string): Promise<P2PConnectionStats | undefined> {
-    statsPath: string,
-): Promise<P2PConnectionStats | undefined> {
     try {
         const text = await Deno.readTextFile(statsPath);
         const lines = text
@@ -252,7 +224,7 @@ async function main(): Promise<void> {
                 config.appId,
                 config.relay,
                 "~.*",
-                config.turnServers,
+                config.turnServers
             ),
             applyP2pSettings(
                 clientSettings,
@@ -261,21 +233,13 @@ async function main(): Promise<void> {
                 config.appId,
                 config.relay,
                 "~.*",
-                config.turnServers,
+                config.turnServers
             ),
         ]);
 
         await Promise.all([
-            applyP2pTestTweaks(
+            applyP2pTestTweaks(hostSettings, "p2p-bench-host", config.passphrase),
-                hostSettings,
+            applyP2pTestTweaks(clientSettings, "p2p-bench-client", config.passphrase),
-                "p2p-bench-host",
-                config.passphrase,
-            ),
-            applyP2pTestTweaks(
-                clientSettings,
-                "p2p-bench-client",
-                config.passphrase,
-            ),
         ]);
 
         const seedFiles = await createDeterministicDataset({
@@ -293,25 +257,15 @@ async function main(): Promise<void> {
         await runCliOrFail(hostVault, "--settings", hostSettings, "mirror");
         const mirrorElapsed = nowMs() - mirrorStart;
 
-        const host = startCliInBackground(
+        const host = startCliInBackground(hostVault, "--settings", hostSettings, "p2p-host");
-            hostVault,
-            "--settings",
-            hostSettings,
-            "p2p-host",
-        );
         try {
             const hostReadyStart = nowMs();
             await host.waitUntilContains("P2P host is running", 20000);
             const hostReadyElapsed = nowMs() - hostReadyStart;
 
             const peerDiscoveryCommandStart = nowMs();
-            const peer = await discoverPeer(
+            const peer = await discoverPeer(clientVault, clientSettings, config.peersTimeoutSeconds);
-                clientVault,
+            const peerDiscoveryCommandElapsed = nowMs() - peerDiscoveryCommandStart;
-                clientSettings,
-                config.peersTimeoutSeconds,
-            );
-            const peerDiscoveryCommandElapsed = nowMs() -
-                peerDiscoveryCommandStart;
 
             const syncStart = nowMs();
             await runCliOrFail(
@@ -320,7 +274,7 @@ async function main(): Promise<void> {
                 clientSettings,
                 "p2p-sync",
                 peer.id,
-                String(config.syncTimeoutSeconds),
+                String(config.syncTimeoutSeconds)
             );
             const syncElapsed = nowMs() - syncStart;
 
@@ -328,28 +282,24 @@ async function main(): Promise<void> {
                 seedFiles.entries,
                 config.verificationMode,
                 async (entry) => {
-                    const pulledPath = workDir.join(
+                    const pulledPath = workDir.join(`pulled-${entry.relativePath.replaceAll("/", "_")}`);
-                        `pulled-${entry.relativePath.replaceAll("/", "_")}`,
-                    );
                     await runCliOrFail(
                         clientVault,
                         "--settings",
                         clientSettings,
                         "pull",
                         entry.relativePath,
-                        pulledPath,
+                        pulledPath
                     );
                     await assertFilesEqual(
                         entry.absolutePath,
                         pulledPath,
-                        `file mismatch after P2P sync: ${entry.relativePath}`,
+                        `file mismatch after P2P sync: ${entry.relativePath}`
                     );
-                },
+                }
             );
 
-            const p2pConnectionStats = await readLatestP2PConnectionStats(
+            const p2pConnectionStats = await readLatestP2PConnectionStats(p2pStatsPath);
-                p2pStatsPath,
-            );
             const result = {
                 caseName: config.caseName,
                 mode: "p2p-cli-benchmark",
@@ -363,10 +313,8 @@ async function main(): Promise<void> {
                 limitations: config.limitations,
                 repeatIndex: config.repeatIndex,
                 repeatCount: config.repeatCount,
-                p2pCandidatePathVerified:
+                p2pCandidatePathVerified: p2pConnectionStats?.candidatePathCollected === true,
-                    p2pConnectionStats?.candidatePathCollected === true,
+                p2pCandidatePathVerification: p2pConnectionStats?.candidatePathCollected
-                p2pCandidatePathVerification:
-                    p2pConnectionStats?.candidatePathCollected
                     ? "selected ICE candidate pair collected from RTCPeerConnection.getStats"
                     : config.candidatePathVerification,
                 p2pCandidatePathNote: p2pConnectionStats?.candidatePathCollected
@@ -389,39 +337,25 @@ async function main(): Promise<void> {
                 mirrorElapsedMs: Number(mirrorElapsed.toFixed(1)),
                 hostReadyElapsedMs: Number(hostReadyElapsed.toFixed(1)),
                 peerDiscoveryTimeoutSeconds: config.peersTimeoutSeconds,
-                peerDiscoveryCommandElapsedMs: Number(
+                peerDiscoveryCommandElapsedMs: Number(peerDiscoveryCommandElapsed.toFixed(1)),
-                    peerDiscoveryCommandElapsed.toFixed(1),
-                ),
                 peerDiscoveryNote:
                     "p2p-peers waits for the requested timeout before printing discovered peers, so this is command duration, not first-peer latency.",
                 syncElapsedMs: Number(syncElapsed.toFixed(1)),
-                throughputBytesPerSec: Number(
+                throughputBytesPerSec: Number((seedFiles.totalBytes / (syncElapsed / 1000)).toFixed(2)),
-                    (seedFiles.totalBytes / (syncElapsed / 1000)).toFixed(2),
+                throughputMiBPerSec: Number((seedFiles.totalBytes / (syncElapsed / 1000) / 1024 / 1024).toFixed(4)),
-                ),
-                throughputMiBPerSec: Number(
-                    (seedFiles.totalBytes / (syncElapsed / 1000) / 1024 / 1024)
-                        .toFixed(
-                            4,
-                        ),
-                ),
             };
 
             if (resultPath) {
-                await Deno.writeTextFile(
+                await Deno.writeTextFile(resultPath, JSON.stringify(result, null, 2));
-                    resultPath,
-                    JSON.stringify(result, null, 2),
-                );
             }
 
             console.log(JSON.stringify(result, null, 2));
             console.error(
-                `[Benchmark] mirrored ${seedFiles.totalFiles} files (${
+                `[Benchmark] mirrored ${seedFiles.totalFiles} files (${formatBytes(
-                    formatBytes(
+                    seedFiles.totalBytes
-                        seedFiles.totalBytes,
+                )}) in ${formatMs(mirrorElapsed)}, ` +
-                    )
-                }) in ${formatMs(mirrorElapsed)}, ` +
                     `synced in ${formatMs(syncElapsed)} ` +
-                    `(${result.throughputBytesPerSec} B/s, ${result.throughputMiBPerSec} MiB/s)`,
+                    `(${result.throughputBytesPerSec} B/s, ${result.throughputMiBPerSec} MiB/s)`
             );
         } finally {
             await host.stop();

src/apps/cli/testdeno/helpers/benchmarkVerification.ts

@@ -10,9 +10,7 @@ export type BenchmarkVerificationResult = {
 };
 
 function toHex(bytes: ArrayBuffer): string {
-    return [...new Uint8Array(bytes)]
+    return [...new Uint8Array(bytes)].map((value) => value.toString(16).padStart(2, "0")).join("");
-        .map((value) => value.toString(16).padStart(2, "0"))
-        .join("");
 }
 
 async function sha256(bytes: Uint8Array): Promise<string> {
@@ -23,7 +21,7 @@ async function sha256(bytes: Uint8Array): Promise<string> {
 
 export function parseBenchmarkVerificationMode(
     raw: string | undefined,
-    fallback: BenchmarkVerificationMode = "sample",
+    fallback: BenchmarkVerificationMode = "sample"
 ): BenchmarkVerificationMode {
     const value = raw?.trim().toLowerCase();
     if (!value) return fallback;
@@ -31,10 +29,7 @@ export function parseBenchmarkVerificationMode(
     throw new Error(`BENCH_VERIFY_MODE must be 'all' or 'sample', got '${raw}'`);
 }
 
-export function selectVerificationEntries(
+export function selectVerificationEntries(entries: DatasetEntry[], mode: BenchmarkVerificationMode): DatasetEntry[] {
-    entries: DatasetEntry[],
-    mode: BenchmarkVerificationMode,
-): DatasetEntry[] {
     if (mode === "all" || entries.length === 0) return [...entries];
 
     const md = entries.find((entry) => entry.kind === "md");
@@ -48,15 +43,11 @@ export function selectVerificationEntries(
     return [...selected.values()];
 }
 
-export async function computeDatasetDigestSha256(
+export async function computeDatasetDigestSha256(entries: DatasetEntry[]): Promise<string> {
-    entries: DatasetEntry[],
-): Promise<string> {
     const manifest: string[] = [];
     for (const entry of entries) {
         const contentDigest = await sha256(await Deno.readFile(entry.absolutePath));
-        manifest.push(
+        manifest.push(`${entry.kind}\t${entry.relativePath}\t${entry.size}\t${contentDigest}`);
-            `${entry.kind}\t${entry.relativePath}\t${entry.size}\t${contentDigest}`,
-        );
     }
     return await sha256(new TextEncoder().encode(manifest.join("\n")));
 }
@@ -64,7 +55,7 @@ export async function computeDatasetDigestSha256(
 export async function verifyBenchmarkDataset(
     entries: DatasetEntry[],
     mode: BenchmarkVerificationMode,
-    verifyEntry: (entry: DatasetEntry) => Promise<void>,
+    verifyEntry: (entry: DatasetEntry) => Promise<void>
 ): Promise<BenchmarkVerificationResult> {
     const selected = selectVerificationEntries(entries, mode);
     for (const entry of selected) {

src/apps/cli/testdeno/test-benchmark-contract.ts

@@ -1,10 +1,7 @@
 import { assert, assertEquals, assertStringIncludes } from "@std/assert";
 import { type BenchmarkCase, buildCases } from "./bench-network-cases.ts";
 import { startCouchdbProxy } from "./bench-couchdb.ts";
-import {
+import { parseBenchmarkVerificationMode, selectVerificationEntries } from "./helpers/benchmarkVerification.ts";
-    parseBenchmarkVerificationMode,
-    selectVerificationEntries,
-} from "./helpers/benchmarkVerification.ts";
 import type { DatasetEntry } from "./helpers/dataset.ts";
 
 function getFreePort(): number {
@@ -24,20 +21,10 @@ function getCase(cases: BenchmarkCase[], name: string): BenchmarkCase {
 
 function parsedLimitations(testCase: BenchmarkCase): string[] {
     const raw = testCase.env.BENCH_LIMITATIONS_JSON;
-    assert(
+    assert(raw, `${testCase.name} must pass BENCH_LIMITATIONS_JSON to benchmark result output`);
-        raw,
-        `${testCase.name} must pass BENCH_LIMITATIONS_JSON to benchmark result output`,
-    );
     const parsed = JSON.parse(raw);
-    assert(
+    assert(Array.isArray(parsed), `${testCase.name} limitations must be an array`);
-        Array.isArray(parsed),
+    assert(parsed.every((item) => typeof item === "string" && item.trim().length > 0));
-        `${testCase.name} limitations must be an array`,
-    );
-    assert(
-        parsed.every((item) =>
-            typeof item === "string" && item.trim().length > 0
-        ),
-    );
     return parsed;
 }
 
@@ -46,36 +33,14 @@ Deno.test("benchmark cases record scope and limitations for paper use", () => {
     assert(cases.length > 0);
 
     for (const testCase of cases) {
-        assert(
+        assert(testCase.description.trim().length > 0, `${testCase.name} must describe the case`);
-            testCase.description.trim().length > 0,
+        assert(testCase.dataPath.trim().length > 0, `${testCase.name} must describe the data path`);
-            `${testCase.name} must describe the case`,
+        assert(testCase.trustBoundary.trim().length > 0, `${testCase.name} must describe the trust boundary`);
-        );
+        assert(testCase.measurementScope.trim().length > 0, `${testCase.name} must describe the measurement scope`);
-        assert(
+        assert(testCase.limitations.length > 0, `${testCase.name} must list limitations`);
-            testCase.dataPath.trim().length > 0,
+        assertEquals(testCase.env.BENCH_MEASUREMENT_SCOPE, testCase.measurementScope);
-            `${testCase.name} must describe the data path`,
-        );
-        assert(
-            testCase.trustBoundary.trim().length > 0,
-            `${testCase.name} must describe the trust boundary`,
-        );
-        assert(
-            testCase.measurementScope.trim().length > 0,
-            `${testCase.name} must describe the measurement scope`,
-        );
-        assert(
-            testCase.limitations.length > 0,
-            `${testCase.name} must list limitations`,
-        );
-        assertEquals(
-            testCase.env.BENCH_MEASUREMENT_SCOPE,
-            testCase.measurementScope,
-        );
         assertEquals(parsedLimitations(testCase), testCase.limitations);
-        assertEquals(
+        assertEquals(testCase.env.BENCH_VERIFY_MODE, "all", `${testCase.name} must verify the complete dataset`);
-            testCase.env.BENCH_VERIFY_MODE,
-            "all",
-            `${testCase.name} must verify the complete dataset`,
-        );
     }
 });
 
@@ -89,7 +54,7 @@ Deno.test("CouchDB latency proxy applies half the requested RTT in each directio
             port: backendPort,
             onListen() {},
         },
-        () => new Response("ok"),
+        () => new Response("ok")
     );
     const proxy = startCouchdbProxy({
         backendUri: `http://127.0.0.1:${backendPort}`,
@@ -143,34 +108,22 @@ Deno.test("benchmark verification mode selects either all files or a labelled sa
 
 Deno.test("P2P signalling-shim cases do not claim to shape the note-data path", () => {
     const cases = buildCases();
-    for (
+    for (const name of ["p2p-signalling-netem-home-wifi", "p2p-signalling-netem-tethering-vpn"]) {
-        const name of [
-            "p2p-signalling-netem-home-wifi",
-            "p2p-signalling-netem-tethering-vpn",
-        ]
-    ) {
         const testCase = getCase(cases, name);
         assertEquals(testCase.runner, "p2p");
         assertEquals(testCase.env.BENCH_TURN_SERVERS, "");
         assertEquals(testCase.env.BENCH_SIMULATION_TIER, "2");
-        assertEquals(
+        assertEquals(testCase.env.BENCH_NETWORK_MODEL, "compose-netem-signalling-shim");
-            testCase.env.BENCH_NETWORK_MODEL,
-            "compose-netem-signalling-shim",
-        );
         assertStringIncludes(testCase.dataPath, "WebRTC DataChannel");
         assertStringIncludes(testCase.dataPath, "Nostr signalling");
         assertStringIncludes(testCase.measurementScope, "fresh CLI p2p-sync");
         assert(
-            testCase.limitations.some((limitation) =>
+            testCase.limitations.some((limitation) => limitation.includes("connection establishment")),
-                limitation.includes("connection establishment")
+            `${name} must state that connection establishment is timed`
-            ),
-            `${name} must state that connection establishment is timed`,
         );
         assert(
-            testCase.limitations.some((limitation) =>
+            testCase.limitations.some((limitation) => limitation.includes("does not shape the selected WebRTC")),
-                limitation.includes("does not shape the selected WebRTC")
+            `${name} must avoid claiming that the P2P note-data path was shaped`
-            ),
-            `${name} must avoid claiming that the P2P note-data path was shaped`,
         );
     }
 });
@@ -182,42 +135,31 @@ Deno.test("placeholder and TURN cases are clearly non-evidence for broad P2P per
     assertEquals(smartphone.env.BENCH_SIMULATION_TIER, "unmeasured");
     assertEquals(smartphone.env.BENCH_NETWORK_MODEL, "local-runner-no-netem");
     assert(
-        smartphone.limitations.some((limitation) =>
+        smartphone.limitations.some((limitation) => limitation.includes("must not be reported as smartphone")),
-            limitation.includes("must not be reported as smartphone")
+        "smartphone/VPN placeholder must not be usable as field evidence by accident"
-        ),
-        "smartphone/VPN placeholder must not be usable as field evidence by accident",
     );
 
     const turn = getCase(cases, "p2p-user-turn");
     assertStringIncludes(turn.env.BENCH_TURN_SERVERS, "turn:");
     assert(
         turn.limitations.some((limitation) =>
-            limitation.includes(
+            limitation.includes("does not prove that the selected ICE path was relayed")
-                "does not prove that the selected ICE path was relayed",
-            )
         ),
-        "TURN case must require selected ICE candidate interpretation",
+        "TURN case must require selected ICE candidate interpretation"
     );
 });
 
 Deno.test("CouchDB netem cases are marked as remote-store baselines", () => {
     const cases = buildCases();
-    for (
+    for (const name of ["couchdb-netem-home-wifi", "couchdb-netem-tethering-vpn"]) {
-        const name of ["couchdb-netem-home-wifi", "couchdb-netem-tethering-vpn"]
-    ) {
         const testCase = getCase(cases, name);
         assertEquals(testCase.runner, "couchdb");
         assertEquals(testCase.env.BENCH_SIMULATION_TIER, "2");
-        assertEquals(
+        assertEquals(testCase.env.BENCH_NETWORK_MODEL, "compose-netem-tcp-shim");
-            testCase.env.BENCH_NETWORK_MODEL,
-            "compose-netem-tcp-shim",
-        );
         assertStringIncludes(testCase.measurementScope, "CouchDB");
         assert(
-            testCase.limitations.some((limitation) =>
+            testCase.limitations.some((limitation) => limitation.includes("not the WebRTC P2P data path")),
-                limitation.includes("not the WebRTC P2P data path")
+            `${name} must remain scoped to the CouchDB remote-store path`
-            ),
-            `${name} must remain scoped to the CouchDB remote-store path`,
         );
     }
 });

utils/release-notes.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync } from "fs";
+import { readFileSync, writeFileSync, writeSync } from "fs";
 
 const updatesPath = "updates.md";
 
@@ -8,7 +8,7 @@ const updatesPath = "updates.md";
 // allowed.
 
 function fail(message) {
-    console.error(message);
+    writeSync(process.stderr.fd, `${message}\n`);
     process.exit(1);
 }
 

utils/release-process.unit.spec.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { ensureTags } from "./release-tags.mjs";
 
 const releaseNotesScript = fileURLToPath(new URL("./release-notes.mjs", import.meta.url));
 const versionBumpScript =
@@ -11,6 +12,7 @@ const versionBumpScript =
 const workspaceUpdateScript = fileURLToPath(new URL("../update-workspaces.mjs", import.meta.url));
 const prepareReleaseWorkflow = fileURLToPath(new URL("../.github/workflows/prepare-release.yml", import.meta.url));
 const finaliseReleaseWorkflow = fileURLToPath(new URL("../.github/workflows/finalise-release.yml", import.meta.url));
+const releaseWorkflow = fileURLToPath(new URL("../.github/workflows/release.yml", import.meta.url));
 const temporaryDirectories: string[] = [];
 
 afterEach(() => {
@@ -39,6 +41,28 @@ function runNode(script: string, args: string[], cwd: string, env: Record<string
     });
 }
 
+function createTagGit(expectedRevision: string, initialTags: Record<string, string> = {}) {
+    const tags = new Map(Object.entries(initialTags));
+    const git = (args: string[], allowMissing = false): string | undefined => {
+        if (args[0] === "rev-parse") {
+            const revision = args.at(-1);
+            if (revision === `${expectedRevision}^{commit}`) return expectedRevision;
+            const tagMatch = revision?.match(/^refs\/tags\/(.+)\^\{commit\}$/);
+            if (tagMatch) {
+                const commit = tags.get(tagMatch[1]);
+                if (commit !== undefined) return commit;
+                if (allowMissing) return undefined;
+            }
+        }
+        if (args[0] === "tag" && args.length === 3) {
+            tags.set(args[1], args[2]);
+            return "";
+        }
+        throw new Error(`Unexpected git command: ${args.join(" ")}`);
+    };
+    return { git, tags };
+}
+
 function createReleaseFixture(version = "0.25.81"): string {
     const directory = makeTemporaryDirectory();
     writeJson(directory, "package.json", { version });
@@ -137,10 +161,50 @@ describe("release workflow", () => {
         const workflow = readFileSync(finaliseReleaseWorkflow, "utf8");
 
         expect(workflow).toContain("actions: write");
+        expect(workflow).toContain('node utils/release-tags.mjs ensure "${VERSION}" "${EXPECTED_HEAD_SHA}"');
+        expect(workflow).toContain('git push --atomic origin "refs/tags/${VERSION}" "refs/tags/${VERSION}-cli"');
+        expect(workflow).not.toContain("Tag already exists");
         expect(workflow).toContain("gh workflow run release.yml");
         expect(workflow).toContain("gh workflow run cli-docker.yml");
         expect(workflow).toContain("dry_run=false");
     });
+
+    it("publishes only by explicit dispatch and validates the selected release", () => {
+        const workflow = readFileSync(releaseWorkflow, "utf8");
+
+        expect(workflow).not.toMatch(/^\s+push:/m);
+        expect(workflow).toContain("ref: ${{ inputs.tag }}");
+        expect(workflow).toContain('node utils/release-notes.mjs validate "${TAG}"');
+        expect(workflow).toContain('TAG_SHA="$(git rev-parse "refs/tags/${TAG}^{commit}")"');
+        expect(workflow).not.toContain("Get Version");
+    });
+});
+
+describe("release tags", () => {
+    it("creates missing tags and accepts matching tags on retry", () => {
+        const head = "a".repeat(40);
+        const { git, tags } = createTagGit(head);
+        const messages: string[] = [];
+
+        ensureTags("0.25.84", head, git, (message) => messages.push(message));
+        expect(tags.get("0.25.84")).toBe(head);
+        expect(tags.get("0.25.84-cli")).toBe(head);
+
+        ensureTags("0.25.84", head, git, (message) => messages.push(message));
+        expect(messages).toContain(`Tag 0.25.84 already points to the expected commit ${head}.`);
+        expect(messages).toContain(`Tag 0.25.84-cli already points to the expected commit ${head}.`);
+    });
+
+    it("rejects an existing release tag that points to another commit without creating missing tags", () => {
+        const previousHead = "b".repeat(40);
+        const expectedHead = "a".repeat(40);
+        const { git, tags } = createTagGit(expectedHead, { "0.25.84-cli": previousHead });
+
+        expect(() => ensureTags("0.25.84", expectedHead, git)).toThrow(
+            `Tag 0.25.84-cli points to ${previousHead}; expected ${expectedHead}.`
+        );
+        expect(tags.has("0.25.84")).toBe(false);
+    });
 });
 
 describe("version bump", () => {

utils/release-tags.mjs

@@ -0,0 +1,73 @@
+import { spawnSync } from "node:child_process";
+import { writeSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+function fail(message) {
+    writeSync(process.stderr.fd, `${message}\n`);
+    process.exit(1);
+}
+
+function assertVersion(version) {
+    if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`Invalid release version: ${version}`);
+    }
+}
+
+function git(args, allowMissing = false) {
+    const result = spawnSync("git", args, { encoding: "utf8" });
+    if (allowMissing && result.status === 1 && result.stdout === "" && result.stderr === "") {
+        return undefined;
+    }
+    if (result.error) {
+        throw new Error(`Could not run git ${args.join(" ")}: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new Error(result.stderr.trim() || `git ${args.join(" ")} exited with status ${result.status}.`);
+    }
+    return result.stdout.trim();
+}
+
+function resolveCommit(revision, runGit) {
+    return runGit(["rev-parse", "--verify", `${revision}^{commit}`]);
+}
+
+function resolveTag(tag, runGit) {
+    return runGit(["rev-parse", "--verify", "--quiet", `refs/tags/${tag}^{commit}`], true);
+}
+
+export function ensureTags(version, expectedRevision, runGit = git, log = console.log) {
+    assertVersion(version);
+    const expectedCommit = resolveCommit(expectedRevision, runGit);
+    const tags = [version, `${version}-cli`];
+    const existing = tags.map((tag) => ({ tag, commit: resolveTag(tag, runGit) }));
+
+    for (const { tag, commit } of existing) {
+        if (commit !== undefined && commit !== expectedCommit) {
+            throw new Error(`Tag ${tag} points to ${commit}; expected ${expectedCommit}.`);
+        }
+    }
+
+    for (const { tag, commit } of existing) {
+        if (commit === undefined) {
+            runGit(["tag", tag, expectedCommit]);
+            log(`Created tag ${tag} at ${expectedCommit}.`);
+        } else {
+            log(`Tag ${tag} already points to the expected commit ${expectedCommit}.`);
+        }
+    }
+}
+
+const isMain = process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
+if (isMain) {
+    const [command, version, expectedRevision] = process.argv.slice(2);
+    if (command !== "ensure" || !version || !expectedRevision) {
+        fail("Usage: node utils/release-tags.mjs ensure <version> <expected-commit>");
+    }
+
+    try {
+        ensureTags(version, expectedRevision);
+    } catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+}