@preventive/triage 1.0.0-alpha.13 → 1.0.0-alpha.15

package/report/src/write-md-finding.js

@@ -0,0 +1,273 @@
+// One finding as markdown: its heading, the facts that aren't prose as a
+// labelled list, then the narrative in the order a reader needs it. The
+// document (write-md.js) hands in the heading text and the depth; what a
+// finding CARRIES is read here, off the parser's object through
+// finding.js.
+//
+// Nothing is dropped for being unfamiliar to the viewer — a report's
+// status and branch, an audit's PoC state and commit land on the list
+// beside the facts every card shows, and each narrative field gets a
+// section rather than a bold label buried in a paragraph.
+//
+// A dedup group — one finding reported several times — is one heading
+// with a case under it per member, so the reader meets the finding once
+// and its reports as its cases.
+
+import { correctedVariants, descriptionSections, displayedSeverity, effectiveSeverity, evidenceNote, findingDisplayName, findingTitle, firstLine, hasSeverityCorrection, locationLabel, revalidateKindOf, runMetaLine, splitDescription, stripExportMarker } from './finding.js'
+import { COLOR_LABELS, SOURCE_LABELS, TRIAGE_LABELS, severityLabel } from './labels.js'
+import { autolink, code, heading, indentUnder, isHttpUrl, joinBlocks, link, plural, prose } from './md-text.js'
+import { isRepoSlug } from './meta.js'
+import { normalizeNewlines } from './md-structure.js'
+
+// A heading has to fit on a line, and a JSON finding whose description
+// is one paragraph is NAMED by that paragraph. Past this it is cut, and
+// the body carries the whole name (descriptionBlocks).
+const HEADING_MAX = 120
+
+export function findingHeading(f) {
+  const title = findingTitle(f) || locationLabel(f) || 'Untitled finding'
+  return title.length > HEADING_MAX ? `${title.slice(0, HEADING_MAX - 1).trimEnd()}…` : title
+}
+
+// A repository as a link — a github.com slug points at github.com, a
+// URL at itself, anything else stays the text it is.
+export function repoRef(repo) {
+  const s = String(repo ?? '').trim()
+  if (isHttpUrl(s)) return autolink(s)
+  return isRepoSlug(s) ? link(s, `https://github.com/${s}`) : s
+}
+
+// What produced the finding, as the document names it: a product, which
+// is one analyzer with no runs to tell apart, so its name is the whole
+// answer — or, out of the analyzer's own dump, the run itself (finding.js
+// runMetaLine). What a report filed a finding UNDER, Claude Security's
+// `**Category:**`, is not its analyzer and gets its own line.
+export function analyzerText(f, source, revalidation) {
+  if (source) return SOURCE_LABELS[source] ?? String(source)
+  return runMetaLine(f, revalidation)
+}
+
+// The narrative fields beyond the description, `[heading, field, pass]`
+// in the order the card reads them: what it means, how to trigger it,
+// how to fix it, then the analyzer's and the pass's remarks. The pass's
+// two travel with the revalidation layer (ctx.revalidation).
+const NARRATIVE = [
+  ['Impact', 'impact', false],
+  ['Reproduction', 'reproduction', false],
+  ['Recommendation', 'recommendation', false],
+  ['Confidence reasoning', 'confidenceReason', false],
+  ['Revalidation verdict', 'revalidateVerdict', true],
+  ['Revalidation recommendation', 'revalidateRecommendation', true],
+]
+
+// The plain facts a report may attach, `[label, field]`, printed as
+// written and under the name the report used, so a reader of the
+// original recognises each: Claude Security's `Status` / `Branch` /
+// `Date created`, Codex's `detected_at`, Piolium's `PoC status` /
+// `Variant of`, DeepSec's `Slug`. Strings and numbers only — an object
+// has no line to print on.
+const PLAIN_FIELDS = [
+  ['Status', 'status'], ['Branch', 'branch'], ['Date created', 'dateCreated'],
+  ['Detected at', 'detectedAt'], ['Committed at', 'committedAt'],
+  ['PoC status', 'pocStatus'], ['Variant of', 'parent'], ['Slug', 'slug'],
+  ['Priority', 'priority'],
+]
+// …and the ones that are paths or hashes, set in code.
+const CODE_FIELDS = [['Detailed report', 'reportPath'], ['Commit audited', 'auditedCommit']]
+
+// A fact is one line of the list, so a value that arrived with line
+// breaks (a wrapped Piolium bullet) is reflowed onto one — the break
+// would end the list. Prose keeps its lines (proseValue).
+function plainValue(v) {
+  if (typeof v === 'number') return Number.isFinite(v) ? String(v) : ''
+  return typeof v === 'string' ? v.replaceAll(/\s*\n\s*/gu, ' ').trim() : ''
+}
+
+function proseValue(v) {
+  return typeof v === 'string' ? v.trim() : ''
+}
+
+// The severity under the reader's lens, with a corrected finding's other
+// value beside it — the document has no toggle, so both are on the page —
+// and the per-report divergence a workspace merge can carry.
+function severityText(f, ctx) {
+  const original = ctx.severityMode === 'original'
+  let text = severityLabel(displayedSeverity(f, ctx.severityMode))
+  if (hasSeverityCorrection(f)) {
+    text += original
+      ? ` — corrected to ${severityLabel(effectiveSeverity(f))}`
+      : ` — corrected from ${severityLabel(f.severity)}`
+  }
+  const variants = correctedVariants(f)
+  if (variants) {
+    const list = Object.entries(variants).map(([r, v]) => `${r || 'this report'}: ${severityLabel(v?.severity)}`)
+    text += ` (varies across reports — ${list.join('; ')})`
+  }
+  if (f.critical === true) text += ' · flagged critical by the analyzer'
+  return text
+}
+
+function locationText(f, ctx) {
+  const label = locationLabel(f)
+  if (!label) return ''
+  const url = ctx.hooks.location(f)
+  const ref = isHttpUrl(url) ? link(code(label), url) : code(label)
+  const name = findingDisplayName(f)
+  return name ? `${ref} · ${code(name)}` : ref
+}
+
+// What the reader did with the finding: its triage bucket (or the
+// per-report ignore), its colour mark, its flag — one line.
+function triageText(a) {
+  if (!a) return ''
+  const parts = []
+  const bucket = TRIAGE_LABELS[a.triage] ?? (a.ignored ? TRIAGE_LABELS.ignored : '')
+  if (bucket) parts.push(bucket)
+  if (a.color) parts.push(`${COLOR_LABELS[a.color] ?? a.color} mark`)
+  if (a.flagged === true) parts.push('Flagged')
+  return parts.join(' · ')
+}
+
+// Whose revalidation pass a stamp came from, in the words this document
+// spells a producer with; an unknown key prints as itself. Written under
+// the stamp, so it travels with the layer and says nothing where the
+// finding's own report ran the pass.
+function sourceText(source) {
+  const s = plainValue(source)
+  return s ? SOURCE_LABELS[s] ?? s : ''
+}
+
+function commitText(f, ctx) {
+  const hash = plainValue(f.commitHash)
+  if (!hash) return ''
+  const url = ctx.hooks.commit(f)
+  return isHttpUrl(url) ? link(code(hash.slice(0, 7)), url) : code(hash)
+}
+
+// The labelled list under a finding's heading: every fact that isn't
+// prose, in the order the card's rail reads them, then the provenance
+// the report attached, then the id — the one fact that means nothing to
+// a reader and everything to the reader of the file, which keys stored
+// triage off it. A line is written only when its fact is there.
+function metaList(f, ctx, annotation) {
+  const rows = []
+  const add = (label, value) => { if (value) rows.push(`- **${label}:** ${value}`) }
+  add('Location', locationText(f, ctx))
+  add('Severity', severityText(f, ctx))
+  if (f.confidence !== undefined && f.confidence !== null) add('Confidence', `${f.confidence}/10`)
+  if (ctx.showAnalyzer) add('Analyzer', ctx.analyzerOf(f))
+  add('Category', plainValue(f.category))
+  const kind = ctx.revalidation ? revalidateKindOf(f) : ''
+  if (kind) add('Revalidation', kind === 'revalidation' ? 'the revalidation pass itself' : kind)
+  if (kind) add('Revalidated by', sourceText(f.revalidateSource))
+  add('Triage', triageText(annotation))
+  if (annotation?.fix) add('Fix', autolink(String(annotation.fix).trim()))
+  if (ctx.showReport) add('Report', code(ctx.hooks.report(f) ?? ''))
+  const repo = plainValue(f.repo?.github)
+  if (repo && repo !== ctx.repo) add('Repository', repoRef(repo))
+  add('Introduced in', commitText(f, ctx))
+  const found = plainValue(f.discoveredIn)
+  if (found && found !== String(f.file ?? '').trim()) add('Found while analyzing', code(found))
+  const npm = f.package?.npm
+  const pkg = plainValue(npm?.name)
+  if (pkg) add('Package', code(plainValue(npm.version) ? `${pkg}@${plainValue(npm.version)}` : pkg))
+  for (const [label, field] of PLAIN_FIELDS) add(label, plainValue(f[field]))
+  for (const [label, field] of CODE_FIELDS) add(label, code(plainValue(f[field])))
+  add('ID', code(plainValue(f.id)))
+  return rows.join('\n')
+}
+
+function section(depth, label, text) {
+  const body = prose(text)
+  return body ? `${heading(depth, label)}\n\n${body}` : heading(depth, label)
+}
+
+// The `## Evidence` rows as a loose numbered list: the reference, linked
+// where the caller can, and the report's note as its own paragraph under
+// it — loose, or a note sharing the reference's line would be reflowed
+// onto it.
+function evidenceList(f, ctx) {
+  const rows = Array.isArray(f.evidence) ? f.evidence : []
+  return rows.map((row, i) => {
+    const marker = `${i + 1}. `
+    const label = locationLabel(row)
+    const url = ctx.hooks.evidence(row, f, i)
+    let ref = ''
+    if (label) ref = isHttpUrl(url) ? link(code(label), url) : code(label)
+    else if (isHttpUrl(url)) ref = autolink(url)
+    const note = prose(evidenceNote(row))
+    const head = marker + (ref || '(no reference)')
+    return note ? `${head}\n\n${indentUnder(marker, note)}` : head
+  }).join('\n\n')
+}
+
+// The description's lead, its evidence, then the labelled sections the
+// report wrote — the order a claude-security report writes and the card
+// reads. A `**Label:**` paragraph becomes a section with a heading, as
+// the finding's own impact / reproduction fields do, so a report that
+// wrote those as fields and one that wrote them into its prose read
+// identically.
+function descriptionBlocks(f, ctx, depth) {
+  const split = splitDescription(f)
+  // Line endings first: the paragraph split below reads blank lines,
+  // and a `\r\n\r\n` a JSON report wrote is not one to it.
+  const body = normalizeNewlines(split.body)
+  // A one-line description IS the heading, and printing it again is a
+  // stutter — unless the heading could not carry the whole name
+  // (HEADING_MAX), where the body opens on it instead, the only place
+  // the whole name appears and where the file's reader finds it.
+  const title = findingTitle(f)
+  const cut = title !== '' && findingHeading(f) !== title
+  const stutter = !cut && !split.title && body.trim() === title
+  const carried = cut && firstLine(body) !== title ? `${title}\n\n${body}` : body
+  const sections = descriptionSections(stutter ? '' : carried)
+  const firstLabel = sections.findIndex((s) => s.label !== null)
+  const lead = firstLabel === -1 ? sections : sections.slice(0, firstLabel)
+  const rest = firstLabel === -1 ? [] : sections.slice(firstLabel)
+  const blocks = lead.map((s) => prose(s.body))
+  const evidence = evidenceList(f, ctx)
+  if (evidence) blocks.push(`${heading(depth, 'Evidence')}\n\n${evidence}`)
+  for (const s of rest) blocks.push(s.label === null ? prose(s.body) : section(depth, s.label, s.body))
+  return blocks
+}
+
+// Everything under one case's heading: the facts, the description, the
+// narrative sections, then the reader's comment — about the finding
+// rather than part of it.
+function caseBlocks(f, ctx, depth) {
+  const annotation = ctx.hooks.annotation(f)
+  const blocks = [metaList(f, ctx, annotation), ...descriptionBlocks(f, ctx, depth)]
+  for (const [label, field, pass] of NARRATIVE) {
+    if (pass && !ctx.revalidation) continue
+    const raw = f[field]
+    const value = typeof raw === 'string' ? stripExportMarker(raw, f) : ''
+    if (value.trim()) blocks.push(section(depth, label, value))
+  }
+  if (hasSeverityCorrection(f) && proseValue(f.correctedSeverityReason)) {
+    blocks.push(section(depth, 'Severity correction', f.correctedSeverityReason))
+  }
+  const comment = proseValue(annotation?.comment)
+  if (comment) blocks.push(section(depth, 'Comment', comment))
+  return blocks
+}
+
+// One group under its heading: a single case writes straight under it,
+// several get a numbered, located heading each with their sections one
+// level down. A case named differently from the group says so under its
+// own heading.
+export function groupSection(group, ctx, { headingText, depth }) {
+  const blocks = [heading(depth, headingText)]
+  if (group.length === 1) return joinBlocks([...blocks, ...caseBlocks(group[0], ctx, depth + 1)])
+  const reports = [...new Set(group.map((f) => ctx.hooks.report(f)).filter(Boolean))]
+  const from = reports.length > 1 ? ` — reported in ${reports.map((r) => code(r)).join(', ')}` : ''
+  blocks.push(`${plural(group.length, 'case')} of this finding${from}.`)
+  const groupTitle = findingTitle(group[0])
+  group.forEach((f, i) => {
+    const loc = locationLabel(f)
+    blocks.push(heading(depth + 1, `Case ${i + 1} of ${group.length}${loc ? ` — ${code(loc)}` : ''}`))
+    const own = findingTitle(f)
+    if (own && own !== groupTitle) blocks.push(prose(own))
+    blocks.push(...caseBlocks(f, ctx, depth + 2))
+  })
+  return joinBlocks(blocks)
+}

