optbrew 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,31 @@
+/** Resample whole question clusters, keeping repetitions dependent. */
+export function clusterBootstrap({ questionIds, valuesByQuestion, seed, iterations = 2000, confidence = 0.95 }) {
+  if (!Array.isArray(questionIds) || !questionIds.length || new Set(questionIds).size !== questionIds.length ||
+      !Number.isInteger(seed) || !Number.isInteger(iterations) || iterations < 1 || !(confidence > 0 && confidence < 1))
+    throw new TypeError('invalid cluster bootstrap parameters');
+  const clusters = questionIds.map(id => {
+    const values = valuesByQuestion?.[id];
+    if (!Array.isArray(values) || !values.length || values.some(x => !Number.isFinite(x)))
+      throw new TypeError(`invalid values for question ${id}`);
+    return values;
+  });
+  let state = seed >>> 0;
+  const random = () => ((state = (1664525 * state + 1013904223) >>> 0) / 2 ** 32);
+  const draws = [];
+  for (let iteration = 0; iteration < iterations; iteration++) {
+    let sum = 0, count = 0;
+    for (let i = 0; i < clusters.length; i++) {
+      const cluster = clusters[Math.floor(random() * clusters.length)];
+      for (const value of cluster) { sum += value; count++; }
+    }
+    draws.push(sum / count);
+  }
+  draws.sort((a, b) => a - b);
+  const tail = (1 - confidence) / 2;
+  const quantile = p => {
+    const x = p * (draws.length - 1), lo = Math.floor(x), hi = Math.ceil(x);
+    return draws[lo] + (draws[hi] - draws[lo]) * (x - lo);
+  };
+  return { interval: [quantile(tail), quantile(1 - tail)], method: 'question_cluster_percentile',
+    seed, iterations, unique_questions: questionIds.length };
+}

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

