optbrew 0.1.3 → 0.2.0

package/skills/optbrew/scripts/core/keys.mjs

@@ -0,0 +1,86 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ENV_NAME = 'OPTBREW_GOOGLE_API_KEY';
+const HASH_CHARS = 8;
+const OWNER_ONLY_FILE = 0o600;
+const OWNER_ONLY_DIR = 0o700;
+
+/** The home folder the key file lives in: USERPROFILE on Windows, HOME elsewhere, then the OS answer. Never a site or output folder. */
+export function keyHome(env = process.env, platform = process.platform) {
+  return (platform === 'win32' ? env?.USERPROFILE : env?.HOME) || os.homedir();
+}
+
+const credentialsPath = home => path.join(home, '.optbrew', 'credentials.json');
+
+const clean = value => typeof value === 'string' && value.trim() ? value.trim() : null;
+
+/**
+ * The key file as a plain object for code that rewrites it. A missing file is empty; an unreadable, corrupt or
+ * non-object file is refused, so a hand-edited file with a typo is never overwritten or deleted. The error names
+ * the path only, never the file's contents.
+ */
+function loadCredentials(file) {
+  let value;
+  try { value = JSON.parse(readFileSync(file, 'utf8')); }
+  catch (error) { if (error.code === 'ENOENT') return {}; value = null; }
+  if (!value || typeof value !== 'object' || Array.isArray(value))
+    throw new Error(`credentials file at ${file} is not a valid JSON object; fix it or delete it, then run the command again`);
+  return value;
+}
+
+/** The same file for readers: anything unusable means "no key". */
+function readCredentials(file) {
+  try { return loadCredentials(file); } catch { return {}; }
+}
+
+/** Environment variable first, then the key file. An empty variable, a missing file or a corrupt file all mean "no key". */
+export function readGoogleKey({ env = process.env, home = keyHome(env) } = {}) {
+  return clean(env?.[ENV_NAME]) ?? clean(readCredentials(credentialsPath(home)).google);
+}
+
+/**
+ * Presence and the first 8 hex characters of the SHA-256; the key value itself is never returned. A key file that exists but is
+ * not a JSON object adds `corrupt: true` (the file is only read, never changed), so the user is told to fix it instead of
+ * being told there is no key.
+ */
+export function googleKeyStatus({ env = process.env, home = keyHome(env) } = {}) {
+  const key = readGoogleKey({ env, home });
+  let corrupt = false;
+  try { loadCredentials(credentialsPath(home)); } catch { corrupt = true; }
+  return { google: { present: key !== null, sha256_8: key === null ? null : createHash('sha256').update(key).digest('hex').slice(0, HASH_CHARS), ...(corrupt ? { corrupt: true } : {}) } };
+}
+
+/** Replace the key file atomically (temp file, then rename) so a reader never sees a half-written file. */
+async function writeCredentials(file, credentials) {
+  const temp = `${file}.${process.pid}.tmp`;
+  await mkdir(path.dirname(file), { recursive: true, mode: OWNER_ONLY_DIR });
+  try {
+    await writeFile(temp, `${JSON.stringify(credentials)}\n`, { flag: 'wx', mode: OWNER_ONLY_FILE });
+    // Windows has no POSIX modes (chmod only toggles read-only there); the home folder's own ACL protects the file.
+    if (process.platform !== 'win32') {
+      await chmod(path.dirname(file), OWNER_ONLY_DIR);
+      await chmod(temp, OWNER_ONLY_FILE);
+    }
+    await rename(temp, file);
+  } finally { await rm(temp, { force: true }); }
+}
+
+/** Store the key and keep every other entry already in the file. */
+export async function saveGoogleKey({ home = keyHome(), key }) {
+  const file = credentialsPath(home);
+  await writeCredentials(file, { ...loadCredentials(file), google: key });
+}
+
+/** Drop only the google entry; the file itself goes away once nothing else is left in it. Returns whether an entry existed. */
+export async function removeGoogleKey({ home = keyHome() } = {}) {
+  const file = credentialsPath(home);
+  const { google, ...rest } = loadCredentials(file);
+  if (google === undefined) return false;
+  if (Object.keys(rest).length) await writeCredentials(file, rest);
+  else await rm(file, { force: true });
+  return true;
+}

package/skills/optbrew/scripts/core/link-graph.mjs

