@cyanheads/pubmed-mcp-server 2.10.8 → 2.10.10

package/dist/mcp-server/tools/definitions/fetch-fulltext.tool.js

@@ -31,16 +31,66 @@ import { getUnpaywallService, } from '../../../services/unpaywall/unpaywall-serv
 import { fitWholeItems } from './_budget.js';
 import { conceptMeta, EDAM_DATA_RETRIEVAL, SCHEMA_SCHOLARLY_ARTICLE } from './_concepts.js';
 import { pmidStringSchema } from './_schemas.js';
-import { escapeMarkdownInline, sliceCodeUnits } from './_text.js';
+import { escapeMarkdownInline, escapeMarkdownTableCell, sliceCodeUnits } from './_text.js';
 function normalizePmcId(id) {
     return id.replace(/^PMC/i, '');
 }
 function withPmcPrefix(id) {
     return id.startsWith('PMC') ? id : `PMC${id}`;
 }
-function filterSections(sections, sectionFilter) {
-    const lowerFilter = sectionFilter.map((s) => s.toLowerCase());
-    return sections.filter((s) => s.title && lowerFilter.some((f) => s.title?.toLowerCase().includes(f)));
+/** Case-insensitive substring match of one section heading against the filter. */
+function matchesSectionFilter(title, lowerFilter) {
+    const lowered = title?.toLowerCase();
+    return lowered !== undefined && lowerFilter.some((f) => lowered.includes(f));
+}
+function lowerCase(s) {
+    return s.toLowerCase();
+}
+/**
+ * Prune a section tree to the branches a `sections` filter selects, matching
+ * titles at every nesting depth rather than the top level alone. (#126)
+ *
+ * A section whose own title matches is returned whole — object identity
+ * included, so an unfiltered subtree is never rebuilt. A section kept only
+ * because a descendant matched becomes a breadcrumb: its `title` and `label`
+ * survive so the match can be placed in the document, its own `text` is cleared
+ * because the caller filtered that prose away, and it carries just the matching
+ * branch of its subsections. Promoting the match to the top level instead would
+ * make `maxSections` — which caps genuine top-level sections — count nested
+ * content as top-level.
+ */
+function pruneSections(sections, lowerFilter) {
+    const kept = [];
+    for (const section of sections) {
+        if (matchesSectionFilter(section.title, lowerFilter)) {
+            kept.push(section);
+            continue;
+        }
+        const subsections = pruneSections(section.subsections ?? [], lowerFilter);
+        if (subsections.length > 0)
+            kept.push({ ...section, text: '', subsections });
+    }
+    return kept;
+}
+/**
+ * Titles of the sections a `sections` filter actually selected — a section that
+ * matched directly plus everything beneath it. Breadcrumb ancestors are left
+ * out: their own text was cleared because the caller did not ask for it, and a
+ * table sitting in one was not asked for either. Walks the *pruned* tree, so a
+ * top-level section the `maxSections` slice removed contributes nothing.
+ */
+function matchedSectionTitles(sections, lowerFilter) {
+    const titles = new Set();
+    const walk = (nodes, inherited) => {
+        for (const section of nodes) {
+            const matched = inherited || matchesSectionFilter(section.title, lowerFilter);
+            if (matched && section.title)
+                titles.add(section.title);
+            walk(section.subsections ?? [], matched);
+        }
+    };
+    walk(sections, false);
+    return titles;
 }
 /**
  * Render a section subtree as text blocks, in document order: each section's
@@ -73,16 +123,133 @@ function clampSectionDepth(sections, depth = 1) {
     });
 }
 /**
- * Apply the requested section/reference filters, then clamp the section tree to
- * the depth the output schema carries. Both run here so every path producing a
- * `pmc` article — PMC EFetch and the Europe PMC stage — shares one shape, and
- * the budget helpers downstream count the text that will actually survive
- * validation. (#112)
+ * Replace an article's table list, dropping the field entirely when nothing is
+ * left. An empty array would read as "this article has no tables", which is the
+ * one thing an absent field already says and a filtered-to-nothing list does
+ * not mean.
+ */
+function withTables(article, tables) {
+    const { tables: _replaced, ...rest } = article;
+    return (tables.length > 0 ? { ...rest, tables } : rest);
+}
+/**
+ * Narrow the table list to what the request asked for. `includeTables: false`
+ * is the wholesale off switch. An active `sections` filter narrows tables with
+ * it: a table names the section it sat in — body, back matter or appendix
+ * alike — so it survives when that section did, and a table that names no
+ * section, such as a `<floats-group>` deposit, is dropped because the caller
+ * asked for named headings and it belongs to none. With no `sections` filter
+ * every table is returned. (#111)
+ */
+function applyTableFilters(article, filters) {
+    if (!article.tables?.length)
+        return article;
+    if (!filters.includeTables)
+        return withTables(article, []);
+    if (!filters.sections?.length)
+        return article;
+    const surviving = matchedSectionTitles(article.sections, filters.sections.map(lowerCase));
+    return withTables(article, article.tables.filter((t) => t.sectionTitle !== undefined && surviving.has(t.sectionTitle)));
+}
+/**
+ * Replace an article's asset list, dropping the field entirely when nothing is
+ * left — the same rule {@link withTables} follows, and for the same reason: an
+ * empty array claims the article deposits no figures, which a filtered-to-nothing
+ * list does not mean.
+ */
+function withAssets(article, assets) {
+    const { assets: _replaced, ...rest } = article;
+    return (assets.length > 0 ? { ...rest, assets } : rest);
+}
+/**
+ * The positional marker the parser leaves in section text where an asset was
+ * lifted out — `[Figure: Fig. 1]`, `[Supplementary: Table S3]`, or the bare
+ * `[Figure]` / `[Supplementary]` when the deposit carries no label.
+ *
+ * Mirrors `assetMarker` in `pmc-article-parser.ts`, which is the only producer.
+ * The two must stay byte-identical: this is what {@link stripAssetMarkers}
+ * removes, and a marker built any other way would leave the real one in place.
+ * Derived per asset rather than matched as a pattern, so prose that happens to
+ * carry a bracketed word is never touched. (#130)
+ */
+function assetMarkerText(asset) {
+    const kind = asset.assetType === 'figure' ? 'Figure' : 'Supplementary';
+    return asset.label ? `[${kind}: ${asset.label}]` : `[${kind}]`;
+}
+/**
+ * Remove every marker in `markers` from one text field and close the gap it
+ * leaves: trailing whitespace on a line the marker ended, and the blank line a
+ * marker that stood alone as its own block leaves behind.
+ */
+function stripAssetMarkers(text, markers) {
+    if (!text)
+        return text;
+    let out = text;
+    for (const marker of markers)
+        out = out.split(marker).join('');
+    if (out === text)
+        return text;
+    return out
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** Strip asset markers from a section and every subsection beneath it. */
+function sectionWithoutMarkers(section, markers) {
+    const text = stripAssetMarkers(section.text, markers);
+    const subsections = section.subsections?.map((sub) => sectionWithoutMarkers(sub, markers));
+    if (text === section.text && subsections === undefined)
+        return section;
+    return { ...section, text, ...(subsections && { subsections }) };
+}
+/**
+ * Narrow the asset list to what the request asked for, mirroring {@link
+ * applyTableFilters}: `includeAssets: false` is the wholesale off switch, and an
+ * active `sections` filter keeps an asset whose named section survived while
+ * dropping one that names no section at all — a `<floats-group>` deposit — since
+ * the caller asked for named headings and it belongs to none.
+ *
+ * Where it goes beyond the table counterpart: turning assets off also removes the
+ * positional markers the parser left in the section text. The marker is the
+ * lift's anchor, and without the array to resolve it against it points at
+ * nothing. Prose-shaped blocks — lists, quotes, formulae — are section text
+ * rather than assets and this switch never touches them. (#130)
+ */
+function applyAssetFilters(article, filters) {
+    const assets = article.assets;
+    if (!assets?.length)
+        return article;
+    if (!filters.includeAssets) {
+        const markers = assets.map(assetMarkerText);
+        return withAssets({ ...article, sections: article.sections.map((s) => sectionWithoutMarkers(s, markers)) }, []);
+    }
+    if (!filters.sections?.length)
+        return article;
+    const surviving = matchedSectionTitles(article.sections, filters.sections.map(lowerCase));
+    return withAssets(article, assets.filter((a) => a.sectionTitle !== undefined && surviving.has(a.sectionTitle)));
+}
+/**
+ * Apply the requested section/reference/table/asset filters, then clamp the
+ * section tree to the depth the output schema carries. All of it runs here so every path
+ * producing a `pmc` article — PMC EFetch and the Europe PMC stage — shares one
+ * shape, and the budget helpers downstream count the text that will actually
+ * survive validation. (#112)
+ *
+ * Order is load-bearing. Tables and assets are matched against the section tree
+ * *after* `filterSections` and the `maxSections` slice, so they narrow with
+ * exactly what the response returns, and *before* `clampSectionDepth`, which
+ * folds sections past {@link MAX_SECTION_DEPTH} into a parent's text — their
+ * titles vanish from the output while a table or figure still names them, so a
+ * title set built after the clamp would drop entries that should have survived.
+ * Stripping the asset markers also has to precede the clamp, or a marker in a
+ * folded-away section survives in the text it was folded into. (#111, #130)
  */
 function applyPmcFilters(article, filters) {
     let out = article;
     if (filters.sections?.length) {
-        out = { ...out, sections: filterSections(out.sections, filters.sections) };
+        out = { ...out, sections: pruneSections(out.sections, filters.sections.map(lowerCase)) };
     }
     if (filters.maxSections !== undefined) {
         out = { ...out, sections: out.sections.slice(0, filters.maxSections) };
@@ -91,6 +258,8 @@ function applyPmcFilters(article, filters) {
         const { references: _, ...rest } = out;
         out = rest;
     }
+    out = applyTableFilters(out, filters);
+    out = applyAssetFilters(out, filters);
     return { ...out, sections: clampSectionDepth(out.sections) };
 }
 /**
@@ -125,11 +294,16 @@ function articleDisplayId(a) {
  * Compose the single recovery notice for `sections`-filter misses. Names the
  * requested terms and the affected article id(s) so the agent can distinguish a
  * filtered-empty body from one absent upstream, and points at the recovery. (#80)
+ *
+ * States the scope the filter actually searches — section and subsection titles
+ * at every depth — so a caller who named a nested heading learns the term itself
+ * matched nothing, rather than being left to suspect the filter never looked
+ * that deep. (#126)
  */
 function buildSectionFilterMissNotice(affectedIds, sectionFilter) {
     const terms = sectionFilter.join(', ');
     const subject = affectedIds.length === 1 ? `article ${affectedIds[0]}` : `articles ${affectedIds.join(', ')}`;
-    return `No body sections matched the requested section filter (${terms}) for ${subject}. The full text was retrieved but every body section was filtered out. Retry without \`sections\`, or filter on broader headings such as Introduction, Methods, Results, or Discussion.`;
+    return `No section or subsection title, at any nesting depth, matched the requested section filter (${terms}) for ${subject}. The full text was retrieved but every body section was filtered out. Retry without \`sections\`, or filter on broader headings such as Introduction, Methods, Results, or Discussion.`;
 }
 /**
  * Compose the recovery notice for identifiers whose only retrievable record was
@@ -204,6 +378,86 @@ const ReferenceSchema = z
     label: z.string().optional().describe('Reference label'),
 })
     .describe('Reference entry');
+/**
+ * One `<table-wrap>`, hung off the article rather than off a section.
+ *
+ * The article is the only level that can hold every table: roughly a quarter of
+ * real `<table-wrap>` elements sit in `<floats-group>`, `<back>`, a
+ * `<table-wrap-group>` or an appendix, with no `<sec>` to attach to. A table
+ * inside a section names it in {@link sectionTitle} instead of being placed by
+ * position.
+ *
+ * The shape also lands exactly on the `format-parity` sentinel walker's eight-hop
+ * budget — `articles[]` → the article union → `tables[]` → `rows[][]` — with no
+ * headroom, and a section-hung variant would spend a hop the existing
+ * `sections[]` → `subsections[]` chain already needs. Re-run
+ * `bun run lint:mcp` after any change here; a level added anywhere inside puts
+ * its own leaves out of the walker's reach and ships their `format()` parity
+ * unverified. (#111, #112)
+ */
+const TableSchema = z
+    .object({
+    label: z.string().optional().describe('Table label as printed, e.g. `TABLE 1`'),
+    caption: z.string().optional().describe('Caption text, with the label excluded'),
+    id: z
+        .string()
+        .optional()
+        .describe('JATS `id` attribute — the target body-text cross-references point at'),
+    sectionTitle: z
+        .string()
+        .optional()
+        .describe('Title of the innermost section enclosing the table, wherever that section sits — body, `<back>` matter, or an appendix all count, and in back matter the section name is the only positional cue there is. Absent only for a table inside no section at all, such as a `<floats-group>` deposit.'),
+    headerRowCount: z
+        .number()
+        .describe('How many leading `rows` entries are header rows — a `<thead>` block, or leading rows made entirely of `<th>`. 0 when the table declares none. Several header rows stack: read one column top to bottom for its full header path.'),
+    rows: z
+        .array(z.array(z.string()).describe('One row, as cell text by grid column'))
+        .describe('Cell text by row, in document order, one entry per grid column. `colspan` and `rowspan` are expanded, so a cell covering several columns or rows repeats its text across each cell it covers and a well-formed table is rectangular — align on position from the left, and read a repeated value as one spanning cell rather than several measurements. Empty when `unextractableReason` is set.'),
+    footnotes: z.string().optional().describe('`<table-wrap-foot>` text, flattened to one string'),
+    unextractableReason: z
+        .enum(['cals-tgroup', 'graphic-only', 'no-rows'])
+        .optional()
+        .describe('Why `rows` is empty — set only then. graphic-only: the table was deposited as an image with no underlying markup. cals-tgroup: the table uses the CALS `<tgroup>` model, which this server does not extract (0 of 283 tables in an open-access survey used it). no-rows: the markup carried no rows. The label and caption are still returned, so a table that could not be read is visible rather than silently missing.'),
+})
+    .describe('One table from the article, with its cells, caption, and owning section');
+/**
+ * One `<fig>` or `<supplementary-material>`, hung off the article beside
+ * {@link TableSchema} and for the same reason: a sixth of them sit in
+ * `<floats-group>`, `<back>` or an appendix with no `<sec>` to attach to, so an
+ * asset inside a section names it in {@link sectionTitle} rather than being
+ * placed by position.
+ *
+ * Scalar leaves only. `articles[]` → the article union → `assets[]` → a leaf is
+ * six of the eight hops the `format-parity` sentinel walker allows; a nested
+ * object here (a `files[]` list, say) spends the remaining two and leaves nothing
+ * for a later field. Re-run `bun run lint:mcp` after any change to this shape.
+ *
+ * There is no media-type field and no per-asset unextractable reason: `mimetype`
+ * appears on no observed deposit, and an uncaptioned supplement is still fully
+ * described by its `id` and `href`, unlike a table that promises cells and
+ * carries none. (#130)
+ */
+const AssetSchema = z
+    .object({
+    assetType: z
+        .enum(['figure', 'supplementary-material'])
+        .describe('Which captioned element this came from — `figure` for a `<fig>`, `supplementary-material` for a `<supplementary-material>` deposit'),
+    label: z.string().optional().describe('Display label as printed, e.g. `Fig. 1`'),
+    caption: z.string().optional().describe('Caption text, with the label excluded'),
+    id: z
+        .string()
+        .optional()
+        .describe('JATS `id` attribute — the target body-text cross-references point at'),
+    sectionTitle: z
+        .string()
+        .optional()
+        .describe('Title of the innermost section enclosing the asset, wherever that section sits — body, `<back>` matter, or an appendix all count. Absent for an asset inside no section at all, such as a `<floats-group>` deposit.'),
+    href: z
+        .string()
+        .optional()
+        .describe('The `<graphic>`/`<media>` `@xlink:href` exactly as deposited — a pointer into the PMC deposit (`MOL2-20-1253-g001.jpg`), not a fetchable URL. No absolute form of it resolves; read the rendered article at `pmcUrl` instead. Absent when the deposit names no file.'),
+})
+    .describe('One figure or supplementary-material item, with its caption, pointer, and section');
 const PublicationDateSchema = z
     .object({
     year: z.string().optional().describe('Publication year'),
@@ -239,6 +493,14 @@ const PmcArticleSchema = z
     articleType: z.string().optional().describe('Article type'),
     publicationDate: PublicationDateSchema.optional(),
     sections: z.array(SectionSchema).describe('Article body sections'),
+    tables: z
+        .array(TableSchema)
+        .optional()
+        .describe('Every `<table-wrap>` the article carries, in document order — from the body and from `<floats-group>`, `<back>` and appendices alike. Absent when the article deposits none, when `includeTables` is false, or when a `sections` filter left none standing.'),
+    assets: z
+        .array(AssetSchema)
+        .optional()
+        .describe('Every `<fig>` and `<supplementary-material>` the article carries, in document order — from the body and from `<floats-group>`, `<back>` and appendices alike. Each one lifted from the body leaves a `[Figure: <label>]` or `[Supplementary: <label>]` marker at its position in the section text, so reading order survives the lift. Absent when the article deposits none, when `includeAssets` is false, or when a `sections` filter left none standing.'),
     references: z.array(ReferenceSchema).optional().describe('Reference list'),
     epmcId: z
         .string()
@@ -303,12 +565,13 @@ const UnavailableReasonSchema = z
     'no-epmc-fulltext',
     'no-body',
     'no-doi',
+    'doi-lookup-failed',
     'no-oa',
     'fetch-failed',
     'parse-failed',
     'service-error',
 ])
-    .describe('Why no full text was returned — the most specific signal any tier that answered reported. not-found: upstream returned no record for this ID. no-pmc-fallback-disabled: every tier was skipped (`triedTiers` is all `not-attempted`) — typically because EPMC (`EUROPEPMC_ENABLED`) and Unpaywall (`UNPAYWALL_EMAIL`) are not configured. no-epmc-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the record was retrieved but carries front matter and abstract only, with no body sections — use `pubmed_fetch_articles` for the metadata. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall has no OA copy. fetch-failed: download failed. parse-failed: extraction empty. service-error: upstream server failure (threw, timed out, or returned malformed data). A reason never means the chain ran to completion — read `unqueriedTiers` for that.');
+    .describe('Why no full text was returned — the most specific signal any tier that answered reported. not-found: upstream returned no record for this ID. no-pmc-fallback-disabled: every tier was skipped (`triedTiers` is all `not-attempted`) — typically because EPMC (`EUROPEPMC_ENABLED`) and Unpaywall (`UNPAYWALL_EMAIL`) are not configured. no-epmc-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the record was retrieved but carries front matter and abstract only, with no body sections — use `pubmed_fetch_articles` for the metadata. no-doi: the DOI lookup ran and this record has none, so Unpaywall could not be queried. doi-lookup-failed: the DOI lookup itself errored, so whether a DOI exists is unknown and Unpaywall was never reached — retry the request; unlike no-doi this is a transient failure, not a settled answer. no-oa: Unpaywall has no OA copy. fetch-failed: download failed. parse-failed: extraction empty. service-error: upstream server failure (threw, timed out, or returned malformed data). A reason never means the chain ran to completion — read `unqueriedTiers` for that.');
 const UnqueriedTierSchema = z
     .enum(['europepmc', 'unpaywall'])
     .describe('A fallback tier this deployment has not configured');
@@ -319,12 +582,13 @@ const TierOutcomeSchema = z
     'no-fulltext',
     'no-body',
     'no-doi',
+    'doi-lookup-failed',
     'no-oa',
     'fetch-failed',
     'parse-failed',
     'service-error',
 ])
-    .describe('Per-tier outcome. not-attempted: tier was skipped. miss: tier returned no record. no-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the tier returned a record with front matter and abstract but no body sections, so the chain continued. no-doi: no DOI to query Unpaywall. no-oa: Unpaywall reports no open-access copy. fetch-failed: OA copy download failed. parse-failed: extraction produced empty content. service-error: tier service threw.');
+    .describe('Per-tier outcome. not-attempted: tier was skipped. miss: tier returned no record. no-fulltext: EPMC indexed the record but publishes no fullTextXML. no-body: the tier returned a record with front matter and abstract but no body sections, so the chain continued. no-doi: the DOI lookup ran and this record has none, so Unpaywall could not be queried. doi-lookup-failed: the DOI lookup itself errored, so whether a DOI exists is unknown and Unpaywall was never reached — retry the request. no-oa: Unpaywall reports no open-access copy. fetch-failed: OA copy download failed. parse-failed: extraction produced empty content. service-error: tier service threw.');
 const TriedTierSchema = z
     .object({
     tier: z.enum(['pmc', 'europepmc', 'unpaywall']).describe('Which tier in the resolution chain'),
@@ -379,6 +643,22 @@ const TruncatedArticleSchema = z
         .array(TruncatedSectionSchema)
         .optional()
         .describe('Per-section accounting for `source: pmc` articles, in document order, including sections dropped for budget. Absent for `source: unpaywall`, whose body has no section structure.'),
+    omittedTables: z
+        .number()
+        .optional()
+        .describe('Tables this article dropped whole because the budget left no room for them. A table is never cut mid-row, so it is either returned complete or counted here. Absent when none were dropped.'),
+    omittedTableNames: z
+        .array(z.string())
+        .optional()
+        .describe("The dropped tables by name, in document order — each table's label, else its `id`, else `table <n>` for its position in the article. Names the tables a bare count only hints at, the way `deferred.ids` names deferred articles. Every table from the first that did not fit onward is here: admission stops at that table rather than skipping ahead to a smaller one, so these are contiguous. Absent when none were dropped."),
+    omittedAssets: z
+        .number()
+        .optional()
+        .describe('Figures and supplementary items this article dropped whole because the budget left no room once sections and tables were served. An asset is never returned with a truncated caption, so it is either returned complete or counted here. Absent when none were dropped.'),
+    omittedAssetNames: z
+        .array(z.string())
+        .optional()
+        .describe("The dropped assets by name, in document order — each asset's label, else its `id`, else `asset <n>` for its position in the article. Contiguous for the same reason `omittedTableNames` is: admission stops at the first asset that did not fit rather than skipping ahead to a smaller one. Absent when none were dropped."),
 })
     .describe('Character accounting for one article the budget shortened');
 const TruncationSchema = z
@@ -400,6 +680,14 @@ const TruncationSchema = z
     omittedSections: z
         .number()
         .describe('Body sections dropped entirely because an article budget was exhausted before reaching them. Always 0 in `outline` mode, which keeps every heading.'),
+    omittedTables: z
+        .number()
+        .optional()
+        .describe('Tables dropped whole across every budgeted article, because the budget left no room once body sections were served. Absent when none were dropped. Re-request the affected articles with a higher `maxCharacters`, or with `sections` narrowed, to receive them.'),
+    omittedAssets: z
+        .number()
+        .optional()
+        .describe('Figures and supplementary items dropped whole across every budgeted article, because the budget left no room once body sections and tables were served. Absent when none were dropped. Re-request the affected articles with a higher `maxCharacters`, or with `sections` narrowed, to receive them.'),
     articles: z
         .array(TruncatedArticleSchema)
         .describe('Per-article accounting, covering only the articles the budget shortened'),
@@ -436,6 +724,10 @@ function budgetRequested(budget) {
 function sectionTextFields(section) {
     return [section.text, ...(section.subsections ?? []).flatMap(sectionTextFields)];
 }
+/** Combined length of the strings given, skipping the absent ones. */
+function totalLength(parts) {
+    return parts.reduce((n, part) => n + (part?.length ?? 0), 0);
+}
 /**
  * Body characters a section carries — its own text plus every nested
  * subsection's. Measured off {@link sectionTextFields} rather than its own walk,
@@ -443,7 +735,49 @@ function sectionTextFields(section) {
  * exactly the fields {@link fitFields} shortens.
  */
 function sectionCharacters(section) {
-    return sectionTextFields(section).reduce((n, text) => n + text.length, 0);
+    return totalLength(sectionTextFields(section));
+}
+/**
+ * Characters a table costs the budget: everything it renders — label, caption,
+ * every cell, footnotes. The whole figure is what admitting the table spends,
+ * and a table is admitted or dropped whole, so there is no partial measure to
+ * take. (#111)
+ */
+function tableCharacters(table) {
+    return totalLength([table.label, table.caption, table.footnotes, ...table.rows.flat()]);
+}
+/**
+ * Characters an asset costs the budget: the text it carries — label, caption,
+ * and the `href` pointer. Positional metadata is excluded, exactly as {@link
+ * tableCharacters} excludes `sectionTitle` and `id`: it places the asset rather
+ * than being content the caller asked for. An asset is admitted or dropped
+ * whole — a caption cut in half is a caption that says something else — so there
+ * is no partial measure to take. (#130)
+ */
+function assetCharacters(asset) {
+    return totalLength([asset.label, asset.caption, asset.href]);
+}
+/**
+ * Admit tables, then assets, in document order until the allowance is spent,
+ * then drop the rest whole and name them. The split is {@link fitWholeItems}'s
+ * prefix cut, the same one `maxResponseCharacters` applies to whole articles.
+ *
+ * Admission stops at the first entry that does not fit rather than skipping past
+ * it to a smaller one further down: the returned set stays a document-order
+ * prefix, so a caller reading it knows where the response stopped instead of
+ * receiving a late entry with nothing saying the earlier ones exist. An entry
+ * that does not fit is never cut either — half a grid reads as a complete table
+ * carrying values that were never deposited, the defect the table extraction
+ * exists to fix, and half a caption says something the deposit does not.
+ * (#111, #130)
+ */
+function fitWholeNamed(items, allowance, measure, name) {
+    const fit = fitWholeItems(items, allowance, measure);
+    return {
+        kept: fit.kept,
+        omittedNames: fit.deferred.map((item, i) => name(item, fit.kept.length + i)),
+        spent: fit.keptCharacters,
+    };
 }
 /**
  * Rebuild a section subtree from `fitted`, consuming one entry per node in the
@@ -530,9 +864,16 @@ function allotSectionBudgets(sizes, budget) {
 /**
  * Apply the character budget to a JATS article's body. Runs as a pure
  * post-processing pass after `applyPmcFilters`, so `sections` / `maxSections` /
- * `includeReferences` and the empty-body signals they feed are unaffected.
- * Titles, abstracts, identifiers, and references are never counted or cut —
- * the budget only spends on body text, keeping every article citable.
+ * `includeReferences` / `includeTables` and the empty-body signals they feed are
+ * unaffected. Titles, abstracts, identifiers, and references are never counted
+ * or cut — the budget spends on body text and table content, keeping every
+ * article citable.
+ *
+ * Body sections are served first, then tables, then assets, each spending what
+ * `maxCharacters` has left, in document order: an item that does not fit is
+ * dropped whole and counted, never truncated into a partial grid or a caption cut
+ * short. With no `maxCharacters` — a bare `maxCharactersPerSection` request —
+ * nothing bounds either list and every entry is kept. (#111, #130)
  *
  * Returns the article untouched (same object identity) when no budget was
  * requested or nothing exceeded it. A section left with zero characters is
@@ -541,11 +882,16 @@ function allotSectionBudgets(sizes, budget) {
  * caller can see which headings exist. (#81)
  */
 function applyPmcBudget(article, budget) {
-    if (!budgetRequested(budget) || article.sections.length === 0) {
+    const tables = article.tables ?? [];
+    const assets = article.assets ?? [];
+    if (!budgetRequested(budget) ||
+        (article.sections.length === 0 && tables.length === 0 && assets.length === 0)) {
         return { article, omittedSections: 0 };
     }
     const sizes = article.sections.map(sectionCharacters);
-    const originalCharacters = sizes.reduce((sum, size) => sum + size, 0);
+    const tablesOriginal = tables.reduce((sum, table) => sum + tableCharacters(table), 0);
+    const assetsOriginal = assets.reduce((sum, asset) => sum + assetCharacters(asset), 0);
+    const originalCharacters = sizes.reduce((sum, size) => sum + size, 0) + tablesOriginal + assetsOriginal;
     const allowances = allotSectionBudgets(sizes, budget);
     const kept = [];
     const sectionReports = [];
@@ -554,7 +900,7 @@ function applyPmcBudget(article, budget) {
     article.sections.forEach((section, i) => {
         const original = sizes[i] ?? 0;
         const fitted = fitFields(sectionTextFields(section), allowances[i] ?? 0);
-        const returned = fitted.reduce((sum, text) => sum + text.length, 0);
+        const returned = totalLength(fitted);
         returnedCharacters += returned;
         sectionReports.push({
             ...(section.title !== undefined && { title: section.title }),
@@ -568,13 +914,40 @@ function applyPmcBudget(article, budget) {
         }
         kept.push(withFittedTexts(section, fitted, { i: 0 }));
     });
-    if (returnedCharacters === originalCharacters && omittedSections === 0) {
+    // Sections are served first, then tables, then assets — each spending whatever
+    // `maxCharacters` has left. A bare per-section budget sets no total, so nothing
+    // bounds either list.
+    const remainingAllowance = () => budget.maxCharacters === undefined
+        ? Number.POSITIVE_INFINITY
+        : Math.max(budget.maxCharacters - returnedCharacters, 0);
+    const fittedTables = fitWholeNamed(tables, remainingAllowance(), tableCharacters, tableDisplayName);
+    returnedCharacters += fittedTables.spent;
+    const omittedTables = fittedTables.omittedNames.length;
+    const fittedAssets = fitWholeNamed(assets, remainingAllowance(), assetCharacters, assetDisplayName);
+    returnedCharacters += fittedAssets.spent;
+    const omittedAssets = fittedAssets.omittedNames.length;
+    if (returnedCharacters === originalCharacters &&
+        omittedSections === 0 &&
+        omittedTables === 0 &&
+        omittedAssets === 0) {
         return { article, omittedSections: 0 };
     }
     return {
-        article: { ...article, sections: kept },
+        article: withAssets(withTables({ ...article, sections: kept }, fittedTables.kept), fittedAssets.kept),
         omittedSections,
-        truncation: { originalCharacters, returnedCharacters, sections: sectionReports },
+        truncation: {
+            originalCharacters,
+            returnedCharacters,
+            sections: sectionReports,
+            ...(omittedTables > 0 && {
+                omittedTables,
+                omittedTableNames: fittedTables.omittedNames,
+            }),
+            ...(omittedAssets > 0 && {
+                omittedAssets,
+                omittedAssetNames: fittedAssets.omittedNames,
+            }),
+        },
     };
 }
 /**
@@ -593,6 +966,66 @@ function applyContentBudget(content, budget) {
         truncation: { originalCharacters: content.length, returnedCharacters: kept.length },
     };
 }
+/** Why a table arrived with no rows, in the reader's terms. */
+const UNEXTRACTABLE_TABLE_EXPLANATIONS = {
+    'cals-tgroup': 'it uses the CALS `<tgroup>` model, which this server does not extract',
+    'graphic-only': 'it was deposited as an image, with no underlying markup to read',
+    'no-rows': 'its markup carried no rows',
+};
+/** How a table is named in a notice: its label, else its id, else its position. */
+function tableDisplayName(table, index) {
+    return table.label ?? table.id ?? `table ${index + 1}`;
+}
+/** How an asset is named in a notice: its label, else its id, else its position. */
+function assetDisplayName(asset, index) {
+    return asset.label ?? asset.id ?? `asset ${index + 1}`;
+}
+/**
+ * Collect the returned tables that carry no cell values. Read off the articles
+ * the response actually ships — after every filter and both budgets — so a table
+ * the `sections` filter removed, or one belonging to a deferred article, is
+ * never named as though the caller received it. (#111)
+ */
+function collectUnextractableTables(articles) {
+    const entries = [];
+    for (const article of articles) {
+        if (article.source !== 'pmc')
+            continue;
+        for (const [index, table] of (article.tables ?? []).entries()) {
+            const reason = table.unextractableReason;
+            if (!reason)
+                continue;
+            entries.push({
+                articleId: articleDisplayId(article),
+                name: tableDisplayName(table, index),
+                reason,
+            });
+        }
+    }
+    return entries;
+}
+/**
+ * Compose the recovery notice for tables returned with a label and caption but
+ * no cells. Without it a table-bearing response carries no response-level signal
+ * that some of the numbers the caller asked for are absent — the per-table
+ * `unextractableReason` only helps a reader who already went looking at that
+ * table. One notice covers the whole response, aggregated across articles, the
+ * way the `sections`-filter miss notice does. (#111)
+ *
+ * The wording turns on recoverability: nothing the caller changes produces these
+ * cells, because the markup does not exist upstream. Tables the character budget
+ * dropped are the opposite case — recoverable by raising `maxCharacters` — so
+ * they stay with the rest of the budget accounting in {@link
+ * buildTruncationNotice} rather than being mixed in here.
+ */
+function buildUnextractableTablesNotice(entries) {
+    const subject = entries.length === 1 ? '1 table was' : `${entries.length} tables were`;
+    const named = entries.map((e) => `${e.name} (${e.articleId}, ${e.reason})`).join(', ');
+    const reasons = [...new Set(entries.map((e) => e.reason))]
+        .map((reason) => `${reason} — ${UNEXTRACTABLE_TABLE_EXPLANATIONS[reason]}`)
+        .join('; ');
+    return `${subject} returned with a label and caption but no cell values: ${named}. Re-calling will not recover the cells (${reasons}); see \`unextractableReason\` on each table.`;
+}
 /**
  * Compose the recovery notice for a budgeted response. Names what was spent and
  * where the detail lives so an agent reading only `content[]` knows the body it
@@ -603,13 +1036,26 @@ function buildTruncationNotice(truncation) {
     const omitted = truncation.omittedSections > 0
         ? ` ${truncation.omittedSections} section(s) were dropped once the budget ran out.`
         : '';
+    // Tables are admitted after sections and only whole, so a dropped one is
+    // absent rather than partial — say so, and name them: a bare count leaves the
+    // reader unable to tell which numbers are missing from what they received.
+    const droppedNames = truncation.articles.flatMap((a) => a.omittedTableNames ?? []);
+    const omittedTables = truncation.omittedTables
+        ? ` ${truncation.omittedTables} table(s) were dropped whole rather than cut mid-row: ${droppedNames.join(', ')}.`
+        : '';
+    // Assets are admitted last and only whole — a caption cut in half says
+    // something the deposit does not — so name them on the same terms.
+    const droppedAssetNames = truncation.articles.flatMap((a) => a.omittedAssetNames ?? []);
+    const omittedAssets = truncation.omittedAssets
+        ? ` ${truncation.omittedAssets} figure/supplementary item(s) were dropped whole rather than returned with a shortened caption: ${droppedAssetNames.join(', ')}.`
+        : '';
     // Name only the budgets the request actually set — pointing at `maxCharacters`
     // when the caller only capped per-section sends them to a knob that is unset.
     const knobs = [
         truncation.maxCharacters !== undefined ? '`maxCharacters`' : undefined,
         truncation.maxCharactersPerSection !== undefined ? '`maxCharactersPerSection`' : undefined,
     ].filter((k) => k !== undefined);
-    return `Full text was shortened to fit the requested character budget: ${truncation.returnedCharacters} of ${truncation.originalCharacters} body characters returned across ${subject} in ${truncation.mode} mode.${omitted} See \`truncation\` for per-article and per-section counts, and raise ${knobs.join(' or ')} or narrow \`sections\` to retrieve more.`;
+    return `Full text was shortened to fit the requested character budget: ${truncation.returnedCharacters} of ${truncation.originalCharacters} body characters returned across ${subject} in ${truncation.mode} mode.${omitted}${omittedTables}${omittedAssets} See \`truncation\` for per-article and per-section counts, and raise ${knobs.join(' or ')} or narrow \`sections\` to retrieve more.`;
 }
 /**
  * Compose the recovery notice for articles the whole-response budget withheld.
@@ -643,7 +1089,7 @@ function countOmittedSections(entry, mode) {
  * recoveries that silently can't happen.
  */
 export function buildFulltextDescription(tiers) {
-    const base = 'Fetch full-text articles from PubMed Central with structured sections and references.';
+    const base = 'Fetch full-text articles from PubMed Central with structured sections, tables, and references.';
     const epmcClause = 'Europe PMC `fullTextXML` (structured JATS for records with a PMC counterpart)';
     const unpaywallClause = 'Unpaywall — publisher-hosted or institutional open-access copies as HTML-as-Markdown or PDF-as-text';
     let fallback;
@@ -711,6 +1157,14 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             .boolean()
             .default(false)
             .describe('Include reference list. Applies to `source=pmc` results only.'),
+        includeTables: z
+            .boolean()
+            .default(true)
+            .describe("Include the article's tables — cells, captions, labels and footnotes. On by default because a dropped table takes its numbers with it. Table-dense articles pay for it: rendered tables typically add 12–17% to an article record and can more than double it. Set false to omit them, or cap the cost with `maxCharacters`, which drops tables it cannot fit whole. Applies to `source=pmc` results only."),
+        includeAssets: z
+            .boolean()
+            .default(true)
+            .describe("Include the article's figures and supplementary material — `assets[]`, each with its label, caption, enclosing section and deposit pointer. On by default because it is cheaper than tables: a median asset-bearing article grows about 10%, and the body prose already refers to these by label. Set false to omit them, which also removes the `[Figure: …]` / `[Supplementary: …]` markers from the section text, since without the array they point at nothing. Prose-shaped blocks — lists, definition lists, block quotes, boxed text, preformatted blocks, displayed formulae — are section text rather than assets and this switch never affects them. Applies to `source=pmc` results only."),
         maxSections: z
             .number()
             .int()
@@ -721,14 +1175,14 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         sections: z
             .array(z.string())
             .optional()
-            .describe('Filter to specific sections by title, case-insensitive (e.g. ["Introduction", "Methods", "Results", "Discussion"]). Applies to `source=pmc` results only.'),
+            .describe('Filter to specific sections by title (e.g. ["Introduction", "Methods", "Results", "Discussion"]). A term matches a section or subsection title at any nesting depth, case-insensitively, as a substring — "resul" matches "Results". A section whose own title matches is returned whole; one kept only because a nested subsection matched keeps its heading as a breadcrumb, with its own text cleared and only the matching branch beneath it. Tables and assets narrow with the filter: one whose section did not survive, or that names no section, is dropped. Applies to `source=pmc` results only.'),
         maxCharacters: z
             .number()
             .int()
             .min(1)
             .max(1_000_000)
             .optional()
-            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text, or the `source=unpaywall` `content` body; titles, abstracts, identifiers, and references are never counted or shortened. Applied after `sections`, `maxSections`, and `includeReferences`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
+            .describe('Per-article budget for body text, in characters. Counts `source=pmc` section and subsection text — which carries the inline blocks the parser renders in place, such as lists, definition lists, block quotes, boxed text, preformatted blocks and displayed formulae — plus table label, caption, cell and footnote text and asset label, caption and `href` text; or the `source=unpaywall` `content` body. Titles, abstracts, identifiers, and references are never counted or shortened. The counted unit is that text alone — the Markdown grid `content[]` renders around the cells (pipes, padding, the divider row, headings) is scaffolding this budget does not measure, so a table renders longer than it costs here. Sections are served first, then tables, then assets, each spending what is left, in document order — admission stops at the first entry that does not fit, and every entry from there on is dropped whole rather than cut mid-row or returned with a shortened caption, counted in `truncation.omittedTables` / `truncation.omittedAssets` and named in `truncation.articles[].omittedTableNames` / `omittedAssetNames`. Applied after `sections`, `maxSections`, `includeReferences`, `includeTables`, and `includeAssets`, so semantic filtering is unaffected. This knob alone bounds only bodies: the response-wide ceiling it implies is this value times the number of articles returned, plus every uncounted field. Use `maxResponseCharacters` for a true whole-response ceiling. Omit for the full body.'),
         maxCharactersPerSection: z
             .number()
             .int()
@@ -763,17 +1217,18 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         truncation: TruncationSchema.optional(),
         deferred: DeferredSchema.optional(),
     }),
-    // Recovery guidance for four cases — a `sections` filter that removed every
+    // Recovery guidance for five cases — a `sections` filter that removed every
     // body section (#80), a record the chain could only retrieve as front matter
-    // (#86), a body the per-article character budget shortened (#81), and articles
-    // the whole-response budget withheld (#100). Agent-facing context surfaced via
+    // (#86), a table returned with no cell values (#111), a body the per-article
+    // character budget shortened (#81), and articles the whole-response budget
+    // withheld (#100). Agent-facing context surfaced via
     // ctx.enrich.notice() to structuredContent and content[]; absent when none
     // applies.
     enrichment: {
         notice: z
             .string()
             .optional()
-            .describe('Optional guidance for a partial or empty body. A `sections`-filter miss names the requested terms and affected article id(s) and suggests retrying without `sections` or using broader headings. A metadata-only record names the id(s) the chain could retrieve as front matter only and points at `pubmed_fetch_articles` for the abstract. A budgeted response names the characters returned versus carried and points at `truncation`. A response-wide budget that deferred articles names the ids to re-request. Absent when none of those applies.'),
+            .describe('Optional guidance for a partial or empty body. A `sections`-filter miss names the requested terms and affected article id(s) and suggests retrying without `sections` or using broader headings. A metadata-only record names the id(s) the chain could retrieve as front matter only and points at `pubmed_fetch_articles` for the abstract. A table returned with no cell values names the affected table(s), the article each came from, and why the cells cannot be recovered. A budgeted response names the characters returned versus carried and points at `truncation`. A response-wide budget that deferred articles names the ids to re-request. Absent when none of those applies.'),
         truncated: z
             .boolean()
             .optional()
@@ -1119,6 +1574,17 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         // ── Stage 3: Unpaywall fallback ─────────────────────────────────────────
         const unpaywall = getUnpaywallService();
         const fallbackArticles = [];
+        // Detail of a DOI-backfill lookup that threw, per branch. A candidate still
+        // DOI-less after one of these is an unknown, not a settled absence: it
+        // reports `doi-lookup-failed` rather than `no-doi`. (#119)
+        let pmcidDoiLookupFailure;
+        let pmidDoiLookupFailure;
+        /** The Unpaywall tier entry for a candidate that reached the stage with no DOI. */
+        const doilessTierEntry = (failure) => ({
+            tier: 'unpaywall',
+            outcome: failure ? 'doi-lookup-failed' : 'no-doi',
+            ...(failure && { detail: failure }),
+        });
         // `pmcids` input reaches Unpaywall on the DOI the chain already holds: the
         // EPMC stage searches by PMCID and its hit carries one, captured on non-hit
         // outcomes too. PMCIDs EPMC never resolved fall back to the PMC ID
@@ -1161,8 +1627,9 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                         });
                     }
                     catch (error) {
+                        pmcidDoiLookupFailure = error instanceof Error ? error.message : String(error);
                         ctx.log.warning('Failed to resolve PMCID → DOI for the Unpaywall fallback', {
-                            error: error instanceof Error ? error.message : String(error),
+                            error: pmcidDoiLookupFailure,
                             pmcidCount: needDoi.length,
                         });
                     }
@@ -1176,12 +1643,15 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                         pmcId,
                         result: candidate.doi
                             ? await resolveUnpaywall({ pmcId, doi: candidate.doi, budget }, unpaywall, ctx)
-                            : { unavailable: { reason: 'no-doi' } },
+                            : undefined,
                     };
                 }));
                 for (const { pmcId, result } of outcomes) {
                     const inputId = pmcidToInputId.get(pmcId) ?? pmcId;
-                    if ('article' in result) {
+                    if (result === undefined) {
+                        chainByInput.get(inputId)?.push(doilessTierEntry(pmcidDoiLookupFailure));
+                    }
+                    else if ('article' in result) {
                         fallbackArticles.push(result.article);
                         inputIdByArticle.set(result.article, inputId);
                         if (result.truncation)
@@ -1215,19 +1685,21 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     });
                 }
                 catch (error) {
+                    pmidDoiLookupFailure = error instanceof Error ? error.message : String(error);
                     ctx.log.warning('Failed to batch-fetch DOIs from PubMed for Unpaywall fallback', {
-                        error: error instanceof Error ? error.message : String(error),
+                        error: pmidDoiLookupFailure,
                         pmidCount: needDoi.length,
                     });
                 }
             }
             if (!unpaywall) {
-                // `fetchPubmedDois` has already run, so the DOI state is settled here.
-                // A candidate with no DOI could not have reached Unpaywall configured
-                // or not — that is `no-doi`, a real answer, not an incomplete search.
+                // `fetchPubmedDois` has already run, so a candidate with no DOI could
+                // not have reached Unpaywall configured or not — that is `no-doi`, a
+                // real answer, not an incomplete search. Unless the lookup itself
+                // threw, in which case the DOI state is unknown rather than absent.
                 for (const c of pmidFallbackCandidates) {
                     if (!c.doi) {
-                        chainByInput.get(c.pmid)?.push({ tier: 'unpaywall', outcome: 'no-doi' });
+                        chainByInput.get(c.pmid)?.push(doilessTierEntry(pmidDoiLookupFailure));
                         continue;
                     }
                     chainByInput.get(c.pmid)?.push({
@@ -1243,10 +1715,13 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                     candidate,
                     result: candidate.doi
                         ? await resolveUnpaywall({ pmid: candidate.pmid, doi: candidate.doi, budget }, unpaywall, ctx)
-                        : { unavailable: { reason: 'no-doi' } },
+                        : undefined,
                 })));
                 for (const { candidate, result } of outcomes) {
-                    if ('article' in result) {
+                    if (result === undefined) {
+                        chainByInput.get(candidate.pmid)?.push(doilessTierEntry(pmidDoiLookupFailure));
+                    }
+                    else if ('article' in result) {
                         fallbackArticles.push(result.article);
                         inputIdByArticle.set(result.article, candidate.pmid);
                         if (result.truncation)
@@ -1361,6 +1836,11 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
             unavailable: unavailable.length,
             ...(deferred && { deferred: deferred.deferredCount }),
         });
+        // Summed off the per-article entries rather than carried through every
+        // stage, so a deferred article's dropped tables leave the roll-up together
+        // with its entry when the splice above removes it. (#111)
+        const omittedTables = truncatedArticles.reduce((n, a) => n + (a.omittedTables ?? 0), 0);
+        const omittedAssets = truncatedArticles.reduce((n, a) => n + (a.omittedAssets ?? 0), 0);
         // Rolled up only when the budget actually removed characters, so an
         // under-budget request returns exactly what it did before the budget
         // controls existed. (#81)
@@ -1374,6 +1854,8 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
                 originalCharacters: truncatedArticles.reduce((n, a) => n + a.originalCharacters, 0),
                 returnedCharacters: truncatedArticles.reduce((n, a) => n + a.returnedCharacters, 0),
                 omittedSections,
+                ...(omittedTables > 0 && { omittedTables }),
+                ...(omittedAssets > 0 && { omittedAssets }),
                 articles: truncatedArticles,
             }
             : undefined;