@@ -0,0 +1,73 @@
+import { createHash } from 'node:crypto';
+import { readFile, readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const manifestName = 'bundle-manifest.json';
+export const evaluationSourcePaths = ['references/check-registry.json', 'references/profiles.json',
+  'references/scoring.md', 'references/measurement.md', 'scripts/core/score.mjs', 'scripts/core/weights.mjs',
+  'scripts/core/contracts.mjs', 'scripts/core/compare.mjs', 'scripts/core/metrics.mjs', 'scripts/core/bootstrap.mjs'];
+export const protocolSourcePaths = ['references/schemas/contract.schema.json', 'scripts/core/protocol.mjs'];
+
+/** Match the package.json skill exclusions for generated Python cache files. */
+export function isDistributedBundlePath(relative) {
+  const parts = relative.split(/[\\/]/);
+  return !parts.some(part => ['__pycache__', 'tests', 'evals'].includes(part) || part.startsWith('_백업_원본_')) &&
+    !relative.endsWith('.pyc') && !/^test_.*\.py$/.test(parts.at(-1));
+}
+
+async function listFiles(root, relative = '') {
+  const result = [];
+  for (const entry of await readdir(path.join(root, relative), { withFileTypes: true })) {
+    const name = relative ? `${relative}/${entry.name}` : entry.name;
+    if (name === manifestName) continue;
+    if (!isDistributedBundlePath(name)) continue;
+    if (entry.isDirectory()) result.push(...await listFiles(root, name));
+    else if (entry.isFile()) result.push(name);
+    else throw new Error(`bundle contains link or special file: ${name}`);
+  }
+  return result.sort();
+}
+
+/** Hash every distributed file; the manifest never hashes itself. */
+export async function createBundleManifest({ bundleRoot, releaseVersion }) {
+  if (!/^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(releaseVersion)) throw new Error('invalid release version');
+  const files = [];
+  for (const name of await listFiles(bundleRoot)) {
+    files.push({ path: name, sha256: digest(await readFile(path.join(bundleRoot, name))) });
+  }
+  // Synthetic install fixtures contain only SKILL.md; production release checks completeness.
+  const selected = paths => paths.every(name => files.some(file => file.path === name))
+    ? paths.map(name => files.find(file => file.path === name)) : [];
+  const evaluation_sources = selected(evaluationSourcePaths);
+  const protocol_sources = selected(protocolSourcePaths);
+  const identity = evaluation_sources.length && protocol_sources.length ? {
+    evaluation_version: '0.1.0', protocol_version: '0.1.0',
+    evaluation_sources, evaluation_hash: digest(JSON.stringify(evaluation_sources)),
+    protocol_sources, protocol_hash: digest(JSON.stringify(protocol_sources)) } : {};
+  return { schema_version: '1.0.0', release_version: releaseVersion,
+    ...identity, files, bundle_hash: digest(JSON.stringify(files)) };
+}
+
+/** Verify the exact allowlist, byte hashes, and aggregate hash. */
+export async function verifyBundle({ bundleRoot, manifest }) {
+  const errors = [];
+  let actual;
+  try { actual = await createBundleManifest({ bundleRoot, releaseVersion: manifest?.release_version }); }
+  catch (error) { return { status: 'invalid', checked_files: 0, errors: [{ path: '', code: error.message }], bundle_hash: null }; }
+  if (!Array.isArray(manifest?.files) || manifest.schema_version !== '1.0.0') errors.push({ path: manifestName, code: 'invalid_manifest' });
+  const expected = new Map(Array.isArray(manifest?.files) ? manifest.files.map(f => [f.path, f.sha256]) : []);
+  const found = new Map(actual.files.map(f => [f.path, f.sha256]));
+  if (expected.size !== manifest?.files?.length) errors.push({ path: manifestName, code: 'duplicate_path' });
+  for (const [name, sha] of found) {
+    if (!expected.has(name)) errors.push({ path: name, code: 'unexpected_file' });
+    else if (expected.get(name) !== sha) errors.push({ path: name, code: 'hash_mismatch' });
+  }
+  for (const name of expected.keys()) if (!found.has(name)) errors.push({ path: name, code: 'missing_file' });
+  if (manifest?.bundle_hash !== actual.bundle_hash ||
+      JSON.stringify(manifest?.files) !== JSON.stringify(actual.files)) errors.push({ path: manifestName, code: 'bundle_hash_mismatch' });
+  for (const field of ['evaluation_version', 'protocol_version', 'evaluation_sources', 'protocol_sources', 'evaluation_hash', 'protocol_hash'])
+    if (JSON.stringify(manifest?.[field]) !== JSON.stringify(actual[field]))
+      errors.push({ path: manifestName, code: field.endsWith('_version') ? 'migration_required' : `${field}_mismatch` });
+  return { status: errors.length ? 'invalid' : 'valid', checked_files: actual.files.length, errors, bundle_hash: actual.bundle_hash };
+}

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

@@ -0,0 +1,19 @@
+/** Match actual evidence surfaces to requested checks without inventing missing capability. */
+export function selectCapabilities(available, requirements) {
+  const selected = []; const missing = []; const limitations = [];
+  for (const requirement of requirements) {
+    const names = requirement === 'structured_data' ? ['raw_html'] : [requirement];
+    const candidate = available.find(item => names.includes(item.capability) && item.bounded === true &&
+      ['code', 'host_policy', 'none'].includes(item.cost_enforcement));
+    if (!candidate || (requirement === 'bulk_crawl' && candidate.cost_enforcement !== 'code')) {
+      missing.push(requirement);
+      if (requirement === 'bulk_crawl' && available.some(item => item.capability === 'bulk_crawl'))
+        limitations.push('bulk_crawl: boundary or cost enforcement is host_policy/unverified');
+      continue;
+    }
+    selected.push({ capability: candidate.capability, provider: candidate.provider, tool_ref: candidate.tool_ref,
+      cost_enforcement: candidate.cost_enforcement });
+    if (candidate.cost_enforcement === 'host_policy') limitations.push(`${candidate.provider}: host_policy cannot enforce paid cost in code`);
+  }
+  return { selected, missing, limitations };
+}

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

@@ -0,0 +1,236 @@
+import { lookup } from 'node:dns/promises';
+import { createHash } from 'node:crypto';
+import http from 'node:http';
+import https from 'node:https';
+import { isIP } from 'node:net';
+import { performance } from 'node:perf_hooks';
+import { assertInScope, assertUrlInScope } from './scope.mjs';
+
+const HEADER_NAMES = ['content-type', 'content-length', 'content-range', 'content-encoding', 'location', 'x-robots-tag', 'last-modified', 'etag'];
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const text = value => Buffer.isBuffer(value) ? value : Buffer.from(value ?? '');
+
+function auxiliaryDocument(url) {
+  const pathname = decodeURIComponent(new URL(url).pathname).toLowerCase();
+  return /\.(?:txt|xml)(?:\.gz)?$/.test(pathname) ||
+    /(?:^|\/)(?:sitemap|(?:[^/]*[-_])?polic(?:y|ies))(?:[-_.\/]|$)/.test(pathname);
+}
+
+function undeclaredAuxiliary(url, allowed) {
+  if (!auxiliaryDocument(url.href) || allowed.has(url.href)) return;
+  const error = new Error('auxiliary document was not declared');
+  error.code = 'auxiliary_undeclared';
+  throw error;
+}
+
+function safeHeaders(headers) {
+  const source = headers instanceof Headers ? Object.fromEntries(headers) : headers ?? {};
+  return Object.fromEntries(Object.entries(source).filter(([name]) => HEADER_NAMES.includes(name.toLowerCase()))
+    .map(([name, value]) => [name.toLowerCase(), String(value)]));
+}
+
+/** Response header lines in wire order; repeated lines (for example two X-Robots-Tag lines) stay separate. */
+export function headerLines(response) {
+  const lines = [];
+  if (Array.isArray(response.rawHeaders)) {
+    for (let i = 0; i + 1 < response.rawHeaders.length; i += 2) {
+      const name = String(response.rawHeaders[i]).toLowerCase();
+      if (HEADER_NAMES.includes(name)) lines.push({ name, value: String(response.rawHeaders[i + 1]) });
+    }
+    return lines;
+  }
+  const source = response.headers instanceof Headers ? Object.fromEntries(response.headers) : response.headers ?? {};
+  for (const [name, value] of Object.entries(source))
+    if (HEADER_NAMES.includes(name.toLowerCase())) for (const item of Array.isArray(value) ? value : [value])
+      lines.push({ name: name.toLowerCase(), value: String(item) });
+  return lines;
+}
+
+/** Node's lookup callback pins the already-vetted address while TLS still verifies the URL hostname. */
+async function nodeTransport({ url, address, timeoutMs, maxBytes, headers = {}, signal }) {
+  const client = url.protocol === 'https:' ? https : http;
+  const hostname = url.hostname.replace(/^\[|\]$/g, '');
+  return new Promise((resolve, reject) => {
+    const req = client.request(url, {
+      method: 'GET', agent: false, signal, headers: { 'User-Agent': 'optbrew/0.1 (bounded public audit)', Accept: '*/*', 'Accept-Encoding': 'identity', ...headers },
+      lookup: (_hostname, options, callback) => options.all ?
+        callback(null, [{ address: address.address, family: address.family }]) : callback(null, address.address, address.family),
+      ...(url.protocol === 'https:' ? { rejectUnauthorized: true,
+        ...(!isIP(hostname) ? { servername: hostname } : {}) } : {}),
+    }, res => {
+      const chunks = []; let size = 0;
+      if (Number(res.headers['content-length']) > maxBytes) {
+        req.destroy(new Error('response byte limit exceeded')); return;
+      }
+      res.on('data', chunk => {
+        size += chunk.length;
+        if (size > maxBytes) { req.destroy(new Error('response byte limit exceeded')); return; }
+        chunks.push(chunk);
+      });
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, rawHeaders: res.rawHeaders, body: Buffer.concat(chunks) }));
+      res.on('error', reject);
+    });
+    req.setTimeout(timeoutMs, () => req.destroy(new Error('request timeout')));
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function addressesFor(url, resolve) {
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  if (isIP(host)) return [{ address: host, family: isIP(host) }];
+  const values = await resolve(host);
+  return (Array.isArray(values) ? values : [values]).map(x => {
+    const address = typeof x === 'string' ? x : x?.address;
+    return { address, family: isIP(address) };
+  });
+}
+
+/** Fetch one URL with fresh DNS validation at every redirect and a pinned connection. */
+export async function fetchScoped(input, { context, transport = nodeTransport, resolve = host => lookup(host, { all: true, verbatim: true }), timeoutMs = 20000, maxBytes = 5242880, maxRedirects = 10, headers = {}, allowedAuxiliary = null, reserveRequest = null }) {
+  if (![timeoutMs, maxBytes, maxRedirects].every(Number.isInteger) || timeoutMs < 1 || timeoutMs > 20000 || maxBytes < 1 || maxBytes > 5242880 || maxRedirects < 0 || maxRedirects > 10)
+    throw new Error('fetch limits exceed context ceiling');
+  let url = assertUrlInScope(input, context.scope);
+  if (allowedAuxiliary) undeclaredAuxiliary(url, allowedAuxiliary);
+  const requested_url = String(input);
+  const redirect_chain = [];
+  const controller = new AbortController();
+  const deadline = performance.now() + timeoutMs;
+  let rejectTimeout;
+  const timeout = new Promise((_, reject) => { rejectTimeout = reject; });
+  const timer = setTimeout(() => { controller.abort(); rejectTimeout(new Error('request timeout')); }, timeoutMs);
+  const withinDeadline = promise => Promise.race([promise, timeout]);
+  try {
+    for (let hop = 0; hop <= maxRedirects; hop++) {
+      const addresses = await withinDeadline(addressesFor(url, resolve));
+      try { assertInScope(url.href, context.scope, addresses); }
+      catch (error) { error.code = 'scope_rejected'; error.redirect_chain = redirect_chain; throw error; }
+      // Pick only a vetted address. The transport must use this address, not resolve again.
+      const remainingMs = Math.ceil(deadline - performance.now());
+      if (remainingMs <= 0 || controller.signal.aborted) throw new Error('request timeout');
+      // Reserve the shared budget immediately before the real request; redirect hops are requests too.
+      if (reserveRequest && !reserveRequest()) {
+        const error = new Error('request budget exhausted');
+        error.code = 'request_limit';
+        error.redirect_chain = redirect_chain;
+        throw error;
+      }
+      const response = await withinDeadline(transport({ url, address: addresses[0], timeoutMs: remainingMs, maxBytes, headers, signal: controller.signal }));
+      if (!Number.isInteger(response?.status) || response.status < 100 || response.status > 599) throw new Error('invalid transport status');
+      const body = text(response.body);
+      if (body.length > maxBytes) throw new Error('response byte limit exceeded');
+      const savedHeaders = safeHeaders(response.headers);
+      if (REDIRECTS.has(response.status) && savedHeaders.location) {
+        if (hop === maxRedirects) throw new Error('redirect limit exceeded');
+        let next;
+        try { next = assertUrlInScope(new URL(savedHeaders.location, url).href, context.scope); }
+        catch {
+          const error = new Error('redirect outside scope');
+          error.code = 'redirect_outside_scope';
+          error.redirect_chain = [...redirect_chain, { url: url.href, status: response.status, location: '[blocked]' }];
+          throw error;
+        }
+        if (allowedAuxiliary) {
+          try { undeclaredAuxiliary(next, allowedAuxiliary); }
+          catch (error) { error.redirect_chain = [...redirect_chain, { url: url.href, status: response.status, location: '[blocked]' }]; throw error; }
+        }
+        redirect_chain.push({ url: url.href, status: response.status, location: next.href });
+        url = next;
+        continue;
+      }
+      return {
+        requested_url, normalized_url: assertUrlInScope(requested_url, context.scope).href, final_url: url.href,
+        status: response.status, headers: savedHeaders, header_lines: headerLines(response), redirect_chain, raw_html_ref: null,
+        content_hash: createHash('sha256').update(body).digest('hex'),
+        capability: savedHeaders['content-type']?.toLowerCase().includes('html') &&
+          (!savedHeaders['content-encoding'] || savedHeaders['content-encoding'].toLowerCase() === 'identity') ? 'raw_html' : 'raw_response',
+        source_ref: 'optbrew:collector', evidence_ref: null, error: null, body,
+      };
+    }
+    throw new Error('redirect limit exceeded');
+  } finally { clearTimeout(timer); }
+}
+
+/** Index of the declared robots.txt artifact on the same origin as the page, as the audit and the report both select it. */
+export function declaredRobotsIndex(artifacts, declaredRobots, pageFinalUrl) {
+  return artifacts.findIndex(x => {
+    try { const u = new URL(x.final_url); return declaredRobots.has(x.normalized_url) && u.origin === new URL(pageFinalUrl).origin && u.pathname === '/robots.txt'; }
+    catch { return false; }
+  });
+}
+
+function links(html, base) {
+  const out = [];
+  for (const match of html.matchAll(/<a\b[^>]*\bhref\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)) {
+    try { out.push(new URL(match[1] ?? match[2], base).href); } catch { /* malformed link */ }
+  }
+  return out;
+}
+
+/** Bounded crawl of fixed protocol URLs and their in-scope links. */
+export async function collect(context, { transport, resolve } = {}) {
+  const scope = context?.scope;
+  const limit = Math.min(scope?.max_urls ?? 50, 50);
+  const depthLimit = Math.min(scope?.max_depth ?? 3, 3);
+  const concurrency = Math.min(scope?.concurrency ?? 2, 2);
+  if (![limit, depthLimit, concurrency].every(Number.isInteger) || limit < 1 || depthLimit < 0 || concurrency < 1)
+    throw new Error('invalid collection limits');
+  const initial = context.protocol.page_types.flatMap(type => type.urls.map(ref => ref.normalized));
+  const auxiliary = context.protocol.auxiliary_resources ?? [];
+  const declaredAuxiliary = new Set(auxiliary.map(resource => resource.normalized));
+  const allowedDocuments = new Set([...initial, ...declaredAuxiliary]);
+  if (initial.some(url => /\/(?:robots\.txt|sitemap[^/]*\.xml)$/i.test(decodeURIComponent(new URL(url).pathname))))
+    throw new Error('robots and sitemap must be auxiliary resources');
+  if (auxiliary.length && initial.length + auxiliary.length > limit) throw new Error('selected pages and auxiliary resources exceed request scope');
+  const queue = []; const seen = new Set(); const skipped = [];
+  const enqueue = (url, depth, auxiliaryResource = false) => {
+    let normalized;
+    try { normalized = assertUrlInScope(url, scope).href; }
+    catch { skipped.push({ url, reason: 'outside_scope' }); return; }
+    if (depth > 0 && auxiliaryDocument(normalized) && !allowedDocuments.has(normalized)) {
+      skipped.push({ url: normalized, reason: 'auxiliary_undeclared' }); return;
+    }
+    if (seen.has(normalized)) return;
+    seen.add(normalized);
+    if (depth > depthLimit) { skipped.push({ url: normalized, reason: 'depth_limit' }); return; }
+    queue.push({ url: normalized, depth, auxiliaryResource });
+  };
+  initial.forEach(url => enqueue(url, 0));
+  for (const resource of auxiliary) {
+    if (seen.has(resource.normalized)) throw new Error('auxiliary resource duplicates selected URL');
+    const normalized = assertUrlInScope(resource.normalized, scope).href;
+    if (normalized !== resource.normalized || assertUrlInScope(resource.original, scope).href !== normalized)
+      throw new Error('auxiliary resource URL mismatch');
+    enqueue(normalized, 0, true);
+  }
+  const artifacts = []; let cursor = 0; let requestCount = 0; let evaluated = 0;
+  async function worker() {
+    while (cursor < queue.length) {
+      const item = queue[cursor++];
+      if (requestCount >= limit) { skipped.push({ url: item.url, reason: 'url_limit' }); continue; }
+      let used = 0;
+      const reserveRequest = () => {
+        if (requestCount >= limit) return false;
+        requestCount++; used++;
+        return true;
+      };
+      let artifact;
+      try { artifact = await fetchScoped(item.url, { context, transport, resolve, allowedAuxiliary: allowedDocuments, reserveRequest }); }
+      catch (error) {
+        const reason = ['scope_rejected', 'redirect_outside_scope', 'auxiliary_undeclared', 'request_limit'].includes(error.code) ? error.code : 'fetch_failed';
+        if (reason === 'request_limit' && !used) { skipped.push({ url: item.url, reason: 'url_limit' }); continue; }
+        if (reason !== 'fetch_failed') skipped.push({ url: item.url, reason });
+        artifact = { requested_url: item.url, normalized_url: item.url, final_url: null, status: null,
+          headers: {}, header_lines: [], redirect_chain: error.redirect_chain ?? [], raw_html_ref: null, content_hash: null, capability: 'none',
+          source_ref: 'optbrew:collector', evidence_ref: null, error: reason, body: Buffer.alloc(0) };
+      }
+      if (used) evaluated++;
+      artifacts.push(artifact);
+      if (!item.auxiliaryResource && artifact.status === 200 && artifact.capability === 'raw_html')
+        for (const next of links(artifact.body.toString('utf8'), artifact.final_url)) enqueue(next, item.depth + 1);
+    }
+  }
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  return { artifacts, discovered_count: seen.size, evaluated_count: evaluated, request_count: requestCount, skipped,
+    limit_reached: skipped.some(x => x.reason === 'url_limit' || x.reason === 'request_limit') };
+}

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

@@ -0,0 +1,47 @@
+import { validateEntity } from './contracts.mjs';
+import { freezeProtocol } from './protocol.mjs';
+import { compileUnits } from './weights.mjs';
+import { score } from './score.mjs';
+
+const close = (a, b) => Math.abs(a - b) <= 1e-9;
+const rawScore = result => result.M === 0 ? null : 100 * result.N / result.M;
+const rawCoverage = result => result.A === 0 ? null : 100 * result.M / result.A;
+const difference = (before, after) => before === null || after === null ? null : after - before;
+const relative = (before, after) => before === null || after === null || close(before, 0) ? null : (after - before) / before;
+
+/** Compare two ScoreInputs only when their frozen conditions and applicable units match. */
+export function compare(before, after) {
+  validateEntity('ScoreInput', before);
+  const baseline = freezeProtocol(before.run_context);
+  if (after === null || after === undefined) return { status: 'no_after', score_deltas: [], reasons: ['after_missing'] };
+  validateEntity('ScoreInput', after);
+  const followup = freezeProtocol(after.run_context);
+  const reasons = [];
+  if (baseline.protocol_hash !== followup.protocol_hash) {
+    for (const field of ['target', 'environment', 'evaluation_version', 'protocol_version'])
+      if (JSON.stringify(baseline.protocol[field]) !== JSON.stringify(followup.protocol[field])) reasons.push(`${field}_changed`);
+    for (const field of ['page_types', 'engines', 'families', 'locale', 'region', 'browser', 'device',
+      'question_panel', 'surfaces', 'models', 'search_enabled', 'target_identity'])
+      if (JSON.stringify(baseline.protocol[field]) !== JSON.stringify(followup.protocol[field])) reasons.push(`${field}_changed`);
+    if (!reasons.length) reasons.push('protocol_changed');
+  }
+  if (reasons.length) return { status: 'not_comparable', score_deltas: [], reasons: [...new Set(reasons)] };
+  // The protocol fixes planned units. Evidence-backed N/A can still change the actual denominator.
+  const unitSignature = input => compileUnits(input, 'SEO').map(unit => [unit.key, unit.weight]).sort((a, b) => a[0].localeCompare(b[0]));
+  const leftUnits = unitSignature(before), rightUnits = unitSignature(after);
+  if (leftUnits.length !== rightUnits.length || leftUnits.some(([key, weight], i) =>
+    key !== rightUnits[i][0] || !close(weight, rightUnits[i][1]))) reasons.push('applicable_units_changed');
+  if (reasons.length) return { status: 'not_comparable', score_deltas: [], reasons: [...new Set(reasons)] };
+  const left = score(before), right = score(after);
+  const score_deltas = left.map((item, i) => {
+    const next = right[i];
+    const oldScore = rawScore(item), newScore = rawScore(next);
+    return { profile: item.profile, before: oldScore, after: newScore,
+      raw_difference: difference(oldScore, newScore),
+      percentage_point_delta: difference(oldScore, newScore),
+      relative_change: relative(oldScore, newScore),
+      coverage_percentage_point_delta: difference(rawCoverage(item), rawCoverage(next)),
+      A_delta: next.A - item.A, M_delta: next.M - item.M, N_delta: next.N - item.N };
+  });
+  return { status: 'comparable', score_deltas, reasons: [] };
+}

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

@@ -0,0 +1,144 @@
+import { readFileSync } from 'node:fs';
+
+const schema = JSON.parse(readFileSync(new URL('../../references/schemas/contract.schema.json', import.meta.url)));
+const registry = JSON.parse(readFileSync(new URL('../../references/check-registry.json', import.meta.url)));
+const families = new Map(registry.families.map(family => [family.family_id, family]));
+const tolerance = 1e-9;
+const cwv = { 'lcp-field': [2500, 4000, 'ms'], 'inp-field': [200, 500, 'ms'], 'cls-field': [0.1, 0.25, 'unitless'] };
+
+export class ContractError extends Error {
+  constructor(message) { super(message); this.name = 'ContractError'; }
+}
+
+function fail(path, message) { throw new ContractError(`${path}: ${message}`); }
+function plainObject(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) &&
+  (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null); }
+
+function jsonSafe(value, path = '$', seen = new Set()) {
+  if (value === undefined || typeof value === 'function' || typeof value === 'symbol' || typeof value === 'bigint') fail(path, 'not JSON data');
+  if (typeof value === 'number' && !Number.isFinite(value)) fail(path, 'nonfinite number');
+  if (value && typeof value === 'object') {
+    if (seen.has(value)) fail(path, 'cycle');
+    seen.add(value);
+    if (!Array.isArray(value) && !plainObject(value)) fail(path, 'not a plain JSON object');
+    for (const [key, child] of Object.entries(value)) jsonSafe(child, `${path}.${key}`, seen);
+    seen.delete(value);
+  }
+}
+
+function checkRule(rule, value, path) {
+  if (rule.$ref) return checkRule(schema.$defs[rule.$ref.split('/').at(-1)], value, path);
+  if ('const' in rule && value !== rule.const) fail(path, `expected ${JSON.stringify(rule.const)}`);
+  if (rule.enum && !rule.enum.includes(value)) fail(path, 'unrecognized value');
+  if (rule.type) {
+    const types = Array.isArray(rule.type) ? rule.type : [rule.type];
+    const valid = types.some(type => type === 'null' ? value === null : type === 'array' ? Array.isArray(value) : type === 'object' ? plainObject(value) : typeof value === type);
+    if (!valid) fail(path, `expected ${types.join(' or ')}`);
+  }
+  if (typeof value === 'number') {
+    if (rule.minimum !== undefined && value < rule.minimum) fail(path, 'below minimum');
+    if (rule.maximum !== undefined && value > rule.maximum) fail(path, 'above maximum');
+  }
+  if (plainObject(value)) {
+    for (const key of rule.required ?? []) if (!Object.hasOwn(value, key)) fail(`${path}.${key}`, 'required');
+    if (rule.additionalProperties === false) for (const key of Object.keys(value))
+      if (!Object.hasOwn(rule.properties ?? {}, key)) fail(`${path}.${key}`, 'unexpected field');
+    for (const [key, child] of Object.entries(rule.properties ?? {})) if (Object.hasOwn(value, key)) checkRule(child, value[key], `${path}.${key}`);
+  }
+  if (Array.isArray(value) && rule.items) value.forEach((item, i) => checkRule(rule.items, item, `${path}[${i}]`));
+}
+
+/** A decision is traceable evidence for a condition, never evidence of a measured score. */
+export function validateApplicabilityDecision(decision, allowedConditions, path = 'applicability_decision') {
+  if (!decision) fail(path, 'structured condition decision required');
+  checkRule(schema.$defs.ApplicabilityDecision, decision, path);
+  if (!allowedConditions.includes(decision.condition)) fail(path, `condition not allowed: ${decision.condition}`);
+  if (!decision.reason.trim() || !decision.evidence_ref.trim()) fail(path, 'reason and evidence_ref required');
+  return decision;
+}
+
+/** Official p75 thresholds; optbrew assigns the middle interval q=0.5. */
+export function cwvVerdict(familyId, value, { percentile = 75, source_type = 'field', unit } = {}) {
+  const limits = cwv[familyId];
+  if (!limits) throw new ContractError(`unknown CWV family: ${familyId}`);
+  if (!Number.isFinite(value) || value < 0 || percentile !== 75 || source_type !== 'field' || unit !== limits[2])
+    throw new ContractError(`invalid p75 field measurement for ${familyId}`);
+  if (value <= limits[0] + tolerance) return { state: 'pass', q: 1, partial_basis: null };
+  if (value > limits[1] + tolerance) return { state: 'fail', q: 0, partial_basis: null };
+  return { state: 'partial', q: 0.5, partial_basis: { kind: 'threshold_half' } };
+}
+
+function checkObservation(value) {
+  const { state, q, partial_basis: basis } = value;
+  const definition = families.get(value.family_id);
+  if (!definition) fail('CheckObservation.family_id', 'unregistered family');
+  if (state === 'unknown' || state === 'not_applicable') {
+    if (q !== null || basis !== null) fail('CheckObservation', `${state} requires null q and basis`);
+    if (state === 'not_applicable') {
+      if (definition.core_policy) fail('CheckObservation', 'core policy unit cannot be not_applicable');
+      validateApplicabilityDecision(value.applicability_decision, definition.na_conditions, 'CheckObservation.applicability_decision');
+    }
+  } else if (state === 'pass' || state === 'fail') {
+    if (typeof q !== 'number' || Math.abs(q - (state === 'pass' ? 1 : 0)) > tolerance || basis !== null) fail('CheckObservation', `${state} requires fixed q and null basis`);
+  } else if (state === 'partial') {
+    if (!plainObject(basis) || !(q > 0 && q < 1)) fail('CheckObservation', 'partial requires a supported basis and interior q');
+    if (definition.verdict_mode === 'binary') fail('CheckObservation', `${value.family_id} is binary`);
+    if (basis.kind === 'threshold_half') {
+      if (definition.verdict_mode !== 'threshold_half') fail('CheckObservation', `${value.family_id} does not allow threshold_half`);
+      if (Math.abs(q - 0.5) > tolerance) fail('CheckObservation', 'threshold_half requires q=0.5');
+    } else if (basis.kind === 'ratio') {
+      if (definition.verdict_mode !== 'ratio') fail('CheckObservation', `${value.family_id} does not allow ratio`);
+      if (!Number.isInteger(basis.numerator) || !Number.isInteger(basis.denominator) || basis.denominator <= 0 ||
+          basis.numerator <= 0 || basis.numerator >= basis.denominator || Math.abs(q - basis.numerator / basis.denominator) > tolerance)
+        fail('CheckObservation', 'ratio requires matching integer numerator and positive denominator');
+    } else fail('CheckObservation', 'unsupported partial basis');
+  }
+  if (state !== 'not_applicable' && value.applicability_decision) fail('CheckObservation', 'decision only allowed for not_applicable');
+  if (value.measurement && cwv[value.family_id]) {
+    const expected = cwvVerdict(value.family_id, value.measurement.value, value.measurement);
+    if (expected.state !== state || Math.abs(expected.q - q) > tolerance) fail('CheckObservation', 'CWV state/q differs from field p75');
+  } else if (cwv[value.family_id] && !['unknown', 'not_applicable'].includes(state)) {
+    fail('CheckObservation', 'CWV measurement requires field p75 source and unit');
+  }
+  if (value.blocker === true && state !== 'fail') fail('CheckObservation', 'blocker requires fail');
+}
+
+function checkMetric(value) {
+  const path = 'MetricObservation';
+  if (!value.metric_id.trim() || !value.definition.trim() || !value.provider_definition.trim() ||
+      !value.source_ref.trim() || !value.evidence_ref.trim()) fail(path, 'nonempty identity, definition and evidence required');
+  if (value.value_state === 'measured' ? !Number.isFinite(value.value) : value.value !== null)
+    fail(path, 'value_state and value disagree');
+  if (!value.sample_selection || !['all', 'positive_only', 'unknown'].includes(value.sample_selection.kind))
+    fail(path, 'sample_selection.kind required');
+  if (value.value_state === 'not_applicable' &&
+      (typeof value.sample_selection.exclusion_reason !== 'string' || !value.sample_selection.exclusion_reason.trim()))
+    fail(path, 'not_applicable requires an exclusion reason');
+  const { start, end, timezone } = value.window;
+  for (const [name, date] of [['start', start], ['end', end]]) {
+    const timestamp = Date.parse(`${date}T00:00:00Z`);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || !Number.isFinite(timestamp) ||
+        new Date(timestamp).toISOString().slice(0, 10) !== date)
+      fail(`${path}.window.${name}`, 'invalid local date');
+  }
+  if (start > end || !timezone) fail(`${path}.window`, 'ordered dates and timezone required');
+  try { new Intl.DateTimeFormat('en', { timeZone: timezone }); }
+  catch { fail(`${path}.window.timezone`, 'invalid timezone'); }
+  if ((value.numerator === null) !== (value.denominator === null) ||
+      (value.numerator !== null && (!Number.isFinite(value.numerator) || !Number.isFinite(value.denominator) || value.denominator <= 0)))
+    fail(path, 'numerator and positive denominator must occur together');
+  if (value.sample_selection.kind === 'positive_only' &&
+      /(?:^|:)citation_response_rate$/.test(value.metric_id)) fail(path, 'positive-only sample cannot estimate all-question citation rate');
+}
+
+/** Validate a persisted entity and return its original value. */
+export function validateEntity(typeName, value) {
+  const rule = schema.$defs[typeName];
+  if (!rule) throw new ContractError(`unknown entity type: ${typeName}`);
+  jsonSafe(value);
+  checkRule(rule, value, typeName);
+  if (typeName === 'CheckObservation') checkObservation(value);
+  if (typeName === 'ScoreInput') value.observations.forEach(checkObservation);
+  if (typeName === 'MetricObservation') checkMetric(value);
+  return value;
+}