@@ -0,0 +1,93 @@
+import { anchorLinks, decodeEntities } from './html.mjs';
+
+/** Link and sitemap target comparison key: no fragment, and a directory index file equals its directory. */
+export function canonicalUrl(value) {
+  try {
+    const url = new URL(value); url.hash = '';
+    url.pathname = url.pathname.replace(/\/index\.(?:html?|php)$/i, '/');
+    return url.href;
+  } catch { return null; }
+}
+
+/** The distinct links of `hrefs` that stay on the origin of `base`, absolute and without fragments, sorted. */
+export function sameOriginLinks(hrefs, base) {
+  const { origin } = new URL(base);
+  const found = new Set();
+  for (const href of hrefs) {
+    let url;
+    try { url = new URL(href, base); } catch { continue; }
+    url.hash = '';
+    if (url.origin === origin) found.add(url.href);
+  }
+  return [...found].sort();
+}
+
+/**
+ * The anchor links between collected HTML pages. `rows` are `{ url, artifact, html }` for every collected page with a 200
+ * raw HTML body, selected or not. `edges` lists `{ from, to }` canonical urls (a page's link to itself is not an edge).
+ * `depthOf(url)` is the click distance from the home page, `inbound(url)` the number of links into a page.
+ * `scriptGap` is true when a page that has scripts and no anchors loads a same-origin script file that was not collected:
+ * its navigation cannot be read, so a missing link proves nothing.
+ */
+export function linkGraph(rows, artifacts) {
+  const collected = new Set(artifacts.flatMap(x => [x.normalized_url, x.final_url].filter(Boolean).map(canonicalUrl)));
+  const edges = [];
+  let scriptGap = false;
+  for (const { artifact, html } of rows) {
+    const hrefs = anchorLinks(html, artifact.final_url);
+    if (!hrefs.length && /<script\b/i.test(html)) {
+      for (const match of html.matchAll(/<script\b[^>]*\bsrc\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) {
+        try {
+          const source = new URL(decodeEntities(match[1] ?? match[2]), artifact.final_url);
+          if (source.origin === new URL(artifact.final_url).origin && !collected.has(canonicalUrl(source.href))) scriptGap = true;
+        } catch { /* malformed script URL */ }
+      }
+    }
+    const from = canonicalUrl(artifact.normalized_url);
+    for (const href of hrefs) {
+      const to = canonicalUrl(href);
+      if (to && to !== canonicalUrl(artifact.final_url) && to !== from) edges.push({ from, to });
+    }
+  }
+  const next = new Map();
+  for (const { from, to } of edges) next.set(from, [...next.get(from) ?? [], to]);
+  const home = rows.find(row => new URL(row.artifact.final_url).pathname === '/') ?? rows[0];
+  const depth = new Map(home ? [[canonicalUrl(home.url), 0]] : []);
+  for (const page of depth.keys()) for (const to of next.get(page) ?? []) if (!depth.has(to)) depth.set(to, depth.get(page) + 1);
+  return {
+    edges, scriptGap,
+    depthOf: url => depth.get(canonicalUrl(url)) ?? null,
+    inbound: url => edges.filter(edge => edge.to === canonicalUrl(url)).length,
+  };
+}
+
+/** True when any other collected page's raw bytes name this page's path (whole path segment, not a longer path). */
+function pathMentioned({ url, artifact }, rows) {
+  const own = canonicalUrl(url);
+  for (const target of new Set([url, artifact.final_url])) {
+    let path;
+    try { path = decodeURIComponent(new URL(target).pathname); } catch { continue; }
+    if (path === '/') continue;
+    const pattern = new RegExp(path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + '(?![A-Za-z0-9_-])');
+    for (const page of rows) if (canonicalUrl(page.url) !== own && pattern.test(page.html)) return true;
+  }
+  return false;
+}
+
+/**
+ * Selected pages that nothing links to and no declared sitemap lists, when the evidence is complete enough to say so.
+ * An unlinked page stays undecided when another page's own bytes (inline scripts included) name its path, or when a
+ * script file that could build the link was not collected, unless a fetched sitemap that lists other pages leaves it out.
+ * No page is an orphan when the crawl was cut short, fewer than two pages were collected, or the sitemap is an index
+ * whose child sitemaps were not fetched, or a declared sitemap was never fetched.
+ */
+export function findOrphans({ pageRows, rows, graph, sitemaps, complete }) {
+  const orphans = new Set();
+  if (rows.length < 2 || !complete || sitemaps.index || sitemaps.unread.length) return orphans;
+  for (const row of pageRows) {
+    const keys = [canonicalUrl(row.url), canonicalUrl(row.artifact.final_url)];
+    if (keys.some(key => sitemaps.urls.has(key) || graph.inbound(key))) continue;
+    if (sitemaps.urls.size || !(graph.scriptGap || pathMentioned(row, rows))) orphans.add(row.url);
+  }
+  return orphans;
+}

package/skills/optbrew/scripts/core/messages.mjs

@@ -0,0 +1,23 @@
+import { messagesKo } from './config.mjs';
+
+/** `{name}` takes the value as it is; `{name:table}` looks the value up as `table.<value>` in the catalog (a word the value stands for). */
+const PLACEHOLDER = /\{(\w+)(?::([\w-]+))?\}/g;
+const UNKNOWN_WORD = 'word.unknown';
+
+/** `{ message_key, message_values }`: what a check records beside its English message so the report can say it in Korean. */
+export const messageOf = (message_key, message_values = {}) => ({ message_key, message_values });
+
+/**
+ * The Korean sentence for a message key with its page-specific values filled in; `fallback` (the English text) when the key is
+ * absent or has no entry. Values stay as they are: the renderer escapes them for its format. A missing value reads as the unknown word.
+ */
+export function koText(key, values = {}, fallback = null) {
+  const catalog = messagesKo();
+  const template = key ? catalog[key] : undefined;
+  if (typeof template !== 'string') return fallback;
+  return template.replace(PLACEHOLDER, (_, name, table) => {
+    const value = values?.[name];
+    if (value === undefined || value === null || value === '') return catalog[UNKNOWN_WORD];
+    return table ? catalog[`${table}.${value}`] ?? String(value) : String(value);
+  });
+}

package/skills/optbrew/scripts/core/metrics.mjs

@@ -1,15 +1,17 @@
 import { ContractError, validateEntity } from './contracts.mjs';
+import { versions } from './config.mjs';
 
 function ratio(id, numerator, denominator, definition, panel, selection, evaluable = true) {
   const measured = evaluable && denominator > 0;
-  const observation = { schema_version: '1.0.0', metric_id: id,
+  const observation = { schema_version: versions().contract_schema, metric_id: id,
     value_state: measured ? 'measured' : 'unknown', value: measured ? numerator / denominator : null,
     numerator: measured ? numerator : null, denominator: measured ? denominator : null,
     definition, filters: { engine: panel.engine, surface: panel.surface, model: panel.model,
       search_enabled: panel.search_enabled, locale: panel.locale, region: panel.region,
       ...(panel.collected_at ? { collected_at: panel.collected_at } : {}),
       ...(panel.last_complete_date ? { last_complete_date: panel.last_complete_date } : {}) },
-    window: panel.window, panel_hash: panel.panel_hash, provider_definition: 'optbrew fixed AI response panel v0.1.0',
+    // The panel is a measurement definition, so its label is the evaluation version.
+    window: panel.window, panel_hash: panel.panel_hash, provider_definition: `optbrew fixed AI response panel v${versions().evaluation}`,
     sample_selection: selection, source_ref: panel.source_ref, evidence_ref: panel.evidence_ref };
   return validateEntity('MetricObservation', observation);
 }

package/skills/optbrew/scripts/core/migration.mjs

@@ -0,0 +1,37 @@
+import { ContractError } from './contracts.mjs';
+import { versions } from './config.mjs';
+
+/** Evidence an older optbrew made: one plain sentence that says what is old and what to do. */
+export class MigrationRequired extends ContractError {
+  constructor(what, detail) {
+    super(`migration_required: this ${what} ${detail}; run the audit again with optbrew ${versions().release} in a new output folder`);
+  }
+}
+
+const numbers = version => typeof version === 'string' && /^\d+\.\d+\.\d+$/.test(version) ? version.split('.').map(Number) : null;
+
+function isOlder(found, current) {
+  const left = numbers(found), right = numbers(current);
+  if (!left || !right) return false;
+  const at = left.findIndex((part, i) => part !== right[i]);
+  return at !== -1 && left[at] < right[at];
+}
+
+/**
+ * The first version label of an input (a ScoreInput, a ReportPacket or a RunContext) that is older than the one this release
+ * uses, as `{ name, found }`; null when none is. The protocol is named first because it is what a comparison reports.
+ */
+export function olderVersion(input) {
+  const context = input?.run_context ?? input;
+  const now = versions();
+  const checks = [['audit protocol', context?.protocol_version, now.protocol], ['evaluation', context?.evaluation_version, now.evaluation],
+    ['contract', input?.schema_version, now.contract_schema], ['contract', context?.schema_version, now.contract_schema]];
+  const hit = checks.find(([, found, current]) => isOlder(found, current));
+  return hit ? { name: hit[0], found: hit[1] } : null;
+}
+
+/** Refuse evidence an older optbrew made, in one sentence, before any schema check can turn it into a stack trace. */
+export function assertCurrentEvidence(input, what) {
+  const older = olderVersion(input);
+  if (older) throw new MigrationRequired(what, `comes from an older optbrew (${older.name} ${older.found})`);
+}

package/skills/optbrew/scripts/core/page-select.mjs

@@ -0,0 +1,136 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { links } from './collector.mjs';
+import { limits } from './config.mjs';
+import { decodeEntities } from './html.mjs';
+import { assertUrlInScope } from './scope.mjs';
+
+const START_FILE = path.join('preflight', 'start.json');
+const EVIDENCE_INDEX = path.join('preflight', 'evidence', 'evidence-index.json');
+/** Robots and sitemap files are auxiliary resources of the protocol, never audited pages. */
+const AUXILIARY_PATH = /\/(?:robots\.txt|sitemap[^/]*\.xml)$/i;
+// A sitemap is an XML document whose root element is <urlset> or <sitemapindex>: before the root only a byte order mark, white
+// space, the XML declaration, other processing instructions (Yoast's stylesheet) and comments may stand. An HTML page that shows
+// sample sitemap XML in its text or a script is a page, never a sitemap. Each instruction and comment ends at its first
+// closing mark, so the prolog has one reading and the match stays linear on a body with many leading comments.
+const SITEMAP_ROOT = /^?(?:\s|<\?(?:[^?]|\?(?!>))*\?>|<!--(?:[^-]|-(?!->))*-->)*<(urlset|sitemapindex)\b/i;
+// Files a sitemap or a link may name that are not pages to audit.
+const NOT_A_PAGE = /\.(?:pdf|jpe?g|png|gif|webp|svg|ico|zip|xml|txt|css|js|json|mp4|mp3)$/i;
+const KOREAN_PAGE = /<html\b[^>]*\blang\s*=\s*["']?ko/i;
+const LOC = /<loc>\s*([^<\s]+)\s*<\/loc>/gi;
+const HOME_TYPE = 'home';
+const TOP_LEVEL_TYPE = 'pages';
+const TYPE_NAME_LENGTH = 40;
+
+const readJson = async file => { try { return JSON.parse(await readFile(file, 'utf8')); } catch { return null; } };
+
+/** The same site under the other spelling of its name: with or without `www.`, over http or https. */
+export const sameSite = (a, b) => a.hostname.replace(/^www\./, '') === b.hostname.replace(/^www\./, '') && a.port === b.port;
+
+/**
+ * What the unscored read before the start questions (`preflight/` in `out`) left behind, if anything: the address the first
+ * request landed on (or the other site it was sent to), whether the start page declares Korean, the page addresses of every
+ * sitemap file it fetched and the links of the start page. A sitemap is any fetched body whose XML root is `<urlset>` or
+ * `<sitemapindex>`, whatever its file name (Yoast and WordPress name their children `page-sitemap.xml`, `wp-sitemap-posts-page-1.xml`). Bodies are used only when
+ * they still match the hash the preflight index lists. `status` says what was there: `missing` (no preflight in this folder),
+ * `read`, or `unreadable` (a preflight exists but none of its evidence could be used). A preflight made for another address is
+ * not this run's and counts as missing.
+ */
+export async function readPreflight(out, startHref) {
+  const start = await readJson(path.join(out, START_FILE));
+  const index = await readJson(path.join(out, EVIDENCE_INDEX));
+  const found = { status: 'missing', requestedUrl: null, finalUrl: null, redirectedTo: null, korean: false, sitemapLocs: [], pageLinks: [], sitemapFiles: [] };
+  if (!start && !index) return found;
+  if (start?.requested_url && !sameSite(new URL(start.requested_url), new URL(startHref))) return found;
+  found.status = 'unreadable';
+  found.requestedUrl = start?.requested_url ?? null;
+  found.finalUrl = start?.final_url ?? null;
+  found.redirectedTo = start?.redirected_to ?? null;
+  if (start?.sitemap_final_url) found.sitemapFiles.push(start.sitemap_final_url);
+  for (const entry of index?.raw ?? []) {
+    let text;
+    try {
+      const bytes = await readFile(entry.evidence_ref);
+      if (createHash('sha256').update(bytes).digest('hex') !== entry.content_hash) continue;
+      text = bytes.toString('utf8');
+    } catch { continue; }
+    found.status = 'read';
+    const root = SITEMAP_ROOT.exec(text)?.[1].toLowerCase();
+    if (root) found.sitemapFiles.push(entry.normalized_url);
+    if (root === 'urlset') for (const match of text.matchAll(LOC)) found.sitemapLocs.push(decodeEntities(match[1]));
+    else if (!root && (entry.normalized_url === startHref || entry.normalized_url === found.finalUrl)) {
+      found.korean = KOREAN_PAGE.test(text);
+      found.pageLinks = links(text, found.finalUrl ?? startHref);
+    }
+  }
+  return found;
+}
+
+/**
+ * How many pages the selection may take within the request `limit`, with `declared` auxiliary resources (robots, sitemaps) fetched
+ * first. A redirect hop is a request the page count does not see, so a margin of `redirect_reserve` (a share of the pages, at least
+ * a minimum) stays free: a redirect then cannot push a selected page or a declared resource out of the limit. One page is always left while the limit has room for one.
+ */
+export function pageBudget(limit, declared) {
+  const { share, min } = limits().redirect_reserve;
+  const room = Math.max(0, limit - declared);
+  let pages = room;
+  while (pages > 1 && pages + Math.max(min, Math.ceil(pages * share)) > room) pages--;
+  return pages;
+}
+
+/**
+ * The pages one audit covers, fixed before the first request: the start page, the pages the owner confirmed facts on, then the
+ * sitemap's pages in the order it lists them, then the start page's own links. Every address must be inside `scope`; a file that
+ * is not a page, a duplicate, an `auxiliary` resource (robots, a sitemap file), or anything past `budget` is left out. A fact page
+ * that is left out is reported back in `dropped`.
+ */
+export function selectPages({ home, factUrls, preflight, scope, budget, auxiliary }) {
+  const chosen = [];
+  const declared = new Set(auxiliary);
+  const seen = new Set();
+  const dropped = [];
+  // A fact page listed twice is reported once.
+  const drop = (url, reason) => { if (!dropped.some(entry => entry.url === url && entry.reason === reason)) dropped.push({ url, reason }); };
+  const add = (href, owner) => {
+    let normalized;
+    try { normalized = assertUrlInScope(href, scope).href; }
+    catch { if (owner) drop(href, 'outside_scope'); return; }
+    const { pathname } = new URL(normalized);
+    // A declared sitemap or robots file is an auxiliary resource, never a page; a fact page that names one is reported, not lost.
+    const reason = declared.has(normalized) || AUXILIARY_PATH.test(pathname) ? 'auxiliary_resource' : NOT_A_PAGE.test(pathname) ? 'not_a_page' : null;
+    if (reason) { if (owner) drop(href, reason); return; }
+    if (seen.has(normalized)) return;
+    if (chosen.length >= budget) { if (owner) drop(href, 'over_limit'); return; }
+    seen.add(normalized);
+    chosen.push(normalized);
+  };
+  add(home, true);
+  for (const href of factUrls) add(href, true);
+  const before = chosen.length;
+  for (const href of preflight.sitemapLocs) add(href, false);
+  const fromSitemap = chosen.length - before;
+  for (const href of preflight.pageLinks) add(href, false);
+  return { pages: chosen, dropped, sources: { preflight: preflight.status, sitemap_pages: fromSitemap, linked_pages: chosen.length - before - fromSitemap } };
+}
+
+/** The type of a page: `home` for the start page, the first path segment for a page inside a section, `pages` for the other top-level pages. */
+function typeOf(href, home) {
+  if (href === home) return HOME_TYPE;
+  const segments = new URL(href).pathname.split('/').filter(Boolean);
+  if (segments.length < 2) return TOP_LEVEL_TYPE;
+  let name = segments[0];
+  try { name = decodeURIComponent(name); } catch { /* an undecodable segment names its type as written */ }
+  return name.slice(0, TYPE_NAME_LENGTH);
+}
+
+/** Page types in the order their first page appears; the same pages always give the same types. */
+export function groupPages(pages, home) {
+  const types = new Map();
+  for (const href of pages) {
+    const id = typeOf(href, home);
+    types.set(id, [...(types.get(id) ?? []), href]);
+  }
+  return [...types].map(([id, urls]) => ({ id, urls }));
+}

package/skills/optbrew/scripts/core/probe.mjs

@@ -0,0 +1,83 @@
+import { harnessSignals } from './config.mjs';
+import { urlTarget } from './scope.mjs';
+
+const OTHER = 'other';
+
+/**
+ * Which `harness:` values in the runbook front matter apply to each probe harness. This is the one place the two
+ * vocabularies meet: `local` runbooks serve both local hosts, `any` serves everyone, and an unknown host (which may be a
+ * local one that sets no signal, such as Codex with full network) gets `any` and `local` (R43).
+ */
+const RUNBOOK_HARNESSES = {
+  'claude-code': ['local', 'any'],
+  codex: ['local', 'codex', 'any'],
+  'claude-code-cloud': ['claude-code-cloud', 'any'],
+  [OTHER]: ['any', 'local'],
+};
+
+/** The runbook that saves a Google key for each probe harness (beside RUNBOOK_HARNESSES, the other place the two vocabularies meet). */
+const KEY_SET_RUNBOOKS = { 'claude-code': 'key-set-local', codex: 'key-set-codex', 'claude-code-cloud': 'key-set-claude-cloud', [OTHER]: 'key-set-local' };
+
+export function keySetRunbook(harness) {
+  const id = KEY_SET_RUNBOOKS[harness];
+  if (!id) throw new Error(`unknown harness: ${harness}`);
+  return id;
+}
+
+export function runbookHarnesses(harness) {
+  const values = RUNBOOK_HARNESSES[harness];
+  if (!values) throw new Error(`unknown harness: ${harness}`);
+  return values;
+}
+
+const isSet = (env, names) => names.some(name => typeof env?.[name] === 'string' && env[name] !== '');
+
+/** The first harness in `harness-signals.json` (file order) with a signal variable set; no signal means `other`. */
+const detectHarness = env => Object.keys(harnessSignals()).find(harness => isSet(env, harnessSignals()[harness].env_any)) ?? OTHER;
+
+/**
+ * Why the site cannot be reached, from the harness. A host that cut its own network (Codex sandbox with the
+ * network-disabled variable, Claude Code cloud network level) is told apart from a site that is simply down.
+ */
+function blockReason(harness, env) {
+  if (harness === 'claude-code-cloud') return 'cloud_network_level';
+  if (harness === 'codex' && isSet(env, harnessSignals().codex.network_blocked_env_any ?? [])) return 'codex_sandbox';
+  return 'site_down';
+}
+
+const proxyFailure = error => typeof error?.code === 'string' && error.code.startsWith('proxy_');
+/** The request was refused by the scope rules (another site, a private address): that says nothing about the site being down. */
+const scopeRejection = error => ['scope_rejected', 'redirect_outside_scope'].includes(error?.code);
+
+/**
+ * The start probe: harness, how the site is reached, Chrome, key presence and source tools. Everything is injected so a
+ * test needs no network or Chrome. `selectTransport` takes `{ env, probeHost }`. `reach(selected)`, when given, does a
+ * real first request; a proxy that refuses it is a network block, a scope rejection is no block at all, any other
+ * failure is the site. A `selectTransport` error other than a DNS failure is thrown on purpose: the CLI then fails
+ * with exit 2. The proxy is recorded as host and port only, and the key is recorded as present or absent, never by value.
+ */
+export async function probeEnvironment({ env = process.env, url, selectTransport, findChrome, readGoogleKey, home, sourceTools = [], reach = null }) {
+  const harness = detectHarness(env);
+  let selected = null;
+  let failure = null;
+  try { selected = await selectTransport({ env, probeHost: urlTarget(new URL(url)).host }); }
+  catch (error) { if (error?.code !== 'dns_unresolvable') throw error; failure = error; }
+  if (selected && reach) {
+    try { await reach(selected); } catch (error) { if (!scopeRejection(error)) failure = error; }
+  }
+  let block = null;
+  if (failure) block = !selected || proxyFailure(failure) ? blockReason(harness, env) : 'site_down';
+  const chrome = await findChrome({ env });
+  const found = Boolean(chrome?.path);
+  return {
+    harness,
+    transport: selected ? (selected.proxy ? 'proxy' : 'direct') : null,
+    address_vetting: selected?.address_vetting ?? null,
+    proxy: selected?.proxy ? { host: selected.proxy.host, port: selected.proxy.port } : null,
+    block_reason: block,
+    chrome: { found, kind: found ? chrome.kind : null, reason: found ? null : chrome?.reason ?? 'chrome_not_found' },
+    google_key: (await readGoogleKey({ env, home })) !== null,
+    source_tools: [...new Set(sourceTools.map(tool => tool.trim()).filter(Boolean))],
+    sitemap_pages: null,
+  };
+}

package/skills/optbrew/scripts/core/protocol.mjs

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { ContractError, validateEntity, validateApplicabilityDecision } from './contracts.mjs';
 import { assertUrlInScope } from './scope.mjs';
+import { limits, publicOnlyFamily, requestLimit } from './config.mjs';
 
 const registry = JSON.parse(readFileSync(new URL('../../references/check-registry.json', import.meta.url)));
 const knownFamilies = new Map(registry.families.map(x => [x.family_id, x]));
@@ -12,6 +13,27 @@ function unique(values, label) {
 }
 
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+
+/**
+ * Whether the run's own fixed conditions decide a family's applicability, and the condition code that names the reason when it is not
+ * applicable; null when no fixed condition decides it (the owner's or the model's decision then stands). Read from the registry, never from
+ * a list of family names: no inapplicable condition at all means always applicable; `public_only` plus `no_public_index_target` follows the
+ * public index targets (and the target engines, where `no_target_engine` is also a condition); an engine-bound family with a `*_not_target`
+ * condition follows its engines; `no_fixed_questions` follows the question panel. A test holds the registry flag and this rule together (T22 S2).
+ */
+function fixedApplicability(definition, protocol, publicCount) {
+  const conditions = definition.na_conditions ?? [];
+  if (!conditions.length) return { applicable: true, condition: null };
+  if (conditions.includes('no_fixed_questions')) return { applicable: protocol.question_panel.length > 0, condition: 'no_fixed_questions' };
+  if (definition.public_only === true && conditions.includes('no_public_index_target')) {
+    const needsEngine = conditions.includes('no_target_engine');
+    return { applicable: publicCount > 0 && (!needsEngine || protocol.engines.length > 0),
+      condition: needsEngine && !protocol.engines.length ? 'no_target_engine' : 'no_public_index_target' };
+  }
+  const engineCondition = conditions.find(code => code.endsWith('_not_target'));
+  if (definition.engines?.length && engineCondition) return { applicable: definition.engines.some(engine => protocol.engines.includes(engine)), condition: engineCondition };
+  return null;
+}
 const sameSet = (a, b) => a.length === b.length && a.every(value => b.includes(value));
 
 function stable(value) {
@@ -35,11 +57,16 @@ export function freezeProtocol(context) {
   const urls = p.page_types.flatMap(x => x.urls.map(u => u.normalized));
   unique(urls, 'normalized URLs');
   if (!urls.length) throw new ContractError('protocol requires selected public audit URLs');
+  const { render } = p;
+  unique(render.pages.map(x => x.normalized), 'render pages');
+  if (render.pages.length > limits().render_pages) throw new ContractError('render pages exceed the render page limit');
+  if (render.pages.some(x => !urls.includes(x.normalized))) throw new ContractError('render page is not a selected URL');
+  if (!Number.isInteger(render.max_render_requests) || render.max_render_requests > limits().max_render_requests)
+    throw new ContractError('render request limit is not a whole number within the render ceiling');
   const resources = p.auxiliary_resources ?? [];
   unique(resources.map(x => x.normalized), 'auxiliary resources');
   if (resources.some(x => urls.includes(x.normalized))) throw new ContractError('auxiliary resource duplicates a selected URL');
-  const requestLimit = Math.min(context.scope.max_urls ?? 50, 50);
-  if (urls.length + resources.length > requestLimit) throw new ContractError('selected pages and auxiliary resources exceed request scope');
+  if (urls.length + resources.length > requestLimit(context.scope)) throw new ContractError('selected pages and auxiliary resources exceed request scope');
   for (const resource of resources) {
     for (const url of [resource.original, resource.normalized]) {
       try { assertUrlInScope(url, context.scope); }
@@ -66,7 +93,7 @@ export function freezeProtocol(context) {
   for (const family of p.families) {
     const definition = knownFamilies.get(family.family_id);
     if (!definition) throw new ContractError(`unregistered family: ${family.family_id}`);
-    const requiredUrls = ['index-policy', 'search-crawl-policy', 'discovery'].includes(family.family_id) ? publicUrls : urls;
+    const requiredUrls = publicOnlyFamily(family.family_id) ? publicUrls : urls;
     if (family.urls) {
       unique(family.urls, `${family.family_id}.urls`);
       if (definition.unit_scope === 'site' || !sameSet(family.urls, requiredUrls))
@@ -78,23 +105,18 @@ export function freezeProtocol(context) {
       if (definition.unit_scope !== 'engine_url' || !sameSet(family.engines, requiredEngines))
         throw new ContractError(`${family.family_id}: target engine units cannot be omitted`);
     }
-    const expected = family.family_id === 'fetch-response' ? true :
-      ['index-policy', 'discovery'].includes(family.family_id) ? publicUrls.length > 0 :
-      family.family_id === 'search-crawl-policy' ? publicUrls.length > 0 && p.engines.length > 0 :
-      family.family_id === 'question-coverage' ? p.question_panel.length > 0 :
-      family.family_id === 'naver-markup' ? p.engines.includes('naver') : null;
-    if (expected !== null && family.applicable !== expected)
+    // A family that only matters for indexed pages has no unit when every selected page is a non-index target.
+    if (publicOnlyFamily(family.family_id) && family.applicable && !publicUrls.length)
+      throw new ContractError(`${family.family_id}: applicable family has no public index target`);
+    const fixed = fixedApplicability(definition, p, publicUrls.length);
+    if (fixed && family.applicable !== fixed.applicable)
       throw new ContractError(`${family.family_id}: applicability contradicts fixed URL/engine conditions`);
     if (family.applicable) {
       if (family.applicability_decision) throw new ContractError(`${family.family_id}: decision only allowed when inapplicable`);
     } else {
       const decision = validateApplicabilityDecision(family.applicability_decision,
         definition.na_conditions, `${family.family_id}.applicability_decision`);
-      const automaticCondition = family.family_id === 'search-crawl-policy' ?
-        (p.engines.length ? 'no_public_index_target' : 'no_target_engine') :
-        ['index-policy', 'discovery'].includes(family.family_id) ? 'no_public_index_target' :
-        family.family_id === 'question-coverage' ? 'no_fixed_questions' :
-        family.family_id === 'naver-markup' ? 'naver_not_target' : null;
+      const automaticCondition = fixed?.condition ?? null;
       if (automaticCondition && decision.condition !== automaticCondition)
         throw new ContractError(`${family.family_id}: decision conflicts with fixed conditions`);
     }
@@ -103,6 +125,7 @@ export function freezeProtocol(context) {
   }
   const sorted = { ...p,
     ...(p.auxiliary_resources ? { auxiliary_resources: [...resources].sort((a, b) => compare(a.normalized, b.normalized)) } : {}),
+    render: { ...render, pages: [...render.pages].sort((a, b) => compare(a.normalized, b.normalized)) },
     engines: [...p.engines].sort(),
     families: [...p.families].sort((a, b) => compare(a.family_id, b.family_id)).map(f => ({ ...f,
       ...(f.urls ? { urls: [...f.urls].sort() } : {}),
@@ -115,6 +138,7 @@ export function freezeProtocol(context) {
   const hashInput = structuredClone(protocol);
   for (const type of hashInput.page_types) for (const url of type.urls) if (url.indexing_decision)
     url.indexing_decision = { condition: url.indexing_decision.condition };
+  for (const url of hashInput.render.pages) if (url.indexing_decision) url.indexing_decision = { condition: url.indexing_decision.condition };
   for (const family of hashInput.families) if (family.applicability_decision)
     family.applicability_decision = { condition: family.applicability_decision.condition };
   if (hashInput.target_identity) {