package/report/src/write-md.js

@@ -0,0 +1,291 @@
+// The findings document — what the "Download" button writes: one
+// markdown file a person can read top to bottom or jump around in.
+//
+// The shape, top to bottom:
+//
+//   <!-- DeepView findings export -->
+//   # <title>
+//   - **Source:** … / **Report:** … / **Repository:** … / **Analyzer:** …
+//   - **Exported:** … / **View:** … / **Filters:** … / **Included:** N of M findings
+//
+//   ## Summary
+//   <severity counts>  <annotation counts>  <index of findings, linked>
+//
+//   ## Critical (2)
+//   ### 1. <finding>              ← write-md-finding.js from here down
+//   - **Location:** …             the facts
+//   <description>  #### Evidence  #### Impact  …
+//
+// The header is the honest part. An export is a SELECTION — the triage
+// view narrowed by the toolbar filters — and a reader who wasn't at the
+// screen has to be told that a file of 12 findings is 12 of 40, and
+// which 28 are missing and why. So the filters ride in the header, in
+// the confirmation dialog's own words and counts.
+//
+// The document is also a report this library READS
+// (parse-deepview-md.js): the first line marks it, every finding carries
+// its id, and what the facts and sections say is what comes back,
+// whichever format the findings first arrived in. So a value goes on the
+// page in a shape the reader can take back off it — a fact on one line,
+// a location in a code span, a line of prose that would read as a
+// heading escaped.
+//
+// `doc` is plain data the caller assembles (ui/view/markdown-export.js,
+// or anything else holding findings out of index.js); `hooks` are the
+// few answers only the caller has — where a location links, what a
+// reader wrote on a finding, which report a case came from. All
+// optional: the defaults link what the report linked and annotate
+// nothing.
+//
+//   writeMarkdown({
+//     title, workspace, reports: [{ name, source }], repo, generatedAt,
+//     view: { bucket, severityMode, revalidation, revalidationDetail },
+//     filters: [{ label, value }], counts: { included, total },
+//     groups: [ [finding, …], … ],       // display order, primary case first
+//   }, { annotation, location, evidence, commit, report })
+
+import { SEVERITIES, displayedSeverity, locationLabel } from './finding.js'
+import { SOURCE_LABELS, severityLabel } from './labels.js'
+import { analyzerText, findingHeading, groupSection, repoRef } from './write-md-finding.js'
+import { anchorSlug, cell, code, escapeBrackets, formatTimestamp, heading, joinBlocks, link, plural, table } from './md-text.js'
+
+// The first line of every document this writes, and what its reader keys
+// on: an HTML comment, invisible rendered, and no other format begins
+// with one. The reader matches the phrase and reads past what follows,
+// so a later document that must be told apart can say so after a comma.
+export const DOCUMENT_MARKER = '<!-- DeepView findings export -->'
+
+// What a caller can answer about a finding, and what is assumed when
+// it doesn't: a report's own link for a location or an evidence row
+// still links, nothing else does, and nothing is annotated.
+const DEFAULT_HOOKS = {
+  annotation: () => null,
+  location: (f) => (typeof f?.location === 'string' ? f.location : null),
+  evidence: (row) => (typeof row?.url === 'string' ? row.url : null),
+  commit: () => null,
+  report: () => null,
+}
+
+function withDefaults(hooks) {
+  const out = {}
+  for (const [name, fallback] of Object.entries(DEFAULT_HOOKS)) {
+    out[name] = typeof hooks?.[name] === 'function' ? hooks[name] : fallback
+  }
+  return out
+}
+
+// Which producer a finding came from — a `source` marker, null for the
+// analyzer's own dump. Its own when it carries one: a re-imported
+// document that mixed products stamps each product's findings, and a
+// finding stays that product's whatever report it now sits in.
+// Otherwise its report's, found by the `report` hook's name in
+// `doc.reports` when the document holds more than one.
+function sourceReader(reports, hooks) {
+  const own = (f) => (typeof f?.source === 'string' && f.source ? f.source : null)
+  if (reports.length === 1) return (f) => own(f) ?? reports[0].source ?? null
+  const byName = new Map(reports.map((r) => [r.name, r.source ?? null]))
+  return (f) => own(f) ?? byName.get(hooks.report(f)) ?? null
+}
+
+// The per-document decisions, made once: the severity lens, whether the
+// revalidation layer is applied, and whether the per-finding analyzer
+// and report lines say anything — written only where they vary, so a
+// single-run report isn't told forty times which run it was.
+function buildContext(doc, hooks, cases) {
+  const revalidation = doc.view?.revalidation !== false
+  const reports = (Array.isArray(doc.reports) ? doc.reports : []).filter((r) => r && typeof r === 'object')
+  const sourceOf = sourceReader(reports, hooks)
+  const analyzerOf = (f) => analyzerText(f, sourceOf(f), revalidation)
+  const analyzers = new Set(cases.map(analyzerOf))
+  const names = new Set(cases.map((f) => hooks.report(f)).filter(Boolean))
+  return {
+    hooks,
+    analyzerOf,
+    severityMode: doc.view?.severityMode === 'original' ? 'original' : 'corrected',
+    revalidation,
+    showAnalyzer: analyzers.size > 1,
+    showReport: names.size > 1 || reports.length > 1,
+    repo: typeof doc.repo === 'string' && doc.repo ? doc.repo : null,
+  }
+}
+
+// The view the selection was made in, as one line: which triage
+// bucket, which severity lens (when the set carries corrections), and
+// whether the revalidation pass is applied (when it carries one).
+function viewText(view) {
+  if (!view) return ''
+  const parts = [view.bucket ? `${view.bucket} findings` : 'Live findings']
+  if (view.severityMode === 'original') parts.push('original analyzer severities')
+  else if (view.severityMode === 'corrected') parts.push('corrected severities')
+  if (view.revalidation === false) parts.push('code view — the revalidation pass is not applied')
+  else if (view.revalidation === true) {
+    // Which app view: the verdict standing in for the rows it re-rated
+    // (the default on screen, folded here as there), or the detailed one
+    // that lists them. A caller that doesn't track the detail says the
+    // layer is applied and no more.
+    if (view.revalidationDetail === true) parts.push('detailed app view — the revalidation pass is applied, with the rows it re-rated')
+    else if (view.revalidationDetail === false) parts.push('app view — the revalidation pass is applied, standing in for the rows it re-rated')
+    else parts.push('app view — the revalidation pass is applied')
+  }
+  return parts.join(' · ')
+}
+
+function includedText(counts) {
+  if (!counts) return ''
+  const included = Number(counts.included) || 0
+  const total = Number(counts.total) || 0
+  if (total === 0) return 'no findings'
+  if (included >= total) return `all ${plural(total, 'finding')}`
+  return `${included} of ${plural(total, 'finding')} (${total - included} filtered out)`
+}
+
+// The header list: what was exported, from where, when, and under which
+// view and filters. Each line is written only when it has something to
+// say, and the filter line says "none" outright, so its absence never
+// has to be interpreted.
+//
+// `Source` names the products the loaded reports came from, `Analyzer`
+// what produced the included findings. For one product they are the same
+// word and the analyzer line is left out — but only when it would say
+// exactly what Source says, the same products and no fewer: two products
+// filtered down to one name the one, and a document holding the
+// analyzer's own runs lists every analyzer. The reader takes a single
+// analyzer named here as every finding's.
+function headerList(doc, ctx, cases) {
+  const rows = []
+  const add = (label, value) => { if (value) rows.push(`- **${label}:** ${value}`) }
+  const reports = Array.isArray(doc.reports) ? doc.reports : []
+  const sources = [...new Set(reports.map((r) => SOURCE_LABELS[r?.source] ?? '').filter(Boolean))]
+  add('Source', sources.join(', '))
+  const names = reports.map((r) => r?.name).filter(Boolean)
+  add(names.length === 1 ? 'Report' : 'Reports', names.map((n) => code(n)).join(', '))
+  add('Workspace', typeof doc.workspace === 'string' ? doc.workspace.trim() : '')
+  if (ctx.repo) add('Repository', repoRef(ctx.repo))
+  const analyzers = [...new Set(cases.map(ctx.analyzerOf).filter(Boolean))]
+  const saidAlready = analyzers.length === sources.length && analyzers.every((a) => sources.includes(a))
+  if (analyzers.length > 0 && !saidAlready) add(analyzers.length === 1 ? 'Analyzer' : 'Analyzers', analyzers.join('; '))
+  if (doc.generatedAt) add('Exported', formatTimestamp(doc.generatedAt))
+  add('View', viewText(doc.view))
+  if (Array.isArray(doc.filters)) {
+    add('Filters', doc.filters.length > 0 ? doc.filters.map((f) => `${f.label}: ${f.value}`).join(' · ') : 'none')
+  }
+  add('Included', includedText(doc.counts))
+  return rows.join('\n')
+}
+
+// The groups bucketed by the severity their primary case displays under,
+// in ladder order — an unknown tier last, as the report spelt it —
+// numbered through the document, each with its heading and anchor.
+function documentEntries(groups, ctx) {
+  const buckets = new Map()
+  for (const g of groups) {
+    const severity = displayedSeverity(g[0], ctx.severityMode) ?? 'informational'
+    if (!buckets.has(severity)) buckets.set(severity, [])
+    buckets.get(severity).push(g)
+  }
+  const order = [...SEVERITIES, ...[...buckets.keys()].filter((s) => !SEVERITIES.includes(s))]
+  const taken = new Set()
+  const entries = []
+  for (const severity of order) {
+    for (const group of buckets.get(severity) ?? []) {
+      const number = entries.length + 1
+      const title = findingHeading(group[0])
+      const headingText = `${number}. ${title}`
+      entries.push({ group, number, severity, title, headingText, slug: anchorSlug(headingText, taken) })
+    }
+  }
+  return entries
+}
+
+// Findings per tier, in entry order — which is ladder order, since the
+// entries were bucketed that way.
+function severityCounts(entries) {
+  const counts = new Map()
+  for (const e of entries) counts.set(e.severity, (counts.get(e.severity) ?? 0) + 1)
+  return counts
+}
+
+function annotationSummary(entries, ctx) {
+  const tally = { flagged: 0, marked: 0, commented: 0, fixed: 0 }
+  for (const { group } of entries) {
+    for (const f of group) {
+      const a = ctx.hooks.annotation(f)
+      if (!a) continue
+      if (a.flagged === true) tally.flagged++
+      if (a.color) tally.marked++
+      if (a.comment) tally.commented++
+      if (a.fix) tally.fixed++
+    }
+  }
+  const parts = []
+  if (tally.flagged) parts.push(`${tally.flagged} flagged`)
+  if (tally.marked) parts.push(`${tally.marked} colour-marked`)
+  if (tally.commented) parts.push(`${tally.commented} commented`)
+  if (tally.fixed) parts.push(`${tally.fixed} with a fix link`)
+  return parts.length > 0 ? `Annotations: ${parts.join(', ')}.` : ''
+}
+
+// One row per finding, linked to its section, so a reader sees the whole
+// report on one screen and can jump. The confidence column appears only
+// when something has a confidence.
+function indexTable(entries) {
+  const withConfidence = entries.some(({ group }) => group.some((f) => f.confidence !== undefined && f.confidence !== null))
+  const headers = ['#', 'Severity', 'Finding', 'Location']
+  if (withConfidence) headers.push('Confidence')
+  const rows = entries.map((e) => {
+    const primary = e.group[0]
+    const cases = e.group.length > 1 ? ` (${plural(e.group.length, 'case')})` : ''
+    const loc = locationLabel(primary)
+    const row = [String(e.number), severityLabel(e.severity), link(cell(escapeBrackets(e.title)), `#${e.slug}`) + cases, loc ? cell(code(loc)) : '']
+    if (withConfidence) row.push(primary.confidence === undefined || primary.confidence === null ? '' : `${primary.confidence}/10`)
+    return row
+  })
+  return table(headers, rows, ['right'])
+}
+
+function summaryBlocks(entries, ctx) {
+  const blocks = [heading(2, 'Summary')]
+  if (entries.length === 0) return [...blocks, 'No findings are included.']
+  const rows = [...severityCounts(entries)].map(([s, n]) => [severityLabel(s), String(n)])
+  rows.push(['**Total**', `**${entries.length}**`])
+  blocks.push(table(['Severity', 'Findings'], rows, ['left', 'right']))
+  const notes = annotationSummary(entries, ctx)
+  if (notes) blocks.push(notes)
+  blocks.push(indexTable(entries))
+  return blocks
+}
+
+// One `## <Severity> (n)` section per tier present, the findings under
+// it in the order they arrived — the caller's sort.
+function severitySections(entries, ctx) {
+  const counts = severityCounts(entries)
+  const blocks = []
+  let current = null
+  for (const e of entries) {
+    if (e.severity !== current) {
+      current = e.severity
+      blocks.push(heading(2, `${severityLabel(current)} (${counts.get(current)})`))
+    }
+    blocks.push(groupSection(e.group, ctx, { headingText: e.headingText, depth: 3 }))
+  }
+  return blocks
+}
+
+export function writeMarkdown(doc = {}, hooks = {}) {
+  const h = withDefaults(hooks)
+  const groups = (Array.isArray(doc.groups) ? doc.groups : [])
+    .map((g) => (Array.isArray(g) ? g : [g]))
+    .map((g) => g.filter((f) => f && typeof f === 'object'))
+    .filter((g) => g.length > 0)
+  const cases = groups.flat()
+  const ctx = buildContext(doc, h, cases)
+  const entries = documentEntries(groups, ctx)
+  const blocks = [
+    DOCUMENT_MARKER,
+    heading(1, typeof doc.title === 'string' && doc.title.trim() ? doc.title.trim() : 'Findings'),
+    headerList(doc, ctx, cases),
+    ...summaryBlocks(entries, ctx),
+    ...severitySections(entries, ctx),
+  ]
+  return `${joinBlocks(blocks)}\n`
+}