package/skills/optbrew/scripts/core/cost-ledger.mjs

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, basename, join } from 'node:path';
+import { validateEntity } from './contracts.mjs';
+
+function amountKey(item, provider) { return `${provider}\u0000${item.unit}\u0000${item.currency ?? ''}`; }
+function validAmounts(items, allowZero = false) {
+  if (!Array.isArray(items) || !items.length) throw new Error('cost upper bounds required');
+  const seen = new Set();
+  for (const item of items) {
+    if (!['credits', 'tokens', 'search_calls', 'currency_minor'].includes(item.unit) ||
+        !Number.isSafeInteger(item.amount) || (allowZero ? item.amount < 0 : item.amount < 1) ||
+        (item.unit === 'currency_minor' ? !/^[A-Z]{3}$/.test(item.currency ?? '') : item.currency != null))
+      throw new Error('invalid cost unit or amount');
+    const key = amountKey(item, '');
+    if (seen.has(key)) throw new Error('duplicate cost unit');
+    seen.add(key);
+  }
+}
+
+async function locked(file, action) {
+  const lock = `${file}.lock`;
+  // ponytail: one ledger lock limits throughput; split by run only if this becomes measurable.
+  let acquired = false;
+  for (let attempt = 0; attempt < 30; attempt++) {
+    try { await mkdir(lock); acquired = true; break; }
+    catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      if (attempt === 29) throw new Error('cost ledger lock exists; manual recovery required');
+      await new Promise(resolve => setTimeout(resolve, 10));
+    }
+  }
+  if (!acquired) throw new Error('cost ledger lock exists');
+  try {
+    const ledger = validateEntity('CostLedger', JSON.parse(await readFile(file, 'utf8')));
+    const result = await action(ledger);
+    const temporary = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`);
+    try { await writeFile(temporary, `${JSON.stringify(ledger, null, 2)}\n`, { flag: 'wx' }); await rename(temporary, file); }
+    catch (error) { await rm(temporary, { force: true }); throw error; }
+    return result ?? ledger;
+  } finally { await rm(lock, { recursive: true }); }
+}
+
+function heldAmount(ledger, provider, unit) {
+  return ledger.reservations.reduce((total, reservation) => {
+    if (reservation.provider !== provider) return total;
+    const upper = reservation.upperBounds.find(x => amountKey(x, provider) === amountKey(unit, provider));
+    if (!upper) return total;
+    const settled = ledger.settlements.find(x => x.reservation_id === reservation.reservation_id && ['settled', 'overrun'].includes(x.status));
+    return total + BigInt(settled?.actual?.find(x => amountKey(x, provider) === amountKey(unit, provider))?.amount ?? upper.amount);
+  }, 0n);
+}
+
+/** Reserve a per-attempt upper bound before any paid provider request. */
+export async function reserveCost(ledgerPath, { provider, upperBounds, approvalRef, runId }) {
+  if (typeof provider !== 'string' || !provider || typeof approvalRef !== 'string' || !approvalRef) throw new Error('provider and approval required');
+  validAmounts(upperBounds);
+  return locked(ledgerPath, ledger => {
+    if (ledger.approval_ref !== approvalRef) throw new Error('cost approval mismatch');
+    if (runId !== undefined && ledger.run_id !== runId) throw new Error('cost ledger run mismatch');
+    if (ledger.reservations.some(x => x.status === 'overrun')) throw new Error('cost spending blocked by observed overrun');
+    for (const requested of upperBounds) {
+      const budget = ledger.budgets.find(x => x.provider === provider && amountKey(x, provider) === amountKey(requested, provider));
+      if (!budget || !Number.isSafeInteger(budget.amount) || budget.amount < 0) throw new Error('cost cap missing');
+      if (heldAmount(ledger, provider, requested) + BigInt(requested.amount) > BigInt(budget.amount)) throw new Error('cost cap exceeded');
+    }
+    const reservation = { reservation_id: randomUUID(), provider, upperBounds, status: 'reserved', approval_ref: approvalRef,
+      created_at: new Date().toISOString() };
+    ledger.reservations.push(reservation);
+    return reservation;
+  });
+}
+
+/** Unknown billing retains the bound; an observed overrun is recorded and blocks new spend. */
+export async function settleCost(ledgerPath, reservationId, actualOrUnknown) {
+  return locked(ledgerPath, ledger => {
+    const reservation = ledger.reservations.find(x => x.reservation_id === reservationId);
+    if (!reservation || reservation.status !== 'reserved') throw new Error('reservation not open');
+    const unknown = actualOrUnknown === 'unknown';
+    let overrun = false;
+    if (!unknown) {
+      validAmounts(actualOrUnknown, true);
+      for (const actual of actualOrUnknown) {
+        const upper = reservation.upperBounds.find(x => amountKey(x, reservation.provider) === amountKey(actual, reservation.provider));
+        if (!upper) throw new Error('actual cost unit was not reserved');
+        if (actual.amount > upper.amount) overrun = true;
+      }
+      if (actualOrUnknown.length !== reservation.upperBounds.length) throw new Error('actual cost units incomplete');
+    }
+    reservation.status = unknown ? 'unknown' : overrun ? 'overrun' : 'settled';
+    ledger.settlements.push({ reservation_id: reservationId, status: reservation.status, actual: unknown ? null : actualOrUnknown,
+      settled_at: new Date().toISOString() });
+    return ledger;
+  });
+}