Report a covered API in browser-shared code as a warning

src/core/lib is imported by the browser-side YAML intelligence, so it cannot import src/deno_ral/platform.ts (it probes Deno in a try block instead). A new Deno.build.os there got the blocking error with a deno_ral hint that cannot compile in that code, and --accept-increase cannot clear a finding. Findings under src/core/lib/ now use the uncovered warning text.

Author: cderv

dev-docs/runtime-migration/02c-ratchet-pr-delta-and-guidance.md

@@ -439,3 +439,9 @@ Run from the branch worktree; `Q` is `package/dist/bin/quarto` (`quarto.cmd` on
 - Fix: delta mode passes `renderDelta` the baseline committed at the `--against` revision, read by the new exported `baselineAt` (`git cat-file -e` to detect an absent file, fallback to the working-tree baseline for a revision from before the ratchet; a malformed baseline exits 2). New export, not in the plan: needed to unit-test the logic with a real temp git repository. After: probe PR prints no notice, V3 still prints `main is above … (tests Deno.* calls 832 > 826)`, `unit/tools/check-runtime-boundary.test.ts` → 36 passed.
 - Correction to the earlier note on the `execProcess` decoder: counts are not always unaffected. A corrupted path from `git diff --name-only` or the untracked list fails both the `ls-tree` membership check and the disk read, so the file contributes nothing and a covered increase in it would be missed silently; only a corrupted `ls-tree` entry over-reports. Still 0 tracked non-ASCII paths, and the fix stays a separate bug on main (backported to v1.10).
 - Open, needs a decision: a covered `Deno.build.os` added under `src/core/lib/` (browser-shared: the YAML-intelligence web worker imports it, so it cannot import `src/deno_ral/platform.ts`) gets a blocking error with a hint that cannot compile there. PR 19 plans a runtime-neutral probe for the two existing uses (`errors.ts`, `colors.ts`).
+
+### 2026-10-22: browser-shared code
+
+- Decided with Chris: option "path list, warning only". `diffChanges` no longer attaches a replacement (so no error) to a finding under `kBrowserSharedPaths` (`src/core/lib/`, the code the YAML-intelligence web worker imports, which cannot import `src/deno_ral/`); it falls under the uncovered warning text. The constant is module-private (no new export); PR 19 removes the two existing `Deno.*` uses there.
+- Test `a covered API in browser-shared code is a warning, not an error` failed before the change (assertion: the finding carried the `build.os` replacement) and passes after; `unit/tools/check-runtime-boundary.test.ts` → 37 passed. Counts unchanged (994/49, 7/0, 10/1, 240/3, 832/177).
+- `_TEMPLATE.md` gets one sentence on `kBrowserSharedPaths` next to the map rule. Deviation from the plan's file list: the constant and template sentence were not in the plan.

dev-docs/runtime-migration/_TEMPLATE.md

@@ -84,7 +84,7 @@ Repository conventions that plans must respect (`.claude/CLAUDE.md` and `.claude
 - Unit tests live in `tests/unit/` (runtime-layer tests under the existing `tests/unit/ral/`), use `unitTest` from `tests/test.ts` and assertions from `tests/asserts.ts` (added by PR 02), and run with `cd tests && QUARTO_TESTS_NO_CONFIG=true ./run-tests.sh --agent unit/<file>.test.ts`.
   The ratchet (PR 02) has a `tests` scope: tests written by PRs 09 and later use `deno_ral` `fs`/`temp`/`process`, never raw `Deno.*`.
 - Landing order inside Phase 1: 02 → 02b → 08 → 22 → 10–13 → 14, with 09 before 10; 22 depends on PR 04 (Phase 0). 02c lands before any other count-changing PR.
-- A PR that adds an equivalent `deno_ral` replacement for a `Deno.*` API adds its exact keys (e.g. `readTextFileSync`) to `kRalDenoReplacements` in `tools/check-runtime-boundary.ts` in the same change, which turns later increases of that API into errors; a PR that adds a std seam may add a `kStdSuggestions` entry (suggestions never fail a PR).
+- A PR that adds an equivalent `deno_ral` replacement for a `Deno.*` API adds its exact keys (e.g. `readTextFileSync`) to `kRalDenoReplacements` in `tools/check-runtime-boundary.ts` in the same change, which turns later increases of that API into errors; a PR that adds a std seam may add a `kStdSuggestions` entry (suggestions never fail a PR). Under `kBrowserSharedPaths` (`src/core/lib/`, which the browser-side YAML intelligence imports and which therefore cannot import `deno_ral`) a covered API is only a warning.
   A conflict in a codemod PR is resolved by resetting the file to `main` and re-running the codemod, never by hand (the codemod is idempotent, PR 09); a conflict on a shared file (`tools/runtime-boundary-baseline.json`, `deno.lock`, the shim, the `deno-ral.md` table, a changelog) follows README ground rule 8.
 - Commands in the plans write the Linux path `package/dist/bin/tools/x86_64/deno`; on Apple Silicon it is `tools/aarch64/deno`, on Windows `tools\x86_64\deno.exe`.
 - Size is by file count (S < 10, M 10–40, L > 40 files); a plan that is large by volume but small by files says so next to the letter.

tests/unit/tools/check-runtime-boundary.test.ts

@@ -660,3 +660,18 @@ unitTest("check-runtime-boundary - baselineAt reads the baseline committed at th
     temp.cleanup();
   }
 });
+
+// deno-lint-ignore require-await
+unitTest("check-runtime-boundary - a covered API in browser-shared code is a warning, not an error", async () => {
+  const report = diffChanges([
+    { path: "src/core/lib/errors.ts", before: "", after: `export const o = ${DENO}build.os;\n`, addedLines: [1] },
+    { path: "src/core/other.ts", before: "", after: `export const o = ${DENO}build.os;\n`, addedLines: [1] },
+  ]);
+  const byFile = Object.fromEntries(report.findings.map((f) => [f.file, f]));
+  assertEquals(byFile["src/core/lib/errors.ts"].replacement, undefined);
+  assertEquals(byFile["src/core/other.ts"].replacement, kRalDenoReplacements["build.os"].hint);
+
+  const rendered = renderDelta(report, { "src": { denoCalls: 996, stdImportFiles: 49 } }, { "src": { denoCalls: 994, stdImportFiles: 49 } });
+  assertEquals(rendered.errors.map((e) => e.file), ["src/core/other.ts"]);
+  assertEquals(rendered.warnings.map((w) => w.file), ["src/core/lib/errors.ts"]);
+});

tools/check-runtime-boundary.ts

@@ -316,6 +316,13 @@ export const kStdSuggestions: Readonly<
   "assert": { module: "tests/asserts.ts", scopes: ["tests"] },
 };
 
+/** Code that also runs in the browser (the YAML intelligence web worker imports it), so it cannot
+ * import src/deno_ral/: a covered API there is only ever a warning. */
+const kBrowserSharedPaths: readonly string[] = ["src/core/lib/"];
+
+const isBrowserShared = (path: string) =>
+  kBrowserSharedPaths.some((prefix) => path.startsWith(prefix));
+
 export function denoReplacement(api: string, scope: string): string | undefined {
   const entry = Object.hasOwn(kRalDenoReplacements, api)
     ? kRalDenoReplacements[api]
@@ -419,7 +426,9 @@ export function diffChanges(changes: FileChange[]): DeltaReport {
           };
           const line = firstAddedLine(e.change, "Deno." + api);
           if (line !== undefined) finding.line = line;
-          const replacement = denoReplacement(api, scope);
+          const replacement = isBrowserShared(e.change.path)
+            ? undefined
+            : denoReplacement(api, scope);
           if (replacement !== undefined) finding.replacement = replacement;
           findings.push(finding);
         }