open-standards/wai/quantum-studio/src/views/render.js

// The six views an agent host draws, from the Studio's own components: a
// circuit, a result with its verdict, a receipt checked here, a critique, a
// resource estimate's frontier, and a device target's map.
//
// Each draws a tool's answer: the call's arguments, its result (the
// structured content), and what the server's engine computed for the view to
// draw (the result's `_meta["science.transaction.wai/quantum-view"]`: the
// program's layout and its description in words, a target's map). A view
// computes no physics and states no number the answer does not hold. The one
// thing it computes is the receipt check, with the engine's own code, here.
import { el } from '../dom.js';
import { circuitSvg, mark } from '../circuit-svg.js';
import { verdictLine } from '../verdict-view.js';
import { chips, fidelityChip } from '../critique-view.js';
import { frontierSvg, compact as count, duration } from '../estimate-view.js';
import { couplingSvg, deviceBlock, legend, table } from '../device.js';
import { METHOD_NAMES, ACCURACY, accuracyExtras, countsBlock, expectationsBlock, amplitudesBlock, energyText } from '../result-parts.js';
import { verify } from './check.js';

export const META = 'science.transaction.wai/quantum-view';

const block = (k, ...kids) => el('div', { class: 'qs-block' }, el('div', { class: 'qs-k', text: k }), ...kids);
const row = (k, v, attrs = {}) => el('tr', {}, el('th', { scope: 'row', text: k }), el('td', attrs, v));
const note = (text, attrs = {}) => el('p', { class: 'qs-note', ...attrs, text });

// What a receipt shows, and what it does not, as the engine's guide says it.
const RECEIPT_NOTE = 'A receipt shows that this key signed this request and this result; anyone can run the request again to compare. It does not say who holds the key, nor that the physics is right.';

// The circuit, drawn from the engine's layout, with its description in words.
export function circuitBlock(data, title = 'Circuit') {
  if (!data) return null;
  if (!data.layout) return data.why ? block(title, note(data.why, { id: 'wq-not-drawn' })) : null;
  const { svg, drawn, total } = circuitSvg(data.layout);
  const fig = el('div', { class: 'wq-circuit', id: 'wq-circuit' }, svg);
  return {
    svg,
    node: block(title, fig,
      drawn < total ? note(`The first ${drawn} of ${total} columns are drawn.`) : null,
      data.description ? el('details', { class: 'wq-words' }, el('summary', { text: 'The circuit in words' }), el('p', { class: 'qs-why', id: 'wq-description', text: data.description })) : null),
  };
}

// The program's text, folded.
function programBlock(src, title = 'Program') {
  if (!src) return null;
  return el('details', { class: 'wq-program' }, el('summary', { text: title }), el('pre', { class: 'wq-src', text: src }));
}

// The receipt of `job` ({request, result}) checked in this view, by the
// engine's own code. `checked` resolves to the check's answer.
export function receiptBlock(job, { title = 'Receipt', what = 'this request and this result' } = {}) {
  const rc = job?.result?.receipt || {};
  const badge = el('span', { class: 'qs-badge', id: 'wq-receipt', 'data-receipt': 'checking', text: 'checking in this view…' });
  const signer = el('td', { class: 'mono', id: 'wq-signer', text: rc.key ? `${rc.key.slice(0, 16)}…` : 'no key named' });
  const by = el('td', { id: 'wq-checked-by', text: '…' });
  const node = block(title, el('table', { class: 'qs-table' }, el('tbody', {}, row('check', badge), el('tr', {}, el('th', { scope: 'row', text: 'signed by' }), signer), el('tr', {}, el('th', { scope: 'row', text: 'checked by' }), by))),
    note(RECEIPT_NOTE));
  const checked = (async () => {
    if (!job?.result?.receipt) {
      badge.dataset.receipt = 'unsealed';
      badge.textContent = 'no receipt';
      by.textContent = 'nothing to check';
      return { valid: false, error: 'no receipt' };
    }
    try {
      const v = await verify(job);
      if (v.error) throw new Error(v.error);
      badge.dataset.receipt = v.valid ? 'valid' : 'invalid';
      badge.className = `qs-badge ${v.valid ? 'ok' : 'bad'}`;
      badge.textContent = v.valid ? `✓ seals ${what}` : `✗ does not seal ${what}`;
      if (v.signer) signer.textContent = v.signer;
      by.textContent = v.form === 'WebAssembly' ? 'the engine, in this view, as WebAssembly' : 'the engine, in this view, translated to JavaScript: this host’s policy refuses WebAssembly';
      if (v.refused) by.title = v.refused;
      document.body.dataset.engine = v.form;
      return v;
    } catch (e) {
      badge.dataset.receipt = 'unchecked';
      badge.className = 'qs-badge bad';
      badge.textContent = 'not checked here';
      by.textContent = String(e?.message || e);
      return { valid: false, error: String(e?.message || e) };
    }
  })();
  return { node, checked };
}

