optbrew 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,52 @@
+import { BlockList, isIP } from 'node:net';
+
+const blocked4 = new BlockList();
+const blocked6 = new BlockList();
+for (const [base, prefix] of [['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8],
+  ['169.254.0.0', 16], ['172.16.0.0', 12], ['192.0.0.0', 24], ['192.0.2.0', 24],
+  ['192.168.0.0', 16], ['198.18.0.0', 15], ['198.51.100.0', 24], ['203.0.113.0', 24],
+  ['224.0.0.0', 4], ['240.0.0.0', 4]]) blocked4.addSubnet(base, prefix, 'ipv4');
+for (const [base, prefix] of [['::', 128], ['::1', 128], ['::ffff:0:0', 96], ['fc00::', 7], ['fe80::', 10],
+  ['ff00::', 8], ['2001:db8::', 32]]) blocked6.addSubnet(base, prefix, 'ipv6');
+
+function addressText(value) { return typeof value === 'string' ? value : value?.address; }
+function privateAddress(value) {
+  const address = addressText(value);
+  const kind = isIP(address);
+  if (!kind) throw new Error('unresolved or invalid IP address');
+  if (kind === 4) return blocked4.check(address, 'ipv4');
+  const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/i.exec(address);
+  return mapped ? blocked4.check(mapped[1], 'ipv4') : blocked6.check(address, 'ipv6');
+}
+
+/** Check the URL boundary before DNS; every request additionally checks resolved IPs. */
+export function assertUrlInScope(input, scope) {
+  let url;
+  try { url = new URL(input); } catch { throw new Error('invalid URL'); }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) throw new Error('URL scheme or userinfo outside scope');
+  if (/%(?:2f|5c|25)/i.test(url.pathname)) throw new Error('encoded path delimiter outside scope');
+  if (!Array.isArray(scope?.allowed) || !scope.allowed.length) throw new Error('scope.allowed required');
+  const path = decodeURIComponent(url.pathname);
+  const matching = scope.allowed.some(rule => {
+    let origin;
+    try { origin = new URL(rule.origin); } catch { return false; }
+    if (origin.origin !== url.origin || origin.username || origin.password || origin.pathname !== '/' || origin.search || origin.hash) return false;
+    const prefix = rule.path_prefix ?? '/';
+    if (typeof prefix !== 'string' || !prefix.startsWith('/')) return false;
+    return prefix === '/' || path === prefix || path.startsWith(prefix.endsWith('/') ? prefix : `${prefix}/`);
+  });
+  if (!matching) throw new Error('URL outside allowed origin or path');
+  url.hash = '';
+  return url;
+}
+
+/** Check origin, path segment, and every resolved address before a request. */
+export function assertInScope(input, scope, resolvedAddresses) {
+  const url = assertUrlInScope(input, scope);
+  if (!Array.isArray(resolvedAddresses) || !resolvedAddresses.length) throw new Error('resolved addresses required');
+  const host = url.hostname.replace(/^\[|\]$/g, '');
+  const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+  const local = (scope.local_targets ?? []).some(x => x.host === host && Number(x.port) === port);
+  for (const address of resolvedAddresses) if (privateAddress(address) && !local) throw new Error('private or reserved address outside local target');
+  return url;
+}

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

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { validateEntity, cwvVerdict, ContractError } from './contracts.mjs';
+import { compileUnits, scoreWeighted } from './weights.mjs';
+
+const registry = JSON.parse(readFileSync(new URL('../../references/check-registry.json', import.meta.url)));
+const profiles = JSON.parse(readFileSync(new URL('../../references/profiles.json', import.meta.url)));
+const bundleRoot = new URL('../../', import.meta.url);
+
+function assertEvaluationIdentity(context) {
+  const manifest = JSON.parse(readFileSync(new URL('bundle-manifest.json', bundleRoot), 'utf8'));
+  if (!manifest.evaluation_hash || !manifest.protocol_hash ||
+      context.evaluation_version !== manifest.evaluation_version ||
+      context.protocol_version !== manifest.protocol_version)
+    throw new ContractError('evaluation version or protocol identity differs from installed bundle');
+  for (const [field, hashField] of [['evaluation_sources', 'evaluation_hash'], ['protocol_sources', 'protocol_hash']]) {
+    const sources = manifest[field];
+    if (!Array.isArray(sources) || !sources.length ||
+        createHash('sha256').update(JSON.stringify(sources)).digest('hex') !== manifest[hashField] ||
+        sources.some(source => createHash('sha256').update(readFileSync(new URL(source.path, bundleRoot))).digest('hex') !== source.sha256))
+      throw new ContractError(`${field} identity differs from installed bundle`);
+  }
+}
+
+export { cwvVerdict };
+
+function band(score) {
+  if (score === null) return null;
+  if (score < 60) return 'focus_improvement';
+  if (score < 80) return 'major_improvement';
+  if (score < 95) return 'additional_improvement';
+  return 'remaining_review';
+}
+
+/** Readiness scores are local audit status, never predicted search or AI outcomes. */
+export function score(input) {
+  validateEntity('ScoreInput', input);
+  assertEvaluationIdentity(input.run_context);
+  const units = compileUnits(input, 'SEO');
+  const coreIds = new Set(registry.families.filter(x => x.core_policy).map(x => x.family_id));
+  const blockingIds = new Set(registry.families.filter(x => x.blocker_on_fail).map(x => x.family_id));
+  const canonicalObservations = [...input.observations].sort((a, b) => {
+    const left = [a.unit_key, a.observation_id, a.source_ref, a.evidence_ref, a.reason].join('\0');
+    const right = [b.unit_key, b.observation_id, b.source_ref, b.evidence_ref, b.reason].join('\0');
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  const observations = new Map();
+  for (const obs of canonicalObservations) if (!observations.has(obs.unit_key)) observations.set(obs.unit_key, obs);
+  const blockers = [], unknown_core = [];
+  for (const unit of units) {
+    const obs = observations.get(unit.key);
+    if ((blockingIds.has(unit.family_id) || obs?.blocker) && unit.state === 'fail')
+      blockers.push({ family_id: unit.family_id, unit_key: unit.key, reason: obs?.reason ?? 'confirmed failure', evidence_ref: obs?.evidence_ref ?? null });
+    if (coreIds.has(unit.family_id) && unit.state === 'unknown')
+      unknown_core.push({ family_id: unit.family_id, unit_key: unit.key });
+  }
+  for (const obs of canonicalObservations) if (obs.blocker && obs.state === 'fail' &&
+    !blockers.some(x => x.unit_key === obs.unit_key))
+    blockers.push({ family_id: obs.family_id, unit_key: obs.unit_key, reason: obs.reason, evidence_ref: obs.evidence_ref });
+  blockers.sort((a, b) => a.unit_key < b.unit_key ? -1 : a.unit_key > b.unit_key ? 1 : 0);
+  const selectedProfiles = Object.keys(profiles.profiles).filter(name => name !== 'NEO' || input.run_context.protocol.engines.includes('naver'));
+  return selectedProfiles.map(profile => {
+    const weighted = scoreWeighted(compileUnits(input, profile));
+    const readiness_status = weighted.A === 0 ? 'not_applicable' : blockers.length ? 'blocked' :
+      unknown_core.length ? 'unverified' : 100 * weighted.M / weighted.A < 80 - 1e-9 ? 'provisional' : 'measured';
+    const result = { schema_version: '1.0.0', evaluation_version: input.run_context.evaluation_version,
+      profile, ...weighted, band: band(weighted.M === 0 ? null : 100 * weighted.N / weighted.M), readiness_status,
+      blockers, unknown_core, source_ref: 'optbrew:scoring:0.1.0' };
+    return validateEntity('ScoreResult', result);
+  });
+}

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

@@ -0,0 +1,139 @@
+import { readFileSync } from 'node:fs';
+import { ContractError, validateEntity } from './contracts.mjs';
+import { freezeProtocol } from './protocol.mjs';
+
+const registry = JSON.parse(readFileSync(new URL('../../references/check-registry.json', import.meta.url)));
+const familyById = new Map(registry.families.map(family => [family.family_id, family]));
+const profiles = JSON.parse(readFileSync(new URL('../../references/profiles.json', import.meta.url)));
+const tolerance = 1e-9;
+
+function candidateUnits(definition, plan, protocol) {
+  const publicOnly = ['index-policy', 'search-crawl-policy', 'discovery'].includes(definition.family_id);
+  const pageTypes = protocol.page_types.map(type => ({ ...type,
+    urls: type.urls.filter(url => (!publicOnly || url.public_indexing) &&
+      (!plan.urls || plan.urls.includes(url.normalized))) })).filter(type => type.urls.length);
+  const pages = pageTypes.flatMap(type => type.urls.map(url => ({ url: url.normalized,
+    share: 1 / pageTypes.length / type.urls.length })));
+  const scope = definition.unit_scope;
+  if (scope === 'site') return [{ key: `${definition.family_id}|site`, engine: null, url: null, share: 1 }];
+  if (scope === 'origin') {
+    const origins = [...new Set(pages.map(page => new URL(page.url).origin))];
+    return origins.map(origin => ({ key: `${definition.family_id}|${origin}`, engine: null, url: origin, share: 1 / origins.length }));
+  }
+  if (scope === 'url') return pages.map(page => ({ key: `${definition.family_id}|${page.url}`,
+    engine: null, url: page.url, share: page.share }));
+  if (scope === 'engine_url') {
+    const engines = (plan.engines ?? protocol.engines).filter(engine => !definition.engines || definition.engines.includes(engine));
+    return engines.flatMap(engine => pages.map(page => ({ key: `${definition.family_id}|${engine}|${page.url}`,
+      engine, url: page.url, share: page.share / engines.length })));
+  }
+  throw new ContractError(`unsupported unit scope: ${scope}`);
+}
+
+function observationsByUnit(input) {
+  const result = new Map();
+  for (const obs of input.observations) {
+    if (obs.check_id !== obs.family_id) throw new ContractError(`unregistered check_id: ${obs.check_id}`);
+    const previous = result.get(obs.unit_key);
+    if (previous && (previous.family_id !== obs.family_id || previous.state !== obs.state ||
+      previous.q !== obs.q || JSON.stringify(previous.partial_basis) !== JSON.stringify(obs.partial_basis) ||
+      previous.applicability_decision?.condition !== obs.applicability_decision?.condition ||
+      Boolean(previous.blocker) !== Boolean(obs.blocker)))
+      throw new ContractError(`conflicting observation for ${obs.unit_key}`);
+    result.set(obs.unit_key, previous ?? obs);
+  }
+  return result;
+}
+
+/** Compile fixed protocol units in axis → family → engine → page type/URL order. */
+export function compileUnits(input, profile) {
+  validateEntity('ScoreInput', input);
+  const profileWeights = profiles.profiles[profile];
+  if (!profileWeights) throw new ContractError(`unknown profile: ${profile}`);
+  const { protocol } = freezeProtocol(input.run_context);
+  const plans = new Map(protocol.families.map(plan => [plan.family_id, plan]));
+  if (plans.size !== registry.families.length || registry.families.some(def => !plans.has(def.family_id)))
+    throw new ContractError('protocol must state applicability for all 22 families');
+  const observed = observationsByUnit(input);
+  for (const obs of input.observations) if (obs.state === 'not_applicable') {
+    const definition = familyById.get(obs.family_id);
+    if (definition.unit_scope === 'site' || obs.family_id === 'discovery' ||
+        (obs.family_id === 'naver-markup' && obs.applicability_decision.condition === 'naver_not_target'))
+      throw new ContractError(`${obs.family_id}: unit N/A contradicts fixed protocol conditions`);
+  }
+  const questionCoverage = observed.get('question-coverage|site');
+  if (questionCoverage?.partial_basis?.kind === 'ratio' &&
+      questionCoverage.partial_basis.denominator !== protocol.question_panel.length)
+    throw new ContractError('question-coverage denominator differs from fixed panel');
+  const expected = new Set();
+  const families = [];
+  for (const definition of registry.families) {
+    const plan = plans.get(definition.family_id);
+    if (!plan.applicable) continue;
+    const candidates = candidateUnits(definition, plan, protocol);
+    if (!candidates.length) throw new ContractError(`applicable family has no fixed units: ${definition.family_id}`);
+    for (const candidate of candidates) expected.add(candidate.key);
+    const active = candidates.map(candidate => ({ ...candidate, observation: observed.get(candidate.key) })).filter(x => x.observation?.state !== 'not_applicable');
+    if (active.length) families.push({ definition, active, total: active.reduce((sum, x) => sum + x.share, 0) });
+  }
+  for (const obs of input.observations) {
+    if (!expected.has(obs.unit_key) || !obs.unit_key.startsWith(`${obs.family_id}|`))
+      throw new ContractError(`unregistered observation unit: ${obs.unit_key}`);
+  }
+  const axes = profiles.axes.filter(axis => profileWeights[axis] > 0 && families.some(f => f.definition.axis === axis));
+  const availableAxisWeight = axes.reduce((sum, axis) => sum + profileWeights[axis], 0);
+  const units = [];
+  for (const axis of axes) {
+    const axisFamilies = families.filter(f => f.definition.axis === axis);
+    const axisWeight = 100 * profileWeights[axis] / availableAxisWeight;
+    for (const family of axisFamilies) {
+      for (const candidate of family.active) {
+        const obs = candidate.observation;
+        units.push({ key: candidate.key, family_id: family.definition.family_id,
+          engine: candidate.engine, url: candidate.url,
+          weight: axisWeight / axisFamilies.length * candidate.share / family.total,
+          state: obs?.state ?? 'unknown', q: obs?.q ?? null });
+      }
+    }
+  }
+  return units;
+}
+
+const display = value => Math.round((value + Number.EPSILON) * 10) / 10;
+const tidy = value => Math.abs(value) < tolerance ? 0 : Math.abs(value - 100) < tolerance ? 100 : value;
+
+/** A/M/N remain raw weighted totals; only displayed percentages are rounded. */
+export function scoreWeighted(units) {
+  if (!Array.isArray(units)) throw new ContractError('units must be an array');
+  const keys = new Set();
+  let A = 0, M = 0, N = 0;
+  for (const unit of units) {
+    if (!unit || typeof unit.key !== 'string' || !unit.key || keys.has(unit.key) ||
+      !Number.isFinite(unit.weight) || unit.weight < 0) throw new ContractError('invalid or duplicate weighted unit');
+    keys.add(unit.key);
+    const { state, q, weight } = unit;
+    const definition = familyById.get(unit.family_id);
+    if (state === 'not_applicable') {
+      if (q !== null) throw new ContractError('not_applicable q must be null');
+      if (definition?.core_policy) throw new ContractError(`${unit.family_id}: core policy unit cannot be not_applicable`);
+      continue;
+    }
+    A += weight;
+    if (state === 'unknown') {
+      if (q !== null) throw new ContractError('unknown q must be null');
+      continue;
+    }
+    if (!['pass', 'partial', 'fail'].includes(state) || !Number.isFinite(q) || q < 0 || q > 1 ||
+      (state === 'pass' && Math.abs(q - 1) > tolerance) ||
+      (state === 'fail' && Math.abs(q) > tolerance) ||
+      (state === 'partial' && (!(q > 0 && q < 1) || definition?.verdict_mode === 'binary' ||
+        (definition?.verdict_mode === 'threshold_half' && Math.abs(q - 0.5) > tolerance))))
+      throw new ContractError(`invalid weighted verdict: ${unit.key}`);
+    M += weight;
+    N += weight * q;
+  }
+  A = tidy(A); M = tidy(M); N = tidy(N);
+  return { A, M, N, score: M === 0 ? null : display(100 * N / M),
+    coverage: A === 0 ? null : display(100 * M / A),
+    missing_bounds: A === 0 ? null : [display(100 * N / A), display(100 * (N + A - M) / A)] };
+}