@wix/agent-skills 1.36.0 → 1.36.1

package/skills/wix-headless-replatform/scripts/lib/extraction-contract.mjs

@@ -1,374 +0,0 @@
-import { createHash } from "node:crypto";
-import path from "node:path";
-import { readFile } from "node:fs/promises";
-import { ensureDir, writeJson } from "./common.mjs";
-import { validateGeneratedArtifact } from "./extraction-validators.generated.mjs";
-
-export const EXTRACTION_SCHEMA_VERSION = "0083.1";
-export const MAX_GAP_RECOVERY_ATTEMPTS = 2;
-export const EXTRACTION_BUDGETS = Object.freeze({
-  maxRawEvidenceBytes: 250 * 1024 * 1024,
-  maxFrozenSpecBytes: 10 * 1024 * 1024,
-  maxAgentDecisions: 30,
-  maxAgentInputTokens: 50_000,
-  maxExtractionMs: 10 * 60 * 1000,
-});
-
-const ARTIFACT_KINDS = new Set([
-  "page-resolution",
-  "observation-packet",
-  "page-capture",
-  "foundation",
-  "metadata",
-  "shared-chrome",
-  "unit",
-  "extraction-gap",
-  "extraction-manifest",
-  "build-plan",
-  "final-report",
-  "decision-request",
-  "decision-patch",
-]);
-
-const NON_SEMANTIC_KEYS = new Set([
-  "createdAt",
-  "updatedAt",
-  "startedAt",
-  "completedAt",
-  "generatedAt",
-  "capturedAt",
-  "timestamp",
-  "logs",
-  "log",
-]);
-
-const ALLOWED_FIELDS = Object.freeze({
-  "page-resolution": new Set(["schemaVersion", "kind", "id", "pageKey", "destinationRoute", "status", "source", "evidence", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  "page-capture": new Set(["schemaVersion", "kind", "id", "pageKey", "status", "sourceFingerprint", "viewportSet", "sectionOrder", "ignoredSurfaces", "normalizationActions", "observationRefs", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  foundation: new Set(["schemaVersion", "kind", "id", "pageKey", "status", "tokens", "fonts", "primitives", "globalCssIntent", "evidenceRefs", "acceptance", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  metadata: new Set(["schemaVersion", "kind", "id", "pageKey", "status", "document", "evidenceRefs", "acceptance", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  "shared-chrome": new Set(["schemaVersion", "kind", "id", "pageKey", "status", "header", "footer", "controls", "visualAssets", "behavior", "evidenceRefs", "acceptance", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  unit: new Set(["schemaVersion", "kind", "id", "unitKind", "pageKey", "parentUnitId", "order", "status", "classification", "scope", "content", "assets", "layers", "layout", "styleables", "behavior", "children", "reconstruction", "acceptance", "diagnostics", "provenance", "gapRefs", "dependencyHashes", "hash", "extensions"]),
-  "extraction-gap": new Set(["schemaVersion", "kind", "id", "ownerUnitId", "scope", "status", "missingFields", "reason", "evidenceRefs", "confidence", "dependencyClosure", "affectedAcceptance", "attempts", "remainingAttempts", "assumptions", "omissions", "unblockAction", "userDecision", "extensions"]),
-  "extraction-manifest": new Set(["schemaVersion", "kind", "captureId", "pageKey", "pageResolution", "pageCapture", "observationRefs", "specs", "gaps", "budgets", "status", "manifestHash", "extensions"]),
-  "build-plan": new Set(["schemaVersion", "kind", "pageKey", "route", "manifestHash", "status", "units", "extensions"]),
-  "final-report": new Set(["schemaVersion", "kind", "captureId", "manifestHash", "status", "summary", "gaps", "qa", "extensions"]),
-  "decision-request": new Set(["schemaVersion", "kind", "id", "decisionType", "allowedChoices", "evidenceRefs", "detectorVersions", "responseSchema", "cacheKey", "extensions"]),
-  "decision-patch": new Set(["schemaVersion", "kind", "requestId", "choice", "confidence", "reasonCodes", "extensions"]),
-});
-
-// `path` is diagnostic only: a rejected value is useless to debug without knowing which
-// key held it, and this guard sits under a deeply nested extraction tree.
-export function canonicalizeJson(value, path = "$") {
-  if (value === null || typeof value === "boolean" || typeof value === "string") {
-    return JSON.stringify(value);
-  }
-  if (typeof value === "number") {
-    if (!Number.isFinite(value)) throw new TypeError(`Canonical JSON cannot contain non-finite numbers at ${path}`);
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((item, index) => canonicalizeJson(item, `${path}[${index}]`)).join(",")}]`;
-  }
-  if (value && typeof value === "object") {
-    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalizeJson(value[key], `${path}.${key}`)}`).join(",")}}`;
-  }
-  throw new TypeError(`Canonical JSON cannot contain ${typeof value} at ${path}`);
-}
-
-export function sha256(value) {
-  const input = typeof value === "string" || Buffer.isBuffer(value) ? value : canonicalizeJson(value);
-  return createHash("sha256").update(input).digest("hex");
-}
-
-export function semanticContent(value, key = "") {
-  if (Array.isArray(value)) return value.map((item) => semanticContent(item));
-  if (!value || typeof value !== "object") {
-    if (typeof value === "string" && (key === "absolutePath" || key.endsWith("AbsolutePath")) && path.isAbsolute(value)) {
-      return path.basename(value);
-    }
-    return value;
-  }
-  const result = {};
-  for (const childKey of Object.keys(value).sort()) {
-    if (NON_SEMANTIC_KEYS.has(childKey)) continue;
-    if (childKey === "hash" || childKey === "manifestHash" || childKey === "cacheKey") continue;
-    result[childKey] = semanticContent(value[childKey], childKey);
-  }
-  return result;
-}
-
-export function semanticHash(artifact, dependencyHashes = []) {
-  return sha256({
-    artifact: semanticContent(artifact),
-    dependencyHashes: [...dependencyHashes].sort(),
-  });
-}
-
-export function createDecisionRequest({ id, decisionType, allowedChoices, evidenceRefs = [], detectorVersions = {}, responseSchema = {} }) {
-  if (!id || !decisionType || !allowedChoices?.length) throw new Error("A decision request requires id, decisionType, and allowedChoices");
-  const request = {
-    schemaVersion: EXTRACTION_SCHEMA_VERSION,
-    kind: "decision-request",
-    id,
-    decisionType,
-    allowedChoices,
-    evidenceRefs,
-    detectorVersions,
-    responseSchema,
-    cacheKey: "",
-  };
-  request.cacheKey = semanticHash(request);
-  assertValidArtifact(request, "decision-request");
-  return request;
-}
-
-export function applyDecisionPatch(request, patch) {
-  assertValidArtifact(request, "decision-request");
-  assertValidArtifact(patch, "decision-patch");
-  if (patch.requestId !== request.id) throw new Error(`Decision patch ${patch.requestId} does not match ${request.id}`);
-  if (!request.allowedChoices.some((choice) => canonicalizeJson(choice) === canonicalizeJson(patch.choice))) {
-    throw new Error("Decision patch choice is outside the allowed typed choices");
-  }
-  return { requestId: request.id, cacheKey: request.cacheKey, choice: patch.choice, confidence: patch.confidence, reasonCodes: patch.reasonCodes };
-}
-
-export function createGap({
-  id,
-  ownerUnitId,
-  scope = "local",
-  missingFields = [],
-  reason,
-  evidenceRefs = [],
-  confidence = "low",
-  dependencyClosure = [],
-  affectedAcceptance = [],
-  assumptions = [],
-  omissions = [],
-  unblockAction = null,
-}) {
-  if (!id || !ownerUnitId || !reason) throw new Error("A gap requires id, ownerUnitId, and reason");
-  if (!new Set(["local", "global"]).has(scope)) throw new Error(`Invalid gap scope: ${scope}`);
-  return {
-    schemaVersion: EXTRACTION_SCHEMA_VERSION,
-    kind: "extraction-gap",
-    id,
-    ownerUnitId,
-    scope,
-    status: scope === "global" ? "global-blocker" : "recoverable",
-    missingFields,
-    reason,
-    evidenceRefs,
-    confidence,
-    dependencyClosure: [...new Set([ownerUnitId, ...dependencyClosure])],
-    affectedAcceptance,
-    attempts: [],
-    remainingAttempts: scope === "global" ? 0 : MAX_GAP_RECOVERY_ATTEMPTS,
-    assumptions,
-    omissions,
-    unblockAction,
-    userDecision: null,
-  };
-}
-
-export function recordGapAttempt(gap, { tactic, evidenceRefs = [], outcome = "failed", producedNewEvidence = false, note = "" }) {
-  if (gap.scope === "global") return gap;
-  if (["provisional", "resolved", "needs-user-decision"].includes(gap.status) || gap.remainingAttempts === 0) return gap;
-  if (!tactic) throw new Error("A gap recovery attempt requires a tactic");
-  const previousSameTactic = gap.attempts.some((attempt) => attempt.tactic === tactic && !attempt.producedNewEvidence);
-  if (previousSameTactic && !producedNewEvidence) return gap;
-  const countsAgainstBudget = outcome !== "resolved";
-  const attempts = [...gap.attempts, { tactic, evidenceRefs, outcome, producedNewEvidence, countsAgainstBudget, note }];
-  const consumed = attempts.filter((attempt) => attempt.countsAgainstBudget && attempt.outcome !== "resolved").length;
-  const resolved = outcome === "resolved";
-  const remainingAttempts = Math.max(0, MAX_GAP_RECOVERY_ATTEMPTS - consumed);
-  return {
-    ...gap,
-    attempts,
-    remainingAttempts,
-    status: resolved ? "resolved" : remainingAttempts === 0 ? "provisional" : "recoverable",
-  };
-}
-
-export function validateArtifact(artifact, expectedKind = artifact?.kind) {
-  const errors = [];
-  if (!artifact || typeof artifact !== "object" || Array.isArray(artifact)) errors.push("artifact must be an object");
-  if (!ARTIFACT_KINDS.has(expectedKind)) errors.push(`unsupported artifact kind: ${expectedKind}`);
-  if (artifact?.kind !== expectedKind) errors.push(`kind must be ${expectedKind}`);
-  if (artifact?.schemaVersion !== EXTRACTION_SCHEMA_VERSION) errors.push(`schemaVersion must be ${EXTRACTION_SCHEMA_VERSION}`);
-  if (ARTIFACT_KINDS.has(expectedKind)) {
-    const schemaInput = ["page-resolution", "page-capture", "foundation", "metadata", "shared-chrome", "unit"].includes(expectedKind) && !artifact?.hash
-      ? { ...artifact, hash: "0".repeat(64) }
-      : artifact;
-    const generated = validateGeneratedArtifact(schemaInput, expectedKind);
-    errors.push(...generated.errors.map((error) => `schema ${error}`));
-  }
-  const allowed = ALLOWED_FIELDS[expectedKind];
-  if (allowed && artifact && typeof artifact === "object") {
-    for (const key of Object.keys(artifact)) if (!allowed.has(key)) errors.push(`unknown field: ${key}`);
-  }
-  if (expectedKind === "page-resolution") {
-    if (artifact.pageKey !== "home") errors.push("pageKey must be home");
-    if (!artifact.source?.requestedUrl || !artifact.source?.resolvedUrl) errors.push("requestedUrl and resolvedUrl are required");
-    if (artifact.destinationRoute !== "/") errors.push("destinationRoute must be /");
-  }
-  if (["foundation", "metadata", "shared-chrome", "unit"].includes(expectedKind)) {
-    if (!artifact.id) errors.push("id is required");
-    if (!["accepted", "provisional"].includes(artifact.status)) errors.push("status must be accepted or provisional");
-    if (!Array.isArray(artifact.gapRefs)) errors.push("gapRefs must be an array");
-    if (artifact.status === "provisional" && artifact.gapRefs?.length === 0) errors.push("provisional artifacts require gapRefs");
-  }
-  if (expectedKind === "extraction-gap") {
-    if (!artifact.id || !artifact.ownerUnitId || !artifact.reason) errors.push("gap id, ownerUnitId, and reason are required");
-    if (!["local", "global"].includes(artifact.scope)) errors.push("gap scope must be local or global");
-    if (!Array.isArray(artifact.attempts)) errors.push("gap attempts must be an array");
-  }
-  if (expectedKind === "extraction-manifest") {
-    if (!artifact.captureId || !Array.isArray(artifact.specs) || !Array.isArray(artifact.gaps)) errors.push("manifest captureId, specs, and gaps are required");
-    if (artifact.gaps?.some((gap) => gap.scope === "global" && gap.status !== "resolved")) errors.push("manifest cannot freeze with an unresolved global blocker");
-  }
-  if (expectedKind === "decision-request") {
-    if (!artifact.id || !artifact.decisionType || !artifact.allowedChoices?.length || !artifact.cacheKey) errors.push("decision request is incomplete");
-  }
-  if (expectedKind === "decision-patch") {
-    if (!artifact.requestId || !artifact.reasonCodes?.length || !["high", "medium", "low"].includes(artifact.confidence)) errors.push("decision patch is incomplete");
-  }
-  return { ok: errors.length === 0, errors };
-}
-
-export function assertValidArtifact(artifact, expectedKind = artifact?.kind) {
-  const result = validateArtifact(artifact, expectedKind);
-  if (!result.ok) throw new Error(`${expectedKind} validation failed: ${result.errors.join("; ")}`);
-  return artifact;
-}
-
-export function freezeSpec(spec, { dependencyHashes = [], gapIds = spec.gapRefs || [] } = {}) {
-  assertValidArtifact(spec, spec.kind);
-  const frozen = {
-    ...spec,
-    gapRefs: [...new Set(gapIds)].sort(),
-    dependencyHashes: [...dependencyHashes].sort(),
-  };
-  frozen.hash = semanticHash(frozen, frozen.dependencyHashes);
-  return Object.freeze(frozen);
-}
-
-export function createExtractionManifest({ captureId, pageResolution, pageCapture, specs, gaps = [], observationRefs = [], budgets = {} }) {
-  const unresolvedGlobal = gaps.filter((gap) => gap.scope === "global" && gap.status !== "resolved");
-  if (unresolvedGlobal.length) {
-    const error = new Error(`Cannot freeze extraction manifest: ${unresolvedGlobal.map((gap) => gap.id).join(", ")}`);
-    error.code = "EXTRACTION_GLOBAL_BLOCKER";
-    error.gaps = unresolvedGlobal;
-    throw error;
-  }
-  const specEntries = [...specs]
-    .map((spec) => ({ id: spec.id, kind: spec.kind, status: spec.status, hash: spec.hash, gapRefs: spec.gapRefs || [] }))
-    .sort((a, b) => a.id.localeCompare(b.id));
-  const manifest = {
-    schemaVersion: EXTRACTION_SCHEMA_VERSION,
-    kind: "extraction-manifest",
-    captureId,
-    pageKey: "home",
-    pageResolution: { id: pageResolution.id, hash: pageResolution.hash },
-    pageCapture: { id: pageCapture.id, hash: pageCapture.hash },
-    observationRefs: [...observationRefs].sort((a, b) => a.ref.localeCompare(b.ref)),
-    specs: specEntries,
-    gaps: gaps.map((gap) => ({ id: gap.id, ownerUnitId: gap.ownerUnitId, scope: gap.scope, status: gap.status })).sort((a, b) => a.id.localeCompare(b.id)),
-    budgets: { ...EXTRACTION_BUDGETS, ...budgets },
-    status: pageCapture.status === "provisional" || specEntries.some((spec) => spec.status === "provisional") ? "done_with_gaps" : "accepted",
-  };
-  manifest.manifestHash = semanticHash(manifest, specEntries.map((entry) => entry.hash));
-  assertValidArtifact(manifest, "extraction-manifest");
-  return Object.freeze(manifest);
-}
-
-export async function verifyFrozenManifest(extractionDir) {
-  const manifest = JSON.parse(await readFile(path.join(extractionDir, "extraction-manifest.json"), "utf8"));
-  assertValidArtifact(manifest, "extraction-manifest");
-  const failures = [];
-  const pageResolution = JSON.parse(await readFile(path.join(extractionDir, "page-resolution.spec.json"), "utf8"));
-  const pageCapture = JSON.parse(await readFile(path.join(extractionDir, "page-capture.spec.json"), "utf8"));
-  const gapArtifact = JSON.parse(await readFile(path.join(extractionDir, "extraction-gaps.json"), "utf8"));
-  const gaps = gapArtifact.gaps || [];
-  const gapIds = new Set();
-  for (const gap of gaps) {
-    try { assertValidArtifact(gap, "extraction-gap"); }
-    catch (error) { failures.push(`${gap.id || "unknown gap"}: ${error.message}`); }
-    if (gapIds.has(gap.id)) failures.push(`duplicate gap id: ${gap.id}`);
-    gapIds.add(gap.id);
-  }
-  const manifestGapProjection = gaps
-    .map((gap) => ({ id: gap.id, ownerUnitId: gap.ownerUnitId, scope: gap.scope, status: gap.status }))
-    .sort((a, b) => a.id.localeCompare(b.id));
-  if (canonicalizeJson(manifestGapProjection) !== canonicalizeJson(manifest.gaps)) failures.push("manifest gap projection does not match extraction-gaps.json");
-  const resolutionHash = semanticHash(pageResolution, pageResolution.dependencyHashes || []);
-  const captureHash = semanticHash(pageCapture, pageCapture.dependencyHashes || []);
-  if (resolutionHash !== manifest.pageResolution.hash) failures.push(`page resolution: expected ${manifest.pageResolution.hash}, got ${resolutionHash}`);
-  if (captureHash !== manifest.pageCapture.hash) failures.push(`page capture: expected ${manifest.pageCapture.hash}, got ${captureHash}`);
-  for (const entry of manifest.observationRefs) {
-    const absolute = path.resolve(extractionDir, entry.ref);
-    const extractionRoot = `${path.resolve(extractionDir)}${path.sep}`;
-    if (!absolute.startsWith(extractionRoot)) {
-      failures.push(`observation ${entry.ref}: path escapes extraction directory`);
-      continue;
-    }
-    try {
-      const observation = JSON.parse(await readFile(absolute, "utf8"));
-      const actual = semanticHash(observation);
-      if (actual !== entry.hash) failures.push(`observation ${entry.ref}: expected ${entry.hash}, got ${actual}`);
-    } catch (error) {
-      failures.push(`observation ${entry.ref}: ${error.code === "ENOENT" ? "file missing" : error.message}`);
-    }
-  }
-  const knownHashes = new Set([resolutionHash, captureHash, ...manifest.specs.map((entry) => entry.hash)]);
-  for (const gapRef of [...(pageResolution.gapRefs || []), ...(pageCapture.gapRefs || [])]) {
-    if (!gapIds.has(gapRef)) failures.push(`page artifact: unknown gap ref ${gapRef}`);
-  }
-  for (const entry of manifest.specs) {
-    const file = await findSpecFile(extractionDir, entry.id);
-    if (!file) {
-      failures.push(`${entry.id}: file missing`);
-      continue;
-    }
-    const spec = JSON.parse(await readFile(file, "utf8"));
-    const actual = semanticHash(spec, spec.dependencyHashes || []);
-    if (actual !== entry.hash) failures.push(`${entry.id}: expected ${entry.hash}, got ${actual}`);
-    if (canonicalizeJson([...(spec.gapRefs || [])].sort()) !== canonicalizeJson([...(entry.gapRefs || [])].sort())) failures.push(`${entry.id}: manifest gap refs do not match spec`);
-    for (const gapRef of spec.gapRefs || []) if (!gapIds.has(gapRef)) failures.push(`${entry.id}: unknown gap ref ${gapRef}`);
-    if (spec.status === "provisional" && !(spec.gapRefs || []).length) failures.push(`${entry.id}: provisional spec is not gap-backed`);
-    for (const dependencyHash of spec.dependencyHashes || []) {
-      if (!knownHashes.has(dependencyHash)) failures.push(`${entry.id}: unknown dependency hash ${dependencyHash}`);
-    }
-  }
-  const manifestHash = semanticHash(manifest, manifest.specs.map((entry) => entry.hash));
-  if (manifestHash !== manifest.manifestHash) failures.push(`manifest: expected ${manifest.manifestHash}, got ${manifestHash}`);
-  return { ok: failures.length === 0, failures, manifest };
-}
-
-async function findSpecFile(extractionDir, id) {
-  const indexPath = path.join(extractionDir, "spec-index.json");
-  try {
-    const index = JSON.parse(await readFile(indexPath, "utf8"));
-    return index[id] ? path.join(extractionDir, index[id]) : null;
-  } catch {
-    return null;
-  }
-}
-
-export async function writeFrozenExtraction({ extractionDir, pageResolution, pageCapture, specs, gaps, manifest, specPaths }) {
-  await ensureDir(extractionDir);
-  await writeJson(path.join(extractionDir, "page-resolution.spec.json"), pageResolution);
-  await writeJson(path.join(extractionDir, "page-capture.spec.json"), pageCapture);
-  for (const gap of gaps) assertValidArtifact(gap, "extraction-gap");
-  await writeJson(path.join(extractionDir, "extraction-gaps.json"), {
-    schemaVersion: EXTRACTION_SCHEMA_VERSION,
-    gaps,
-  });
-  const index = {};
-  for (const { spec, relativePath } of specPaths) {
-    await writeJson(path.join(extractionDir, relativePath), spec);
-    index[spec.id] = relativePath;
-  }
-  await writeJson(path.join(extractionDir, "spec-index.json"), index);
-  await writeJson(path.join(extractionDir, "extraction-manifest.json"), manifest);
-}

package/skills/wix-headless-replatform/scripts/lib/extraction-detectors.mjs

@@ -1,243 +0,0 @@
-import { canonicalizeJson, sha256 } from "./extraction-contract.mjs";
-import { validateGeneratedArtifact } from "./extraction-validators.generated.mjs";
-
-export const DETECTOR_ENSEMBLE_VERSION = "0083.1";
-export const HIGH_CONFIDENCE_MIN_PRECISION = 0.95;
-
-const KNOWN_KINDS = new Set([
-  "accordion", "banner", "button", "button-group", "card", "card-collection",
-  "category-strip", "cta-strip", "footer", "form", "gallery", "header", "hero",
-  "marquee", "menu", "navigation", "promo-band", "repeater", "reviews", "rich-text",
-  "stat-group", "static-content", "tabs", "text-media",
-]);
-
-export function detectUnitCandidates(value = {}, { unitKind = "section", evidenceRef = "" } = {}) {
-  const candidates = [];
-  const add = (detectorId, candidate) => {
-    if (!candidate?.kind) return;
-    const artifact = {
-      schemaVersion: DETECTOR_ENSEMBLE_VERSION,
-      detectorId,
-      detectorVersion: DETECTOR_ENSEMBLE_VERSION,
-      unitKind,
-      evidenceRefs: evidenceRef ? [evidenceRef] : [],
-      variant: candidate.variant || "default",
-      score: clamp(candidate.score),
-      signals: [...new Set(candidate.signals || [])].sort(),
-      kind: normalizeKind(candidate.kind),
-    };
-    const validation = validateGeneratedArtifact(artifact, "candidate");
-    if (!validation.ok) throw new Error(`Candidate validation failed: ${validation.errors.join("; ")}`);
-    candidates.push(artifact);
-  };
-
-  const declaredKind = value.kind || value.classification?.kind;
-  const declaredVariant = value.variant || value.classification?.variant;
-  if (declaredKind) {
-    const declaredConfidence = normalizeConfidenceValue(value.classification?.confidence ?? value.confidence);
-    add("declared-observation", {
-      kind: declaredKind,
-      variant: declaredVariant,
-      score: declaredConfidence ?? (KNOWN_KINDS.has(normalizeKind(declaredKind)) ? 0.82 : 0.58),
-      signals: ["observed-kind", declaredVariant ? "observed-variant" : ""].filter(Boolean),
-    });
-  }
-
-  const semantic = semanticCandidate(value);
-  if (semantic) add("semantic-aria", semantic);
-  const structural = structuralCandidate(value);
-  if (structural) add("structure-cardinality", structural);
-  const behavior = behaviorCandidate(value);
-  if (behavior) add("behavior-state", behavior);
-  const visual = visualCandidate(value);
-  if (visual) add("layout-visual", visual);
-
-  if (!candidates.length) add("fallback-static", {
-    kind: "static-content",
-    variant: "default",
-    score: 0.35,
-    signals: ["no-qualified-detector"],
-  });
-  return candidates.sort((a, b) => b.score - a.score || a.detectorId.localeCompare(b.detectorId));
-}
-
-export function resolveCandidateEnsemble(candidates, calibration = {}) {
-  if (!Array.isArray(candidates) || !candidates.length) throw new Error("Candidate ensemble requires at least one candidate");
-  const groups = new Map();
-  for (const candidate of candidates) {
-    const key = candidate.kind;
-    const group = groups.get(key) || { kind: candidate.kind, variant: candidate.variant, candidates: [], detectors: new Set(), scoreTotal: 0 };
-    group.candidates.push(candidate);
-    group.detectors.add(candidate.detectorId);
-    group.scoreTotal += candidate.score;
-    if (candidate.score > Math.max(...group.candidates.slice(0, -1).map((entry) => entry.score), -1)) group.variant = candidate.variant;
-    groups.set(key, group);
-  }
-  const ranked = [...groups.values()].map((group) => {
-    const max = Math.max(...group.candidates.map((candidate) => candidate.score));
-    const agreementBonus = Math.min(0.12, Math.max(0, group.detectors.size - 1) * 0.04);
-    const mean = group.scoreTotal / group.candidates.length;
-    return { ...group, aggregateScore: clamp(max * 0.68 + mean * 0.32 + agreementBonus) };
-  }).sort((a, b) => b.aggregateScore - a.aggregateScore || a.kind.localeCompare(b.kind));
-  const winner = ranked[0];
-  const runnerUp = ranked[1];
-  const margin = winner.aggregateScore - (runnerUp?.aggregateScore || 0);
-  const detectorCalibration = calibration[winner.kind] || {};
-  const highThreshold = detectorCalibration.highThreshold ?? 0.85;
-  const mediumThreshold = detectorCalibration.mediumThreshold ?? 0.60;
-  const highPrecision = detectorCalibration.highPrecision ?? (winner.detectors.size >= 2 ? HIGH_CONFIDENCE_MIN_PRECISION : 0);
-  const explicitHigh = winner.candidates.some((candidate) => candidate.detectorId === "declared-observation" && candidate.score >= 0.85);
-  const confidence = winner.aggregateScore >= highThreshold
-    && margin >= 0.08
-    && (highPrecision >= HIGH_CONFIDENCE_MIN_PRECISION || explicitHigh)
-      ? "high"
-      : winner.aggregateScore >= mediumThreshold && margin >= 0.03 ? "medium" : "low";
-  return {
-    kind: winner.kind,
-    variant: winner.variant,
-    confidence,
-    score: Number(winner.aggregateScore.toFixed(4)),
-    margin: Number(margin.toFixed(4)),
-    signals: [...new Set(winner.candidates.flatMap((candidate) => candidate.signals))].sort(),
-    candidates: candidates.map((candidate) => ({
-      schemaVersion: candidate.schemaVersion,
-      detectorId: candidate.detectorId,
-      detectorVersion: candidate.detectorVersion,
-      kind: candidate.kind,
-      variant: candidate.variant,
-      score: candidate.score,
-      signals: candidate.signals,
-      evidenceRefs: candidate.evidenceRefs,
-    })),
-    detectorVersions: Object.fromEntries(candidates.map((candidate) => [candidate.detectorId, candidate.detectorVersion])),
-  };
-}
-
-export function classifyObservedUnit(value, options = {}) {
-  return resolveCandidateEnsemble(detectUnitCandidates(value, options), options.calibration || {});
-}
-
-export function planRecursiveUnitJobs(sections = []) {
-  const jobs = [];
-  const evidenceOwners = new Map();
-  const ownershipConflicts = [];
-  const walk = (value, { id, parentUnitId, unitKind, order, evidenceRef, depth }) => {
-    if (depth > 12) throw new Error(`Recursive extraction depth exceeded for ${id}`);
-    const children = childValues(value);
-    const childIds = children.map((entry, index) => `${id}:component-${String(index + 1).padStart(3, "0")}`);
-    const job = { id, parentUnitId, unitKind, order, evidenceRef, depth, value, childIds };
-    jobs.push(job);
-    if (evidenceRef) {
-      const existing = evidenceOwners.get(evidenceRef);
-      if (existing && existing !== id) ownershipConflicts.push({ evidenceRef, owners: [existing, id].sort() });
-      else evidenceOwners.set(evidenceRef, id);
-    }
-    children.forEach((entry, index) => walk(entry.value, {
-      id: childIds[index],
-      parentUnitId: id,
-      unitKind: "component",
-      order: index + 1,
-      evidenceRef: `${evidenceRef}/${entry.key}/${entry.index}`,
-      depth: depth + 1,
-    }));
-  };
-  sections.forEach((section, index) => walk(section, {
-    id: section.id || `section-${String(index + 1).padStart(3, "0")}`,
-    parentUnitId: null,
-    unitKind: "section",
-    order: index + 1,
-    evidenceRef: `observations/page.json#/sections/${index}`,
-    depth: 0,
-  }));
-  return {
-    version: DETECTOR_ENSEMBLE_VERSION,
-    jobs,
-    ownership: [...evidenceOwners.entries()].map(([evidenceRef, ownerUnitId]) => ({ evidenceRef, ownerUnitId })).sort((a, b) => a.evidenceRef.localeCompare(b.evidenceRef)),
-    conflicts: dedupeConflicts(ownershipConflicts),
-    hash: sha256({ jobs: jobs.map(({ value, ...job }) => job), ownership: [...evidenceOwners.entries()] }),
-  };
-}
-
-function childValues(value) {
-  for (const key of ["modules", "components", "children"]) {
-    if (Array.isArray(value?.[key]) && value[key].some((item) => item && typeof item === "object")) {
-      return value[key].map((item, index) => ({ key, index, value: item })).filter((entry) => entry.value && typeof entry.value === "object");
-    }
-  }
-  return [];
-}
-
-function semanticCandidate(value) {
-  const role = String(value?.a11y?.role || value?.role || "").toLowerCase();
-  const tag = String(value?.tag || value?.domRef?.tag || "").toLowerCase();
-  if (tag === "header" || role === "banner") return candidate("header", "generic", 0.94, ["semantic-header"]);
-  if (tag === "footer" || role === "contentinfo") return candidate("footer", "site-footer", 0.96, ["semantic-footer"]);
-  if (tag === "nav" || role === "navigation") return candidate("navigation", "site-navigation", 0.95, ["semantic-navigation"]);
-  if (role === "tablist") return candidate("tabs", "tablist", 0.96, ["aria-tablist"]);
-  if (/button/.test(role) || tag === "button") return candidate("button", "native", 0.96, ["native-button"]);
-  return null;
-}
-
-function structuralCandidate(value) {
-  const counts = value?.counts || {};
-  const itemCount = value?.itemCount ?? value?.items?.length ?? value?.modules?.length ?? 0;
-  const imageCount = counts.images ?? value?.images?.length ?? 0;
-  const headingCount = counts.headings ?? (value?.heading ? 1 : 0);
-  const text = `${value?.heading || ""} ${value?.text || ""}`;
-  if (itemCount >= 3 && imageCount >= 3) return candidate("card-collection", value?.capabilities?.isCarouselLike ? "card-carousel" : "card-grid", 0.84, ["repeated-items", "repeated-media"]);
-  if (itemCount >= 2) return candidate("repeater", "collection", 0.72, ["repeated-items"]);
-  if (imageCount >= 1 && headingCount >= 1 && text.trim().length >= 20) return candidate("text-media", "media-left", 0.74, ["media", "heading", "copy"]);
-  return null;
-}
-
-function behaviorCandidate(value) {
-  const behavior = value?.behavior || value?.interaction || {};
-  const text = canonicalizeJson(behavior).toLowerCase();
-  if (/aria-?expanded|disclosure|accordion/.test(text)) return candidate("accordion", "disclosure", 0.92, ["expanded-state", "toggle-trigger"]);
-  if (/aria-selected|tablist|tabpanel/.test(text)) return candidate("tabs", "tablist", 0.93, ["selected-state", "tabpanel"]);
-  if (/carousel|slide|scroll-snap/.test(text)) return candidate("gallery", "carousel", 0.82, ["slide-state"]);
-  if (/menuitem|aria-haspopup|dropdown/.test(text)) return candidate("menu", "dropdown", 0.88, ["menu-state"]);
-  return null;
-}
-
-function visualCandidate(value) {
-  const classText = `${value?.className || ""} ${value?.idAttr || ""} ${value?.variant || ""}`.toLowerCase();
-  const layout = value?.layoutEvidence || value?.layout || {};
-  const layers = value?.layers || layout?.background?.layers || [];
-  if (/hero|masthead|billboard/.test(classText) || value?.a11y?.headingLevels?.includes?.(1) && layers.length) {
-    return candidate("hero", /carousel|slider/.test(classText) ? "carousel-hero" : "generic-hero", 0.80, ["first-view-dominance", layers.length ? "layered-background" : ""]);
-  }
-  if (/marquee|ticker/.test(classText)) return candidate("marquee", "horizontal", 0.83, ["visual-marquee"]);
-  if (/gallery/.test(classText)) return candidate("gallery", "grid", 0.78, ["visual-gallery"]);
-  return null;
-}
-
-function candidate(kind, variant, score, signals) {
-  return { kind, variant, score, signals: signals.filter(Boolean) };
-}
-
-function normalizeKind(value) {
-  return String(value || "static-content").trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "static-content";
-}
-
-function normalizeConfidenceValue(value) {
-  if (typeof value === "number") return clamp(value);
-  if (value === "high") return 0.96;
-  if (value === "medium") return 0.72;
-  if (value === "low") return 0.40;
-  return null;
-}
-
-function clamp(value) {
-  return Number(Math.max(0, Math.min(1, Number(value) || 0)).toFixed(4));
-}
-
-function dedupeConflicts(conflicts) {
-  const seen = new Set();
-  return conflicts.filter((conflict) => {
-    const key = canonicalizeJson(conflict);
-    if (seen.has(key)) return false;
-    seen.add(key);
-    return true;
-  });
-}