// A refusal: what the engine said, its code and meaning, and its verdict.
function refusalBlocks(sc, res) {
  const msg = sc?.message || sc?.error || res?.content?.[0]?.text || 'refused';
  return [
    block('Refused', el('p', { class: 'qs-warn', id: 'wq-refusal', text: msg }),
      sc?.code ? note(`${sc.code} · ${sc.outcome || 'refused'}: ${sc.meaning || ''}`, { id: 'wq-code' }) : null),
    sc?.verdict ? block('Verdict', verdictLine(sc.verdict, { sealed: false, id: 'wq-verdict' })) : null,
  ];
}

// ---- the views ----

// A result: the method and why, its accuracy, the verdict the receipt seals,
// the circuit, the numbers, a device target's account, the energy, and the
// receipt checked here.
function result({ res, data }) {
  const sc = res.structuredContent || {};
  if (res.isError || sc.error || sc.code) return { blocks: refusalBlocks(sc, res), state: 'refused' };
  if (sc.status === 'queued' || sc.status === 'running') return { blocks: [block('Running', note(`The job ${sc.id || ''} is ${sc.status} on the service; this view follows it.`, { id: 'wq-running' }))], state: 'running', poll: sc.id };
  const r = sc.result || {};
  const acc = r.accuracy || {};
  const extra = accuracyExtras(r);
  const circuit = circuitBlock(data);
  const rc = receiptBlock({ request: sc.request, result: r });
  const blocks = [
    block('Verdict', r.verdict ? verdictLine(r.verdict, { sealed: true, id: 'wq-verdict' }) : note('This result carries no verdict.')),
    block('Method', el('div', {}, el('b', { class: 'qs-method', id: 'wq-method', text: METHOD_NAMES[sc.method] || sc.method || '' }), el('span', { class: 'qs-why', text: ` ${sc.why || ''}` }))),
    block('Accuracy', el('div', {}, el('span', { class: 'qs-badge ok', id: 'wq-accuracy', text: acc.class || '?' }), el('span', { class: 'qs-why', text: ` ${ACCURACY[acc.class] || ''}${extra.length ? ` ${extra.join(', ')}.` : ''}` })),
      r.warning ? el('p', { class: 'qs-warn', text: r.warning }) : null),
    circuit?.node,
    r.counts ? countsBlock(r) : null,
    r.expectations ? expectationsBlock(r) : null,
    r.amplitudes ? amplitudesBlock(r) : null,
    r.target ? deviceBlock(r.target, r.ideal) : null,
    block('Energy', el('span', { class: 'qs-why', id: 'wq-energy', text: energyText(r.energy || {}) })),
    rc.node,
    programBlock(sc.request?.qasm),
  ];
  return { blocks, checked: rc.checked, state: 'shown' };
}