@@ -1386,6 +1868,10 @@ export const fetchFulltextTool = tool('pubmed_fetch_fulltext', {
         const unrecoveredBodyless = [...bodylessInputIds].filter((id) => !recoveredIds.has(id));
         if (unrecoveredBodyless.length > 0)
             notices.push(buildBodylessNotice(unrecoveredBodyless));
+        const unextractableTables = collectUnextractableTables(articles);
+        if (unextractableTables.length > 0) {
+            notices.push(buildUnextractableTablesNotice(unextractableTables));
+        }
         if (truncation) {
             notices.push(buildTruncationNotice(truncation));
             ctx.enrich({ truncated: true });
@@ -1541,8 +2027,11 @@ async function runEpmcStage(epmc, args) {
         pmidOutcomes.set(run.c.pmid, run.outcome);
         if (run.article)
             collectHit(run.c.pmid, { ...run, article: run.article });
+        // A DOI the EPMC hit carried is evidence the next stage needs, whatever the
+        // fetch outcome was — merge it in like the pmcid branch below, so Unpaywall
+        // gets it without a redundant PubMed metadata round-trip. (#119)
         else
-            remainingPmid.push(run.c);
+            remainingPmid.push(run.doi && !run.c.doi ? { ...run.c, doi: run.doi } : run.c);
     }
     for (const run of pmcidResults) {
         pmcidOutcomes.set(run.c.normalized, run.outcome);
@@ -1849,6 +2338,7 @@ function unpaywallReasonToTierOutcome(reason) {
     switch (reason) {
         case 'no-body':
         case 'no-doi':
+        case 'doi-lookup-failed':
         case 'no-oa':
         case 'fetch-failed':
         case 'parse-failed':
@@ -1900,6 +2390,11 @@ function reasonFromChain(chain) {
             return 'no-body';
         case 'unpaywall:no-doi':
             return 'no-doi';
+        // Its own case, never folded into the `unpaywall:no-doi` → `not-found`
+        // collapse above: that collapse says record absence is the specific signal,
+        // and a lookup that never answered has established no absence at all. (#119)
+        case 'unpaywall:doi-lookup-failed':
+            return 'doi-lookup-failed';
         case 'unpaywall:no-oa':
             return 'no-oa';
         case 'unpaywall:fetch-failed':
@@ -1942,7 +2437,9 @@ function formatUnqueriedTiers(tiers, chain) {
  * separators — so the numbers stay greppable. (#81)
  */
 function formatTruncation(t, lines) {
-    lines.push(`\n**Truncated (${t.mode} mode):** ${t.returnedCharacters} of ${t.originalCharacters} body characters returned across ${t.articles.length} article(s); ${t.omittedSections} section(s) omitted`);
+    const tablesOmitted = t.omittedTables === undefined ? '' : `; ${t.omittedTables} table(s) omitted whole`;
+    const assetsOmitted = t.omittedAssets === undefined ? '' : `; ${t.omittedAssets} asset(s) omitted whole`;
+    lines.push(`\n**Truncated (${t.mode} mode):** ${t.returnedCharacters} of ${t.originalCharacters} body characters returned across ${t.articles.length} article(s); ${t.omittedSections} section(s) omitted${tablesOmitted}${assetsOmitted}`);
     const budgets = [
         t.maxCharacters === undefined ? undefined : `maxCharacters ${t.maxCharacters}`,
         t.maxCharactersPerSection === undefined
@@ -1952,7 +2449,13 @@ function formatTruncation(t, lines) {
     if (budgets.length)
         lines.push(`Budget applied: ${budgets.join(', ')}`);
     for (const a of t.articles) {
-        lines.push(`- ${a.id} (${a.source}): ${a.returnedCharacters} of ${a.originalCharacters} characters`);
+        const tablesDropped = a.omittedTables === undefined
+            ? ''
+            : `, ${a.omittedTables} table(s) dropped whole: ${(a.omittedTableNames ?? []).join(', ')}`;
+        const assetsDropped = a.omittedAssets === undefined
+            ? ''
+            : `, ${a.omittedAssets} asset(s) dropped whole: ${(a.omittedAssetNames ?? []).join(', ')}`;
+        lines.push(`- ${a.id} (${a.source}): ${a.returnedCharacters} of ${a.originalCharacters} characters${tablesDropped}${assetsDropped}`);
         for (const s of a.sections ?? []) {
             lines.push(`  - ${s.title ?? 'untitled section'} — ${s.returnedCharacters} of ${s.originalCharacters} characters (truncated: ${s.truncated})`);
         }
@@ -2021,6 +2524,10 @@ function formatPmcArticle(a, lines, truncation) {
         lines.push(`\n#### Abstract\n${a.abstract}`);
     for (const sec of a.sections)
         formatSection(sec, lines, 4);
+    if (a.tables?.length)
+        formatTables(a.tables, lines);
+    if (a.assets?.length)
+        formatAssets(a.assets, lines);
     if (a.references?.length) {
         lines.push(`\n#### References (${a.references.length})`);
         for (const ref of a.references) {
@@ -2029,6 +2536,112 @@ function formatPmcArticle(a, lines, truncation) {
         }
     }
 }
+/**
+ * Render every table as a Markdown grid, so a `content[]` reader gets the same
+ * cells `structuredContent` carries rather than a note that tables exist. (#111)
+ *
+ * Cell text goes through {@link escapeMarkdownTableCell} — the inline escape
+ * plus the `|` a cell cannot carry raw. The parser expands `colspan` and
+ * `rowspan`, so a well-formed table arrives rectangular and every value renders
+ * under the header it belongs to; a row still short of the widest is padded on
+ * the right with empty cells only, never a neighbour's value.
+ */
+function formatTables(tables, lines) {
+    lines.push(`\n#### Tables (${tables.length})`);
+    for (const table of tables) {
+        const heading = [table.label, table.caption].filter(Boolean).join(' — ');
+        lines.push(`\n##### ${escapeMarkdownInline(heading || 'Table')}`);
+        const meta = [
+            table.sectionTitle ? `Section: ${escapeMarkdownInline(table.sectionTitle)}` : undefined,
+            table.id ? `id: ${escapeMarkdownInline(table.id)}` : undefined,
+            describeHeaderRows(table),
+        ].filter((part) => part !== undefined);
+        if (meta.length)
+            lines.push(`*${meta.join(' · ')}*`);
+        if (table.unextractableReason) {
+            lines.push(`\n> Table body could not be read (${table.unextractableReason}) — ${UNEXTRACTABLE_TABLE_EXPLANATIONS[table.unextractableReason]}. The label and caption above are all this deposit carries; no cell values exist to return.`);
+        }
+        if (table.rows.length > 0)
+            lines.push(...renderTableGrid(table.rows, table.headerRowCount));
+        if (table.footnotes)
+            lines.push(`\nFootnotes: ${escapeMarkdownInline(table.footnotes)}`);
+    }
+}
+/**
+ * Render every figure and supplementary item, so a `content[]` reader gets the
+ * same caption, pointer and placement `structuredContent` carries rather than a
+ * count saying they exist. Each field of `AssetSchema` appears here — that is
+ * what `format-parity` verifies. (#130)
+ *
+ * Label, caption and `href` go through {@link escapeMarkdownInline}: the parser
+ * stores the raw upstream text, and a caption carrying `[`, `*` or a tag-shaped
+ * `<` would otherwise form a link, emphasis or raw HTML at the render boundary.
+ *
+ * The note about `href` is worth its line: the value is a filename inside the PMC
+ * deposit, and an agent that reads it as a URL will spend a request on a 404 for
+ * every figure in the article.
+ */
+function formatAssets(assets, lines) {
+    lines.push(`\n#### Assets (${assets.length})`);
+    lines.push(`\n> \`file\` is the pointer exactly as deposited — a name inside the PMC deposit, not a fetchable URL. Open the article at the PMC link above to view it.`);
+    for (const asset of assets) {
+        const heading = [asset.label, asset.caption].filter(Boolean).join(' — ');
+        lines.push(`\n##### ${escapeMarkdownInline(heading || 'Asset')}`);
+        const meta = [
+            asset.assetType,
+            asset.sectionTitle ? `Section: ${escapeMarkdownInline(asset.sectionTitle)}` : undefined,
+            asset.id ? `id: ${escapeMarkdownInline(asset.id)}` : undefined,
+            asset.href ? `file: ${escapeMarkdownInline(asset.href)}` : undefined,
+        ].filter((part) => part !== undefined);
+        lines.push(`*${meta.join(' · ')}*`);
+    }
+}
+/**
+ * The meta-line clause describing a table's header rows.
+ *
+ * A Markdown grid carries exactly one header row, so a table declaring several
+ * has them folded into it — say how many were folded, or the grid understates
+ * what the deposit declared. A table declaring none still needs the empty header
+ * row Markdown requires above the divider; naming that keeps a reader from
+ * taking the blank row for a header the publisher deposited and left empty.
+ */
+function describeHeaderRows(table) {
+    if (table.rows.length === 0)
+        return;
+    if (table.headerRowCount === 0)
+        return 'header rows: none declared — every row below is data';
+    if (table.headerRowCount === 1)
+        return 'header rows: 1';
+    return `header rows: ${table.headerRowCount} (folded into one)`;
+}
+/**
+ * Join one grid column's header cells into the single header path Markdown can
+ * carry. Consecutive repeats — what expanding a `colspan` produces — collapse to
+ * one, so a group header spanning three columns reads once per column rather
+ * than three times in each.
+ */
+function foldHeaderColumn(headerRows, column) {
+    const path = [];
+    for (const row of headerRows) {
+        const cell = row[column] ?? '';
+        if (cell && cell !== path.at(-1))
+            path.push(cell);
+    }
+    return path.join(' · ');
+}
+/** One table's rows as Markdown grid lines, preceded by a blank line. */
+function renderTableGrid(rows, headerRowCount) {
+    const columns = rows.reduce((widest, row) => Math.max(widest, row.length), 0);
+    const renderRow = (cells) => `| ${Array.from({ length: columns }, (_, i) => escapeMarkdownTableCell(cells[i] ?? '')).join(' | ')} |`;
+    const headerRows = rows.slice(0, headerRowCount);
+    const header = Array.from({ length: columns }, (_, i) => foldHeaderColumn(headerRows, i));
+    return [
+        '',
+        renderRow(header),
+        `| ${Array.from({ length: columns }, () => '---').join(' | ')} |`,
+        ...rows.slice(headerRowCount).map(renderRow),
+    ];
+}
 function formatUnpaywallArticle(a, lines, truncation) {
     const requestedId = a.pmcId ? `PMCID ${a.pmcId}` : a.pmid ? `PMID ${a.pmid}` : `DOI ${a.doi}`;
     const heading = a.title ?? requestedId;