package/server-e2e/bus-receiver.ts

@@ -90,6 +90,7 @@ export function createBusReceiver(deps: BusReceiverDeps): (msg: BusMessage) => P
       workspaceTag: msg.tag,
       resourceTag: msg.res,
       version: msg.ver,
+      ...(msg.incarnation === undefined ? {} : { incarnation: msg.incarnation }),
     }))
   }
 }

package/server-e2e/hub.ts

@@ -7,9 +7,13 @@
 // testable and reasoned about on its own.
 
 import type { WebSocket } from 'ws'
+import { Buffer } from 'node:buffer'
 import type { PeerRegistry } from './peer.ts'
 
 export type Hub = {
+  // Buffer broadcasts during async subscription snapshots. The returned
+  // release flushes them after the snapshot/chain replies, preserving order.
+  pauseBroadcasts(socket: WebSocket): () => void
   subscribe(socket: WebSocket, tag: string): void
   unsubscribeAll(socket: WebSocket): void
   send(socket: WebSocket, msg: object): void
@@ -38,18 +42,34 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   // workspaceTag → Set<WebSocket>. The per-socket reverse index lives on
   // `Peer.tags` (see ./peer.ts) and is read by `unsubscribeAll` on close.
   const subscribers = new Map<string, Set<WebSocket>>()
+  const paused = new WeakMap<WebSocket, { depth: number; payloads: string[]; bytes: number }>()
+
+  function pauseBroadcasts(socket: WebSocket): () => void {
+    const pending = paused.get(socket) ?? { depth: 0, payloads: [], bytes: 0 }
+    pending.depth++
+    paused.set(socket, pending)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      if (--pending.depth > 0 || paused.get(socket) !== pending) return
+      paused.delete(socket)
+      for (const payload of pending.payloads) sendRaw(socket, payload)
+      pending.payloads.length = 0
+    }
+  }
 
   function subscribe(socket: WebSocket, tag: string): void {
     let set = subscribers.get(tag)
-    if (!set) {
-      set = new Set()
-      subscribers.set(tag, set)
-    }
+    if (!set) { set = new Set(); subscribers.set(tag, set) }
     set.add(socket)
     peers.get(socket)?.tags.add(tag)
   }
 
   function unsubscribeAll(socket: WebSocket): void {
+    const pending = paused.get(socket)
+    if (pending) pending.payloads.length = 0
+    paused.delete(socket)
     const tags = peers.get(socket)?.tags
     if (!tags) return
     for (const tag of tags) {
@@ -102,6 +122,7 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
   }
 
   function fanOut(set: Set<WebSocket>, payload: string, except: WebSocket | null): void {
+    const payloadBytes = Buffer.byteLength(payload)
     // Snapshot before iterating — a socket transitioning to CLOSED
     // mid-broadcast triggers `unsubscribeAll` from the 'close' handler,
     // mutating `set` while we walk it. The snapshot also keeps a future
@@ -109,9 +130,19 @@ export function createHub(deps: { peers: PeerRegistry; maxBufferedBytes: number;
     // subscribers. Audit M4 round-3.
     for (const s of [...set]) {
       if (s === except) continue
-      sendRaw(s, payload)
+      const pending = paused.get(s)
+      if (!pending) { sendRaw(s, payload); continue }
+      pending.bytes += payloadBytes
+      if (pending.bytes > maxBufferedBytes) {
+        // Snapshot waits must obey the same memory bound as socket writes.
+        pending.payloads.length = 0
+        paused.delete(s)
+        try { s.terminate() } catch {}
+        continue
+      }
+      pending.payloads.push(payload)
     }
   }
 
-  return { subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
+  return { pauseBroadcasts, subscribe, unsubscribeAll, send, sendRaw, broadcast, broadcastLocalRaw }
 }

package/server-e2e/index.ts

@@ -289,12 +289,13 @@ const publishRevision = (tag: string, revisionId: string): void => {
 const publishObjPut = (tag: string, resourceTag: string): void => {
   pubsub.publish({ kind: 'objput', tag, res: resourceTag })
 }
-const publishObjDeleted = (tag: string, resourceTag: string, version: number): void => {
-  pubsub.publish({ kind: 'objdel', tag, res: resourceTag, ver: version })
+const publishObjDeleted = (tag: string, resourceTag: string, version: number, incarnation: string): void => {
+  pubsub.publish({ kind: 'objdel', tag, res: resourceTag, ver: version, incarnation })
 }
 
 const { handleSave, handleSaveRest, handleSubscribe, sendSaveError } = createSyncHandlers({
   handle, send, broadcast, publishRevision, subscribe, getNonce,
+  pauseBroadcasts: hub.pauseBroadcasts,
   requiresAuth, passwordConfigured, sendUnauthorized, workspaceExists,
   // Folds the objstore inventory into the `workspace-subscribed` ack.
   // The objstore store keeps its own richer `Handle`, so we wire the