// A receipt: the job given checked here, beside the server's own answer.
function receipt({ args, res }) {
  const sc = res.structuredContent || {};
  const job = args?.job ? args.job : { request: args?.request, result: args?.result };
  if (res.isError && !job?.result) return { blocks: refusalBlocks(sc, res), state: 'refused' };
  const r = job?.result || {};
  const rc = receiptBlock(job, { title: 'Checked in this view' });
  const server = sc.valid === true ? 'it verifies' : sc.valid === false ? 'it does not verify' : 'no answer';
  const agree = el('span', { class: 'qs-badge', id: 'wq-agree', text: 'comparing…' });
  rc.checked.then((v) => {
    if (v.error || typeof sc.valid !== 'boolean') { agree.textContent = 'not compared'; agree.dataset.agree = 'unknown'; return; }
    const same = v.valid === sc.valid;
    agree.dataset.agree = same ? 'yes' : 'no';
    agree.className = `qs-badge ${same ? 'ok' : 'bad'}`;
    agree.textContent = same ? 'the server and this view agree' : 'the server and this view disagree: trust neither until it is checked again';
  });
  const top = r.counts ? Object.entries(r.counts).sort((a, b) => b[1] - a[1]).slice(0, 4).map(([k, n]) => `${k}: ${n}`).join(', ') : '';
  const blocks = [
    rc.node,
    block('The server’s check', el('table', { class: 'qs-table' }, el('tbody', {}, row('answer', server, { id: 'wq-server-valid' }), row('agreement', agree)))),
    block('What it seals', el('table', { class: 'qs-table' }, el('tbody', {},
      job?.request?.qasm ? row('program', `${job.request.qasm.split('\n').filter((l) => l.trim()).length} lines`) : null,
      r.method ? row('method', METHOD_NAMES[r.method] || r.method) : null,
      r.accuracy?.class ? row('accuracy', r.accuracy.class) : null,
      top ? row('counts', top) : null,
      r.verdict ? row('verdict', verdictLine(r.verdict, { sealed: true, id: 'wq-verdict' })) : null,
      r.format ? row('format', r.format) : null))),
    programBlock(job?.request?.qasm),
  ];
  return { blocks, checked: rc.checked, state: 'shown' };
}

