@inflexa-ai/harness 0.20.0 → 0.21.0

package/dist/report-render/types.d.ts

@@ -7,10 +7,14 @@
  * serves. Thus a `figure` here carries a ready `src` string, and the renderer holds no policy about the
  * image bytes.
  */
+import type { DataAsset } from "./table-data.js";
 /**
  * The value that one block resolves to, as a closed union. A `scalar` gives one number or one string. A
  * `table` gives the rows and the optional column order. A `figure` gives a ready source string. A
  * `citation` echoes one external id.
+ *
+ * A `table` carries `total` when a row bound cut the rows of the artifact. The renderer states the shown
+ * count against it. A table with no bound carries none, and the row count answers for it.
  */
 export type RenderValue = {
     type: "scalar";
@@ -19,6 +23,7 @@ export type RenderValue = {
     type: "table";
     rows: Array<Record<string, string | number>>;
     columns?: string[];
+    total?: number;
 } | {
     type: "figure";
     src: string;
@@ -37,3 +42,13 @@ export interface RenderProblem {
 }
 /** The value map that the renderer takes, keyed by block id. */
 export type RenderValues = Record<string, RenderValue>;
+/**
+ * One rendered page: the HTML string, and each data asset that the page references.
+ *
+ * The renderer writes no file. Thus it gives the asset bytes back to the caller, and the caller stages
+ * them beside the page. A document with no table gives an empty list, and its page references none.
+ */
+export interface RenderedPage {
+    html: string;
+    dataAssets: DataAsset[];
+}

package/dist/report-render/value-bridge.js

@@ -69,12 +69,16 @@ export function bridgeValues(resolutions, figureSrc) {
 /**
  * Map a resolved table onto a render table. The explicit column order carries through when it is present,
  * and it stays absent otherwise, thus the renderer keeps its first-row order as the default.
+ *
+ * The pre-bound total carries through the same way. The resolution is the one step that reads the whole
+ * artifact, thus the renderer takes that count and never counts again.
  */
 function tableValue(value) {
+    const total = value.total === undefined ? {} : { total: value.total };
     if (value.columns !== undefined) {
-        return { type: "table", rows: value.rows, columns: value.columns };
+        return { type: "table", rows: value.rows, columns: value.columns, ...total };
     }
-    return { type: "table", rows: value.rows };
+    return { type: "table", rows: value.rows, ...total };
 }
 /** Make one mismatch that names the block, its kind, the resolved type that it needs, and the type that arrived. */
 function mismatch(blockId, blockKind, expected, actual) {

package/dist/report-render/views/chart-view.d.ts

@@ -1,14 +1,21 @@
 /**
- * The chart panel markup.
+ * The chart card markup.
  *
  * The bootstrap in `page.ts` reads the option from the next element sibling of the container. Thus the
  * `<script type="application/json">` element MUST follow the container div with no element between them.
  *
- * The panel is the window-chrome form: the three dots on the left, the title in the center, and the
- * `CORTEX` badge on the right. It is the one component with rounded corners. The chart body carries a fixed
+ * The card is the square corner-accent form of the table and the figure, with the mono title line over it. A
+ * report is a document, thus the card wears no application-window costume. The chart body carries a fixed
  * height, because the chart runtime measures the container and a container with no height shows no chart.
  */
 import type { ChartBlock } from "../../contracts/report-blocks.js";
 import type { EchartOption } from "../chart.js";
-/** Render the panel markup for a chart. */
-export declare function renderChart(block: ChartBlock, option: EchartOption): string;
+import type { ReferenceLedger } from "../references.js";
+/**
+ * Render the card markup for a chart.
+ *
+ * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
+ * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
+ * same line.
+ */
+export declare function renderChart(block: ChartBlock, ledger: ReferenceLedger, option: EchartOption): string;

package/dist/report-render/views/chart-view.js

@@ -1,26 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
 /**
- * The chart panel markup.
+ * The chart card markup.
  *
  * The bootstrap in `page.ts` reads the option from the next element sibling of the container. Thus the
  * `<script type="application/json">` element MUST follow the container div with no element between them.
  *
- * The panel is the window-chrome form: the three dots on the left, the title in the center, and the
- * `CORTEX` badge on the right. It is the one component with rounded corners. The chart body carries a fixed
+ * The card is the square corner-accent form of the table and the figure, with the mono title line over it. A
+ * report is a document, thus the card wears no application-window costume. The chart body carries a fixed
  * height, because the chart runtime measures the container and a container with no height shows no chart.
  */
 import { raw } from "hono/html";
+import { Marker } from "./references-view.js";
 import { scriptJson } from "../script-json.js";
-/** The product badge of a chart panel. */
-const PANEL_BADGE = "CORTEX";
-/** Render the panel markup for a chart. */
-export function renderChart(block, option) {
+/**
+ * Render the card markup for a chart.
+ *
+ * The whole-table binding joins the reference ladder, thus the title line carries the marker and the
+ * appendix names the artifact that the chart plots. A chart with no title still shows its marker on the
+ * same line.
+ */
+export function renderChart(block, ledger, option) {
+    const n = ledger.mark(block.binding);
     const containerId = chartContainerId(block.id);
     // The JSON goes to the page through `raw()`, thus `scriptJson` is the sole guard of this sink. It
     // replaces every `<` with `\u003c`, thus a `</script` sequence in a string cell cannot close the
     // element early. The JSON parser reads `\u003c` as `<`, thus the option value stays exact.
     const json = scriptJson(option);
-    return String(_jsxs("div", { class: "report-chart", children: [_jsxs("div", { class: "window-chrome", children: [_jsxs("div", { class: "window-chrome-bar", children: [_jsxs("div", { class: "chrome-dots", children: [_jsx("span", { class: "chrome-dot dot-1" }), _jsx("span", { class: "chrome-dot dot-2" }), _jsx("span", { class: "chrome-dot dot-3" })] }), block.title !== undefined ? _jsx("span", { class: "window-chrome-title", children: block.title }) : null, _jsx("span", { class: "window-chrome-badge", children: PANEL_BADGE })] }), _jsxs("div", { class: "window-chrome-body", children: [_jsx("div", { id: containerId, "data-echarts-id": block.id, class: "chart-container" }), _jsx("script", { type: "application/json", children: raw(json) })] })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
+    return String(_jsxs("div", { class: "report-chart", children: [_jsxs("div", { class: "report-chart-title", children: [block.title, _jsx(Marker, { n: n })] }), _jsxs("div", { class: "report-chart-card corner-accents", children: [_jsx("div", { id: containerId, "data-echarts-id": block.id, class: "chart-container" }), _jsx("script", { type: "application/json", children: raw(json) })] }), block.caption !== undefined ? _jsx("p", { class: "report-caption", children: block.caption }) : null] }));
 }
 /** The container id derives from the block id, thus the id stays stable across renders. */
 function chartContainerId(blockId) {

package/dist/report-render/views/page-view.d.ts

@@ -1,17 +1,24 @@
 /**
- * The page assembly: the hero, the bands, the reference band, and the footer.
+ * The page assembly: the hero, the bands, the appendix band, and the footer.
  *
- * The skeleton inlines the style rules in the head, and it puts the three scripts at the end of the body.
- * The order of the three scripts is a contract. The theme registration runs before the chart bootstrap,
- * thus each chart finds its theme. The fade-in observer also runs before the chart bootstrap, thus the
- * bootstrap finds the reveal gate and it signals readiness after the first reveal pass. The navigation, the
- * main content, and the reference frame arrive as already-escaped markup strings, thus `raw()` inserts them
- * byte for byte.
+ * The skeleton inlines the style rules in the head, and it puts the page scripts at the end of the body.
+ * The script order is a contract. The theme registration runs before the chart bootstrap, thus each chart
+ * finds its theme. The fade-in observer also runs before the chart bootstrap, thus the bootstrap finds the
+ * reveal gate and it signals readiness after the first reveal pass. The grid boot runs before the chart
+ * bootstrap too, thus every grid stands before the page signals that it is ready. The scrollspy reads the
+ * sections alone, thus its position is free. The navigation, the main content, and the reference frame
+ * arrive as already-escaped markup strings, thus `raw()` inserts them byte for byte.
  *
  * One band holds one top-level section. The band index drives the alternation of the background and of the
  * texture, thus a caller that adds a band passes the next index.
+ *
+ * The container gives the full-bleed gutter of a region, and the content column inside it gives the one
+ * measure of the page. The hero, each band, and the footer use the same pair. Thus every block kind reads at
+ * one width, and the title over them sits on the same left edge.
  */
-import type { ReferenceLedger } from "../references.js";
+import type { DataAsset } from "../table-data.js";
+import type { CitationRecords } from "../../report-model/reference-resolver.js";
+import type { DerivationChains, ReferenceLedger } from "../references.js";
 /**
  * Wrap already-escaped markup in one full-bleed band. An even index gives the white background and the dot
  * texture, and an odd index gives the slate background and the grid texture. The noise texture lies over
@@ -19,13 +26,27 @@ import type { ReferenceLedger } from "../references.js";
  */
 export declare function renderBand(index: number, inner: string): string;
 /**
- * Wrap the reference list in the final band. An empty ledger gives an empty string, thus the page shows no
- * empty reference band. The index continues the band alternation of the sections.
+ * Wrap the one appendix in a band of its own, under the one title.
+ *
+ * The two reference kinds answer different questions, but one marker notation sends the reader to both.
+ * Thus one list serves them, and the kind tag of an entry states which question it answers.
+ *
+ * An empty ledger renders no band. The index continues the band alternation of the sections, thus the
+ * appendix takes the next surface. The records carry the bibliography of each cited key, and a ledger with
+ * no citation reads none of them. The chains carry the derivation of each derived path, and an entry of
+ * such a path states it.
  */
-export declare function renderReferenceSection(ledger: ReferenceLedger, index: number): string;
+export declare function renderReferenceSection(ledger: ReferenceLedger, index: number, records?: CitationRecords, chains?: DerivationChains): string;
 /**
- * Assemble the page from the title, the navigation, the main content, and the reference frame. The title
- * passes through the runtime as text, and the runtime escapes it. The reference frame is optional, thus
- * an empty frame adds no markup.
+ * Assemble the page from the title, the navigation, the main content, the reference frame, and the data
+ * assets. The title passes through the runtime as text, and the runtime escapes it. The reference frame is
+ * optional, thus an empty frame adds no markup.
+ *
+ * Each data asset rides a classic `script` tag at the end of the body, and the decoder runs after the last
+ * of them. Thus every payload is registered before any reader looks. A page with no asset carries no tag
+ * and no decoder.
+ *
+ * `grids` states that the content holds a grid mount. The grid runtime weighs about two megabytes, thus a
+ * page whose only payload feeds a chart references neither the runtime nor the grid boot.
  */
-export declare function assemblePage(title: string, nav: string, content: string, references: string): string;
+export declare function assemblePage(title: string, nav: string, content: string, references: string, dataAssets: readonly DataAsset[], grids: boolean): string;

package/dist/report-render/views/page-view.js

@@ -1,26 +1,34 @@
 import { jsx as _jsx, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
 /**
- * The page assembly: the hero, the bands, the reference band, and the footer.
+ * The page assembly: the hero, the bands, the appendix band, and the footer.
  *
- * The skeleton inlines the style rules in the head, and it puts the three scripts at the end of the body.
- * The order of the three scripts is a contract. The theme registration runs before the chart bootstrap,
- * thus each chart finds its theme. The fade-in observer also runs before the chart bootstrap, thus the
- * bootstrap finds the reveal gate and it signals readiness after the first reveal pass. The navigation, the
- * main content, and the reference frame arrive as already-escaped markup strings, thus `raw()` inserts them
- * byte for byte.
+ * The skeleton inlines the style rules in the head, and it puts the page scripts at the end of the body.
+ * The script order is a contract. The theme registration runs before the chart bootstrap, thus each chart
+ * finds its theme. The fade-in observer also runs before the chart bootstrap, thus the bootstrap finds the
+ * reveal gate and it signals readiness after the first reveal pass. The grid boot runs before the chart
+ * bootstrap too, thus every grid stands before the page signals that it is ready. The scrollspy reads the
+ * sections alone, thus its position is free. The navigation, the main content, and the reference frame
+ * arrive as already-escaped markup strings, thus `raw()` inserts them byte for byte.
  *
  * One band holds one top-level section. The band index drives the alternation of the background and of the
  * texture, thus a caller that adds a band passes the next index.
+ *
+ * The container gives the full-bleed gutter of a region, and the content column inside it gives the one
+ * measure of the page. The hero, each band, and the footer use the same pair. Thus every block kind reads at
+ * one width, and the title over them sits on the same left edge.
  */
 import { raw } from "hono/html";
-import { ASSET_HEAD, CHART_BOOTSTRAP, FADE_IN_OBSERVER } from "../page.js";
+import { ASSET_HEAD, CHART_BOOTSTRAP, FADE_IN_OBSERVER, GRID_ASSET_HEAD, GRID_BOOTSTRAP, SECTION_SPY, TABLE_DATA_DECODER } from "../page.js";
+import { stagedSource } from "../assets.js";
 import { DESIGN_CSS, ECHARTS_THEME, ECHARTS_THEME_NAME } from "../design.js";
-import { renderReferenceList } from "./references-view.js";
+import { renderReferences } from "./references-view.js";
 import { scriptJson } from "../script-json.js";
 /** The constant eyebrow of the hero. The render reads no clock, thus the hero carries no date. */
 const HERO_EYEBROW = "INFLEXA · ANALYSIS REPORT";
 /** The constant note of the footer. */
-const FOOTER_NOTE = "Powered by Inflexa Cortex";
+const FOOTER_NOTE = "Powered by Inflexa";
+/** The title of the one appendix. It holds each artifact and each paper that the report names. */
+const REFERENCES_TITLE = "References";
 /**
  * The theme object as script-safe JSON. `scriptJson` replaces every `<` with `\u003c`, thus a later edit
  * that adds a `<` to the theme stays safe inside the script sink. The JSON parser reads `\u003c` as `<`, thus
@@ -44,26 +52,40 @@ const THEME_REGISTRATION = `(function () {
  */
 export function renderBand(index, inner) {
     const surface = index % 2 === 0 ? "report-band-white texture-dots" : "report-band-slate texture-grid";
-    return String(_jsx("section", { class: `report-band ${surface} texture-noise`, children: _jsx("div", { class: "report-container fade-in", children: raw(inner) }) }));
+    return String(_jsx("section", { class: `report-band ${surface} texture-noise`, children: _jsx("div", { class: "report-container fade-in", children: _jsx("div", { class: "report-content", children: raw(inner) }) }) }));
 }
 /**
- * Wrap the reference list in the final band. An empty ledger gives an empty string, thus the page shows no
- * empty reference band. The index continues the band alternation of the sections.
+ * Wrap the one appendix in a band of its own, under the one title.
+ *
+ * The two reference kinds answer different questions, but one marker notation sends the reader to both.
+ * Thus one list serves them, and the kind tag of an entry states which question it answers.
+ *
+ * An empty ledger renders no band. The index continues the band alternation of the sections, thus the
+ * appendix takes the next surface. The records carry the bibliography of each cited key, and a ledger with
+ * no citation reads none of them. The chains carry the derivation of each derived path, and an entry of
+ * such a path states it.
  */
-export function renderReferenceSection(ledger, index) {
-    const list = renderReferenceList(ledger);
-    if (list === "") {
+export function renderReferenceSection(ledger, index, records, chains) {
+    const references = renderReferences(ledger, records, chains);
+    if (references === "") {
         return "";
     }
-    const heading = String(_jsx("h2", { class: "report-heading report-heading-2", children: "References" }));
-    return renderBand(index, heading + list);
+    const heading = String(_jsx("h2", { class: "report-heading report-heading-3 report-ref-title", children: REFERENCES_TITLE }));
+    return renderBand(index, heading + references);
 }
 /**
- * Assemble the page from the title, the navigation, the main content, and the reference frame. The title
- * passes through the runtime as text, and the runtime escapes it. The reference frame is optional, thus
- * an empty frame adds no markup.
+ * Assemble the page from the title, the navigation, the main content, the reference frame, and the data
+ * assets. The title passes through the runtime as text, and the runtime escapes it. The reference frame is
+ * optional, thus an empty frame adds no markup.
+ *
+ * Each data asset rides a classic `script` tag at the end of the body, and the decoder runs after the last
+ * of them. Thus every payload is registered before any reader looks. A page with no asset carries no tag
+ * and no decoder.
+ *
+ * `grids` states that the content holds a grid mount. The grid runtime weighs about two megabytes, thus a
+ * page whose only payload feeds a chart references neither the runtime nor the grid boot.
  */
-export function assemblePage(title, nav, content, references) {
+export function assemblePage(title, nav, content, references, dataAssets, grids) {
     return ("<!doctype html>" +
-        String(_jsxs("html", { lang: "en", children: [_jsxs("head", { children: [_jsx("meta", { charset: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("title", { children: title }), raw(ASSET_HEAD), _jsx("style", { children: raw(DESIGN_CSS) })] }), _jsxs("body", { children: [raw(nav), _jsx("header", { class: "report-hero texture-noise", children: _jsxs("div", { class: "report-container", children: [_jsx("p", { class: "report-eyebrow", children: HERO_EYEBROW }), _jsx("h1", { class: "report-display", children: title })] }) }), _jsxs("main", { children: [raw(content), references.length > 0 ? raw(references) : null] }), _jsx("footer", { class: "report-footer", children: _jsxs("div", { class: "report-container report-footer-row", children: [_jsx("span", { class: "report-footer-title", children: title }), _jsx("span", { class: "report-footer-note", children: FOOTER_NOTE })] }) }), _jsx("script", { children: raw(THEME_REGISTRATION) }), _jsx("script", { children: raw(FADE_IN_OBSERVER) }), _jsx("script", { children: raw(CHART_BOOTSTRAP) })] })] })));
+        String(_jsxs("html", { lang: "en", children: [_jsxs("head", { children: [_jsx("meta", { charset: "utf-8" }), _jsx("meta", { name: "viewport", content: "width=device-width, initial-scale=1" }), _jsx("title", { children: title }), raw(ASSET_HEAD), grids ? raw(GRID_ASSET_HEAD) : null, _jsx("style", { children: raw(DESIGN_CSS) })] }), _jsxs("body", { children: [raw(nav), _jsx("header", { class: "report-hero texture-noise", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content", children: [_jsx("p", { class: "report-eyebrow", children: HERO_EYEBROW }), _jsx("h1", { class: "report-display", children: title })] }) }) }), _jsxs("main", { children: [raw(content), references.length > 0 ? raw(references) : null] }), _jsx("footer", { class: "report-footer", children: _jsx("div", { class: "report-container", children: _jsxs("div", { class: "report-content report-footer-row", children: [_jsx("span", { class: "report-footer-title", children: title }), _jsx("span", { class: "report-footer-note", children: FOOTER_NOTE })] }) }) }), dataAssets.map((asset) => (_jsx("script", { src: stagedSource(asset.name) }))), dataAssets.length > 0 ? _jsx("script", { children: raw(TABLE_DATA_DECODER) }) : null, _jsx("script", { children: raw(THEME_REGISTRATION) }), _jsx("script", { children: raw(FADE_IN_OBSERVER) }), grids ? _jsx("script", { children: raw(GRID_BOOTSTRAP) }) : null, _jsx("script", { children: raw(CHART_BOOTSTRAP) }), _jsx("script", { children: raw(SECTION_SPY) })] })] })));
 }

package/dist/report-render/views/prose.d.ts

@@ -4,15 +4,25 @@
  * The runtime escapes every interpolated string, thus hostile prose reaches the page as text. A text
  * block and a claim block split the prose on a blank line, and each part becomes one paragraph. A claim
  * adds one marker for each binding, and the markers number through the shared ledger.
+ *
+ * A text block also carries a typed list, and the list renders as list markup after the paragraphs. Each
+ * item takes the same escape as a paragraph, thus no item reaches the page as markup.
  */
 import type { ClaimBlock, SectionBlock, TextBlock } from "../../contracts/report-blocks.js";
 import type { ReferenceLedger } from "../references.js";
-/** Render a text block as escaped paragraphs. */
+/**
+ * Render a text block as escaped paragraphs, and then its list.
+ *
+ * The lead sentences introduce the enumeration, thus the list comes after them. An empty prose gives no
+ * paragraph, and a block with a list alone renders the list alone. A block with no list renders the
+ * paragraphs alone, exactly as it did before the field existed.
+ */
 export declare function renderText(block: TextBlock): string;
 /**
  * Render a claim block as escaped paragraphs plus evidence markers. The markers attach to the last
  * paragraph, thus they sit at the end of the claim text. The ledger marks each binding, thus a shared
- * reference keeps one number across the page.
+ * reference keeps one number across the page. An artifact binding and a citation binding read the same
+ * bracket, because one ladder counts them both.
  */
 export declare function renderClaim(block: ClaimBlock, ledger: ReferenceLedger): string;
 /**

package/dist/report-render/views/prose.js

@@ -5,11 +5,18 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-
  * The runtime escapes every interpolated string, thus hostile prose reaches the page as text. A text
  * block and a claim block split the prose on a blank line, and each part becomes one paragraph. A claim
  * adds one marker for each binding, and the markers number through the shared ledger.
+ *
+ * A text block also carries a typed list, and the list renders as list markup after the paragraphs. Each
+ * item takes the same escape as a paragraph, thus no item reaches the page as markup.
  */
 import { raw } from "hono/html";
 import { Marker } from "./references-view.js";
-/** The paragraph class of a text block and a claim block. The measure caps the line inside the wide band. */
+/** The paragraph class of a text block and a claim block. The paragraph fills the content column. */
 const PARAGRAPH_CLASS = "report-prose";
+/** The class of a rendered list. The list fills the content column, the same as a paragraph. */
+const LIST_CLASS = "report-list";
+/** The site that the navigation brand links to. It is the one reference of the page that leaves the page. */
+const BRAND_HREF = "https://inflexa.ai/";
 /**
  * Split prose into paragraphs on a blank line. A run of blank lines makes one split. An empty part drops
  * out, thus a leading or a trailing blank line adds no empty paragraph.
@@ -25,19 +32,34 @@ function splitParagraphs(prose) {
     }
     return paragraphs;
 }
-/** Render a text block as escaped paragraphs. */
+/**
+ * One typed list as list markup. The flag selects the element: an ordered list numbers its items, and an
+ * unordered one bullets them. Each item is one inline line, thus no item holds a list of its own.
+ */
+function TextListView({ list }) {
+    const items = list.items.map((item) => _jsx("li", { class: "report-list-item", children: item }));
+    return list.ordered ? _jsx("ol", { class: LIST_CLASS, children: items }) : _jsx("ul", { class: LIST_CLASS, children: items });
+}
+/**
+ * Render a text block as escaped paragraphs, and then its list.
+ *
+ * The lead sentences introduce the enumeration, thus the list comes after them. An empty prose gives no
+ * paragraph, and a block with a list alone renders the list alone. A block with no list renders the
+ * paragraphs alone, exactly as it did before the field existed.
+ */
 export function renderText(block) {
     const paragraphs = splitParagraphs(block.content.prose);
-    return String(_jsx(_Fragment, { children: paragraphs.map((paragraph) => (_jsx("p", { class: PARAGRAPH_CLASS, children: paragraph }))) }));
+    const list = block.content.list;
+    return String(_jsxs(_Fragment, { children: [paragraphs.map((paragraph) => (_jsx("p", { class: PARAGRAPH_CLASS, children: paragraph }))), list !== undefined ? _jsx(TextListView, { list: list }) : null] }));
 }
 /**
  * Render a claim block as escaped paragraphs plus evidence markers. The markers attach to the last
  * paragraph, thus they sit at the end of the claim text. The ledger marks each binding, thus a shared
- * reference keeps one number across the page.
+ * reference keeps one number across the page. An artifact binding and a citation binding read the same
+ * bracket, because one ladder counts them both.
  */
 export function renderClaim(block, ledger) {
-    const markerNumbers = block.bindings.map((reference) => ledger.mark(reference));
-    const markers = markerNumbers.map((n) => _jsx(Marker, { n: n }));
+    const markers = block.bindings.map((reference) => _jsx(Marker, { n: ledger.mark(reference) }));
     const paragraphs = splitParagraphs(block.content.prose);
     if (paragraphs.length === 0) {
         return String(_jsx("p", { class: PARAGRAPH_CLASS, children: markers }));
@@ -65,5 +87,5 @@ export function renderSection(section, depth, childrenHtml) {
  * The `report-sidebar` id is the hook of the layout shift on a large viewport.
  */
 export function renderNav(topSections) {
-    return String(_jsxs("aside", { id: "report-sidebar", class: "report-nav", "aria-label": "Report navigation", children: [_jsx("div", { class: "report-nav-brand", children: _jsx("span", { class: "report-nav-brand-name", children: "inflexa" }) }), _jsx("nav", { class: "report-nav-list", "aria-label": "Report sections", children: topSections.map((section, index) => (_jsxs("a", { href: `#${section.id}`, class: "report-nav-link", children: [_jsx("span", { class: "report-nav-index", children: index + 1 }), _jsx("span", { class: "report-nav-label", children: section.title })] }))) })] }));
+    return String(_jsxs("aside", { id: "report-sidebar", class: "report-nav", "aria-label": "Report navigation", children: [_jsx("div", { class: "report-nav-brand", children: _jsx("a", { class: "report-nav-brand-name", href: BRAND_HREF, children: "inflexa" }) }), _jsx("nav", { class: "report-nav-list", "aria-label": "Report sections", children: topSections.map((section, index) => (_jsxs("a", { href: `#${section.id}`, class: "report-nav-link", children: [_jsx("span", { class: "report-nav-index", children: index + 1 }), _jsx("span", { class: "report-nav-label", children: section.title })] }))) })] }));
 }

package/dist/report-render/views/references-view.d.ts

@@ -1,20 +1,34 @@
 /**
- * The reference markup: the evidence marker and the ordered reference list.
+ * The reference markup: the one evidence marker, and the one appendix list under it.
  *
  * The runtime escapes each child and each attribute value, thus a hostile path, a hostile id, or a
- * hostile operation reaches the page as text. The list keeps the first-appearance order of the ledger,
+ * hostile operation reaches the page as text. The list keeps the first-appearance order of the ladder,
  * thus the ordinal of each item matches its marker.
+ *
+ * One list holds both reference kinds, flat and in number order. Each entry leads with a kind tag, thus an
+ * artifact entry and a literature entry stay apart on sight without a heading between them. A page with an
+ * empty ledger renders no list at all.
  */
-import type { ReferenceLedger } from "../references.js";
+import { type CitationRecords } from "../../report-model/reference-resolver.js";
+import { type DerivationChains, type ReferenceLedger } from "../references.js";
 /**
- * One evidence marker as a superscript that links to the list entry. The number comes from the ledger as
- * an integer.
+ * One evidence marker as a bracket number that links to its appendix entry.
+ *
+ * A bracket reads as a reference inside prose, and it stays a span beside the words. One notation serves
+ * every kind, thus one list answers every marker.
  */
 export declare function Marker({ n }: {
     n: number;
 }): import("hono/jsx/jsx-dev-runtime").JSX.Element;
 /**
- * The ordered reference list for the end of the page. An empty ledger gives an empty string, thus the
- * page shows no empty list.
+ * The one appendix list: one entry for each distinct reference of the page, in the order of the ladder.
+ *
+ * The list is an appendix: a reader consults one entry from a marker, thus the design keeps it quieter than
+ * the body. The ordered list numbers its own items, thus the shown number of an entry matches the marker
+ * that sent the reader to it. An empty ledger gives an empty string, thus the page shows no empty list.
+ *
+ * The records carry the bibliography of each cited key, and a ledger with no citation reads none of them.
+ * The chains are the derivations of the session, keyed by the output path. An entry whose path the chains
+ * hold carries the chain line, and each other entry carries none.
  */
-export declare function renderReferenceList(ledger: ReferenceLedger): string;
+export declare function renderReferences(ledger: ReferenceLedger, records?: CitationRecords, chains?: DerivationChains): string;

package/dist/report-render/views/references-view.js

@@ -1,10 +1,14 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "hono/jsx/jsx-runtime";
+import { citationRecordOf } from "../../report-model/reference-resolver.js";
+import { citationKeyOf } from "../references.js";
 /**
- * One evidence marker as a superscript that links to the list entry. The number comes from the ledger as
- * an integer.
+ * One evidence marker as a bracket number that links to its appendix entry.
+ *
+ * A bracket reads as a reference inside prose, and it stays a span beside the words. One notation serves
+ * every kind, thus one list answers every marker.
  */
 export function Marker({ n }) {
-    return (_jsx("sup", { class: "report-marker", children: _jsx("a", { href: `#ref-${n}`, children: n }) }));
+    return (_jsx("span", { class: "report-marker", children: _jsx("a", { href: `#ref-${n}`, children: `[${n}]` }) }));
 }
 /** The kind label of one reference entry. */
 function RefKind({ children }) {
@@ -18,6 +22,56 @@ function PathCode({ children }) {
 function Detail({ children }) {
     return _jsx("span", { class: "report-ref-detail", children: children });
 }
+/** The head of a content hash in a monospace span. */
+function HashCode({ children }) {
+    return _jsx("code", { class: "report-ref-hash", children: children });
+}
+/**
+ * The count of hash characters that a chain line shows.
+ *
+ * A content hash is 64 hex characters, and a line that carries three whole ones reads as noise. The head
+ * identifies the bytes, and it matches the count that a staged file name carries. Thus a reader compares the
+ * two by sight.
+ */
+const CHAIN_HASH_CHARS = 12;
+/** The head of one content hash: the hex after the algorithm name, cut to the shown length. */
+function hashHead(hash) {
+    return hash.slice(hash.lastIndexOf(":") + 1).slice(0, CHAIN_HASH_CHARS);
+}
+/**
+ * The head of the script hash, as a link to the staged script where the caller staged one.
+ *
+ * The hash head stays the text of the link. Thus the reader reads the same head as before, and the click
+ * opens the script itself. A chain with no staged script shows the head alone.
+ */
+function ScriptLink({ chain }) {
+    const head = _jsx(HashCode, { children: hashHead(chain.scriptHash) });
+    return chain.scriptSource === undefined ? (head) : (_jsx("a", { class: "report-ref-link", href: chain.scriptSource, children: head }));
+}
+/**
+ * The chain of one derived path: each source with the head of its hash, then the head of the script hash,
+ * then the derived file.
+ *
+ * The line rides under the entry of the path, thus the entry itself keeps the form of a pinned artifact and
+ * the chain adds one quiet line under it. A reader mounts the same sources, runs the same script, and gets
+ * the same bytes.
+ *
+ * The script and the derived file are relative links, thus the whole chain walks with no network and no
+ * host. Each hash head stays beside its link, because the head is what a reader compares against the name of
+ * a staged file.
+ */
+function ChainLine({ chain }) {
+    return (_jsxs("div", { class: "report-ref-chain", children: [_jsx(RefKind, { children: "Derived from" }), " ", chain.sources.map((source, index) => (_jsxs(_Fragment, { children: [index > 0 ? " and " : "", _jsx(PathCode, { children: source.path }), " ", _jsx(HashCode, { children: hashHead(source.hash) })] }))), " ", _jsx(Detail, { children: "by script" }), " ", _jsx(ScriptLink, { chain: chain }), chain.outputSource !== undefined ? (_jsxs(_Fragment, { children: [" ", _jsx(Detail, { children: "into" }), " ", _jsx("a", { class: "report-ref-link", href: chain.outputSource, children: _jsx(PathCode, { children: chain.outputSource }) })] })) : null] }));
+}
+/**
+ * The one path that an artifact reference names, or `undefined` for a kind that names no single file.
+ *
+ * A derivation reference computes over two inputs, thus it names no output file of its own and no chain
+ * belongs to it.
+ */
+function pathOf(reference) {
+    return reference.kind === "derivation" ? undefined : reference.path;
+}
 /**
  * Describe a locator as plain text: the column and the one row selector. The refine of the schema admits
  * exactly one of `row` or `rowFilter`, thus the two branches cover a valid locator.
@@ -33,11 +87,11 @@ function describeLocator(locator) {
     return `column ${locator.column}`;
 }
 /**
- * The inner markup of one list entry. An artifact entry names its path, and it adds the locator when the
- * reference pins one cell. A citation entry names its identifier space and its id. A derivation entry
- * names its operation and its two inputs, each by path and locator.
+ * The inner markup of one artifact entry. An artifact entry names its path, and it adds the locator when
+ * the reference pins one cell. A derivation entry names its operation and its two inputs, each by path and
+ * locator.
  */
-function ReferenceEntry({ reference }) {
+function ReferenceBody({ reference }) {
     switch (reference.kind) {
         case "artifact-value":
             return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact value" }), " ", _jsx(PathCode, { children: reference.path }), " ", _jsx(Detail, { children: describeLocator(reference.locator) })] }));
@@ -45,20 +99,54 @@ function ReferenceEntry({ reference }) {
             return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact table" }), " ", _jsx(PathCode, { children: reference.path })] }));
         case "artifact-file":
             return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Artifact file" }), " ", _jsx(PathCode, { children: reference.path })] }));
-        case "citation":
-            return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Citation" }), " ", _jsx(Detail, { children: `${reference.idKind}:${reference.id}` })] }));
         case "derivation":
             return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: `Derivation (${reference.op})` }), " ", reference.inputs.map((input, index) => (_jsxs(_Fragment, { children: [index > 0 ? " and " : "", _jsx(PathCode, { children: input.path }), " ", _jsx(Detail, { children: describeLocator(input.locator) })] })))] }));
     }
 }
 /**
- * The ordered reference list for the end of the page. An empty ledger gives an empty string, thus the
- * page shows no empty list.
+ * One artifact entry: the body of its kind, and the chain of its path where the records hold one.
+ *
+ * A path that no record names renders the body alone, thus a page over pinned artifacts alone reads exactly
+ * as it did before the chains existed.
+ */
+function ArtifactEntry({ reference, chains }) {
+    const path = pathOf(reference);
+    const chain = path === undefined ? undefined : chains?.get(path);
+    return (_jsxs(_Fragment, { children: [_jsx(ReferenceBody, { reference: reference }), chain !== undefined ? _jsx(ChainLine, { chain: chain }) : null] }));
+}
+/**
+ * The inner markup of one literature entry: the kind tag, the short citation of the pinned record, the key,
+ * and the description of the record on a line of its own. A key that the record map does not hold shows the
+ * key alone, because absence is a normal condition.
+ *
+ * The description sits in the appendix and never on the card. The card sits in the body of the report,
+ * where a paragraph about the paper competes with the prose around it.
+ */
+function CitationEntry({ reference, records }) {
+    const key = citationKeyOf(reference);
+    const record = citationRecordOf(records, key);
+    const description = record?.description;
+    return (_jsxs(_Fragment, { children: [_jsx(RefKind, { children: "Citation" }), " ", record !== undefined ? (_jsxs(_Fragment, { children: [_jsx("span", { class: "report-cite-source", children: record.citation }), " "] })) : null, _jsx(Detail, { children: key }), description !== undefined ? _jsx("div", { class: "report-cite-description", children: description }) : null] }));
+}
+/** One appendix entry. The kind of the reference selects the shape, and the two shapes share the ladder. */
+function ReferenceEntry({ reference, records, chains }) {
+    return reference.kind === "citation" ? _jsx(CitationEntry, { reference: reference, records: records }) : _jsx(ArtifactEntry, { reference: reference, chains: chains });
+}
+/**
+ * The one appendix list: one entry for each distinct reference of the page, in the order of the ladder.
+ *
+ * The list is an appendix: a reader consults one entry from a marker, thus the design keeps it quieter than
+ * the body. The ordered list numbers its own items, thus the shown number of an entry matches the marker
+ * that sent the reader to it. An empty ledger gives an empty string, thus the page shows no empty list.
+ *
+ * The records carry the bibliography of each cited key, and a ledger with no citation reads none of them.
+ * The chains are the derivations of the session, keyed by the output path. An entry whose path the chains
+ * hold carries the chain line, and each other entry carries none.
  */
-export function renderReferenceList(ledger) {
+export function renderReferences(ledger, records, chains) {
     const entries = ledger.entries();
     if (entries.length === 0) {
         return "";
     }
-    return String(_jsx("ol", { class: "report-references", children: entries.map((reference, index) => (_jsx("li", { id: `ref-${index + 1}`, class: "report-ref-item", children: _jsx(ReferenceEntry, { reference: reference }) }))) }));
+    return String(_jsx("ol", { class: "report-references", children: entries.map((reference, index) => (_jsx("li", { id: `ref-${index + 1}`, class: "report-ref-item", children: _jsx(ReferenceEntry, { reference: reference, records: records, chains: chains }) }))) }));
 }