// A circuit: a program drawn, linted, repaired or compiled.
function circuit({ res, data }) {
  const sc = res.structuredContent || {};
  const tool = data?.tool || '';
  if (res.isError && !sc.repairs) return { blocks: [...refusalBlocks(sc, res), programBlock(data?.program)], state: 'refused' };
  const c = circuitBlock(data);
  const blocks = [];
  let checked;
  if (sc.verdict) blocks.push(block('Verdict', verdictLine(sc.verdict, { sealed: false, id: 'wq-verdict' })));
  if (sc.result?.certificate) {
    // A compile: the passes, each with its check, and the certificate's seal.
    const cert = sc.result.certificate;
    const e = cert.epsilon || {};
    const counts = (x) => `${x?.gates ?? '—'} gates, ${x?.cnots ?? '—'} CNOTs, ${x?.t_count ?? '—'} T, ${x?.rotations ?? '—'} rotations`;
    blocks.push(block('Compiled', el('p', { class: 'qs-why', id: 'wq-compile', text: `To ${cert.basis} at level ${cert.level}: ${cert.verdict}. Within ${e.bound} of the program in the operator norm (budget ${e.budget}).` }),
      el('table', { class: 'qs-table', id: 'wq-passes' }, el('thead', {}, el('tr', {}, ...['pass', 'before', 'after', 'check'].map((t) => el('th', { text: t })))),
        el('tbody', {}, ...(cert.passes || []).map((p) => el('tr', {}, el('th', { scope: 'row', text: p.pass }), el('td', { text: counts(p.before) }), el('td', { text: counts(p.after) }), el('td', { text: `${p.check?.verdict || ''}${p.check?.distance ? ` (${Number(p.check.distance).toExponential(2)})` : ''}` }))))),
      cert.reading ? note(cert.reading) : null));
    const rc = receiptBlock({ request: sc.request, result: sc.result }, { title: 'Certificate', what: 'this compile' });
    checked = rc.checked;
    if (c) blocks.push(c.node);
    blocks.push(rc.node);
  } else if (Array.isArray(sc.repairs)) {
    // A repair: each change with its code and lines, and what needs a person.
    blocks.push(block('Repairs', sc.repairs.length ? el('ul', { class: 'qs-smells', id: 'wq-repairs' }, ...sc.repairs.map((r) => el('li', { class: 'qs-smell', 'data-code': r.code },
      el('span', { class: 'qs-smell-text', text: `${r.code}: ${r.rule}` }),
      el('span', { class: 'qs-smell-where qs-note', text: (r.edits || []).map((x) => `line ${x.line}: ${x.before} → ${x.after}`).join('; ') })))) : note('Nothing to repair.')));
    if (sc.needs_person?.length) blocks.push(block('Needs a person', el('ul', { class: 'qs-smells' }, ...sc.needs_person.map((p) => el('li', { class: 'qs-smell' }, el('span', { class: 'qs-smell-text', text: `${p.code}: ${p.message || p.advice || ''}` }))))));
    if (c) blocks.push(c.node);
  } else if (sc.ok === false) {
    blocks.push(block('Refused', el('p', { class: 'qs-warn', id: 'wq-refusal', text: sc.error }), note(`${sc.code} on line ${sc.line}`, { id: 'wq-code' })));
  } else {
    if (sc.qubits != null) blocks.push(block('Shape', el('p', { class: 'qs-why', id: 'wq-shape', text: `${sc.qubits} qubits, ${sc.gates} gates, ${sc.bits} classical bits, ${sc.measured} measured` })));
    if (c) blocks.push(c.node);
  }
  if (!c && tool !== 'compile_qasm' && data?.why) blocks.push(block('Circuit', note(data.why, { id: 'wq-not-drawn' })));
  blocks.push(programBlock(data?.program, tool === 'compile_qasm' ? 'Compiled program' : 'Program'));
  return { blocks, checked, state: sc.ok === false ? 'refused' : 'shown' };
}

// A critique: the measures, the smells with their lines, marked on the circuit.
function critique({ res, data }) {
  const sc = res.structuredContent || {};
  if (res.isError || sc.ok === false) return { blocks: refusalBlocks(sc, res), state: 'refused' };
  const c = circuitBlock(data);
  const smells = el('ul', { class: 'qs-smells', id: 'wq-smells' }, ...(sc.smells || []).map((s) => {
    const li = el('li', { class: 'qs-smell', 'data-kind': s.kind, tabindex: '0' },
      el('span', { class: 'qs-smell-text', text: s.message }),
      el('span', { class: 'qs-smell-where qs-note', text: s.lines?.length ? `line${s.lines.length > 1 ? 's' : ''} ${s.lines.join(', ')}` : (s.qubits || []).map((q) => `q${q}`).join(' ') }));
    if (c) for (const [ev, on] of [['mouseenter', true], ['focusin', true], ['mouseleave', false], ['focusout', false]]) li.addEventListener(ev, () => mark(c.svg, 'qc-smell', on ? s.ops || [] : [], on ? s.qubits || [] : []));
    return li;
  }));
  const blocks = [
    block('Measures', el('div', { class: 'qs-chips', id: 'wq-measures' }, ...chips(sc), sc.clifford ? el('span', { class: 'qs-badge ok', text: 'Clifford' }) : null, fidelityChip(sc))),
    block(`Smells · ${(sc.smells || []).length}`, (sc.smells || []).length ? smells : note('None found.')),
    c?.node,
    sc.verdict ? block('Verdict', verdictLine(sc.verdict, { sealed: false, id: 'wq-verdict' })) : null,
  ];
  return { blocks, state: 'shown' };
}

// An estimate: the headline, the counts, the frontier, and every seal checked here.
function estimate({ res }) {
  const sc = res.structuredContent || {};
  if (res.isError || !sc.result) return { blocks: refusalBlocks(sc, res), state: 'refused' };
  const r = sc.result;
  const e = r.estimate || {};
  const c = r.counts || {};
  const points = r.frontier || [];
  const head = Math.max(0, points.findIndex((p) => p.headline));
  const pointed = note('Point at an estimate to read it.', { id: 'wq-point' });
  const svg = points.length ? frontierSvg(points, head, (i) => { const p = points[i]; pointed.textContent = `slowdown ${p.slowdown}: ${count(p.physical_qubits)} physical qubits, ${duration(p.runtime_s)}, distance ${p.distance}, ${p.factories} factories`; }) : null;
  const rc = receiptBlock({ request: sc.request, result: r }, { title: 'Seal', what: 'this estimate' });
  const blocks = [
    block('Estimate', el('p', { class: 'qs-why', id: 'wq-headline', text: `${count(e.physical_qubits)} physical qubits, ${e.factories} factories (${Math.round(100 * (e.factory_fraction || 0))}% of the qubits), ${duration(e.runtime_s)} at code distance ${e.distance}, on ${e.qubit} with the ${e.code}.` })),
    block('Logical counts', el('div', { class: 'qs-chips', id: 'wq-counts' }, ...[['logical_qubits', 'logical qubits'], ['t_gates', 'T'], ['toffolis', 'Toffolis'], ['rotations', 'rotations'], ['rotation_t', 'T in the rotations'], ['t_depth', 'T depth']].filter(([k]) => c[k] != null).map(([k, label]) => el('span', { class: 'qs-chip' }, el('b', { text: count(c[k]) }), ` ${label}`)))),
    svg ? block(`Frontier · ${points.length} estimate${points.length === 1 ? '' : 's'}`, el('div', { class: 'qs-frontier-figure', id: 'wq-frontier' }, svg), pointed) : null,
    rc.node,
    ...(r.notes || []).map((n) => note(n)),
  ];
  return { blocks, checked: rc.checked, state: 'shown' };
}

// A device target: its coupling map coloured by its errors, and its summary.
function target({ res, data }) {
  const sc = res.structuredContent || {};
  if (res.isError || sc.error) return { blocks: refusalBlocks(sc, res), state: 'refused' };
  const view = sc.view || data?.target_view;
  const map = view ? couplingSvg(view, { by: 'readout', width: 420 }) : null;
  const gates = (sc.gates || []).filter((g) => g.error).map((g) => `${g.gate} ${g.error.median}`).join(', ');
  const blocks = [
    block('Device target', el('table', { class: 'qs-table' }, el('tbody', {},
      row('target', sc.name, { id: 'wq-target-name' }),
      row('hash', sc.hash, { class: 'mono', id: 'wq-target-hash' }),
      row('qubits, pairs', `${sc.qubits}, ${sc.pairs}`),
      sc.native?.basis ? row('compiles to', sc.native.basis) : null,
      gates ? row('median errors', gates) : null,
      sc.calibration?.id ? row('calibration', sc.calibration.id) : null)),
      sc.source?.note ? note(sc.source.note) : null),
    map ? block('Coupling map', el('div', { class: 'qs-dev-map', id: 'wq-map' }, map.svg), legend(map.pairBounds, map.qubitBounds, map.colour), table(view)) : block('Coupling map', note('The answer holds no map to draw.')),
  ];
  return { blocks, state: 'shown' };
}

export const VIEWS = { result, receipt, circuit, critique, estimate, target };

export function render(view, input) {
  const f = VIEWS[view];
  if (!f) return { blocks: [note(`No view ${view}.`)], state: 'refused' };
  const out = f(input);
  return { ...out, blocks: out.blocks.filter(Boolean) };
}