@inflexa-ai/harness 0.20.0 → 0.21.1

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

@@ -2,31 +2,85 @@
  * The reference ledger state.
  *
  * A claim binds to evidence, and a citation block points at an external source. The ledger collects each
- * reference in first-appearance order, and it gives one marker number to each distinct reference. A claim
- * marker and a citation marker read from the same ledger, thus one reference that two blocks share gets
- * one number and one list entry.
+ * reference in first-appearance order, and it gives one bracket number to each distinct reference. Every
+ * marker of the page reads from this one ladder, thus a reference that two blocks share gets one number and
+ * one appendix entry.
  *
- * Identity is the canonical serialization of the reference. `serializeReference` sorts the keys at every
- * depth, thus two references match only when every field matches. The key order of the source object does
- * not change the identity.
+ * One ladder holds both kinds. A reader of a report follows one notation, and the appendix lists flat in
+ * number order. Two ladders give one page two notations, and a reader must then learn which marker points
+ * at which list.
+ *
+ * The identity of a reference depends on its kind. An artifact identity is the canonical serialization of
+ * the reference: `serializeReference` sorts the keys at every depth, thus two references match only when
+ * every field matches, and two locators of one file stay apart. A citation identity is the citation key
+ * alone, because the key names the paper and the display text is authored beside it.
+ *
+ * The two identity forms cannot collide. A serialization is a JSON object, and a citation key is the
+ * prefixed `idKind:id` text. Thus one map holds both.
+ */
+import { type CitationReference, type Reference } from "../contracts/report-reference.js";
+/** The citation key of one citation reference, in the prefixed `idKind:id` form. */
+export declare function citationKeyOf(reference: CitationReference): string;
+/** One source of a derivation: the pinned path that the script read, and the content hash of those bytes. */
+export interface DerivationChainSource {
+    readonly path: string;
+    readonly hash: string;
+}
+/**
+ * The chain of one derived path: the sources that the script read, and the hash of the script itself.
+ *
+ * The renderer declares the shape that the appendix reads, and never the durable record that carries it.
+ * Thus a caller passes the stored records straight through, and the render stays a pure function of plain
+ * data.
+ *
+ * The two sources are the links of the chain, and both are optional. `scriptSource` is the relative source
+ * of the staged script asset, and `outputSource` is the relative source of the derived file. The caller
+ * stages the script and it knows where the derived file sits, thus the caller states both and the renderer
+ * reads no disk. A chain that carries neither renders its hashes alone.
+ */
+export interface DerivationChain {
+    readonly outputPath: string;
+    readonly sources: readonly DerivationChainSource[];
+    readonly scriptHash: string;
+    readonly scriptSource?: string;
+    readonly outputSource?: string;
+}
+/** The chain of each derived path of one render, keyed by the output path that the bindings name. */
+export type DerivationChains = ReadonlyMap<string, DerivationChain>;
+/**
+ * Key each chain by its output path.
+ *
+ * The appendix reads one chain for one path, thus the map is the read form of the list. A repeated output
+ * path keeps the first record, because the durable list refuses a repeated path and a second one carries no
+ * new meaning.
+ */
+export declare function derivationChains(records: readonly DerivationChain[] | undefined): DerivationChains;
+/**
+ * Each reference kind that names data, which is every kind except a citation.
+ *
+ * A derivation joins this set, because it computes over pinned artifacts and it names no paper.
  */
-import { type Reference } from "../contracts/report-reference.js";
+export type ArtifactReference = Exclude<Reference, CitationReference>;
 /**
  * The mutable ledger of references.
  *
- * The page walk makes one ledger, and it threads the ledger through each claim and each citation. The
- * order of the entries is the order of the first mark, thus the marker numbers count up by first
- * appearance.
+ * The page walk makes one ledger, and it threads the ledger through each claim, each card, and each
+ * citation. The order of the entries is the order of the first mark, thus the marker numbers count up by
+ * first appearance across the whole page.
  */
 export declare class ReferenceLedger {
-    private readonly order;
-    private readonly markers;
+    private readonly references;
+    private readonly marks;
     /**
-     * Give the marker number of a reference. A new reference gets the next number, and it joins the
-     * order. A reference that matches an earlier one gives the earlier number, thus the list holds it one
-     * time.
+     * Give the marker number of a reference. A new reference gets the next number of the ladder, and it
+     * joins the order of the ladder. A reference that matches an earlier one gives the earlier number, thus
+     * the appendix holds it one time.
+     *
+     * A citation matches on its key alone. The `raw` text and the display fields of a citation are the
+     * words of the author, and two blocks over one paper carry different words. The key names the paper,
+     * thus one paper takes one number and the appendix holds it one time.
      */
     mark(reference: Reference): number;
-    /** The references in first-appearance order. The marker of an entry is its position plus one. */
+    /** Every reference in first-appearance order. The marker of an entry is its position plus one. */
     entries(): readonly Reference[];
 }

package/dist/report-render/references.js

@@ -2,43 +2,75 @@
  * The reference ledger state.
  *
  * A claim binds to evidence, and a citation block points at an external source. The ledger collects each
- * reference in first-appearance order, and it gives one marker number to each distinct reference. A claim
- * marker and a citation marker read from the same ledger, thus one reference that two blocks share gets
- * one number and one list entry.
+ * reference in first-appearance order, and it gives one bracket number to each distinct reference. Every
+ * marker of the page reads from this one ladder, thus a reference that two blocks share gets one number and
+ * one appendix entry.
  *
- * Identity is the canonical serialization of the reference. `serializeReference` sorts the keys at every
- * depth, thus two references match only when every field matches. The key order of the source object does
- * not change the identity.
+ * One ladder holds both kinds. A reader of a report follows one notation, and the appendix lists flat in
+ * number order. Two ladders give one page two notations, and a reader must then learn which marker points
+ * at which list.
+ *
+ * The identity of a reference depends on its kind. An artifact identity is the canonical serialization of
+ * the reference: `serializeReference` sorts the keys at every depth, thus two references match only when
+ * every field matches, and two locators of one file stay apart. A citation identity is the citation key
+ * alone, because the key names the paper and the display text is authored beside it.
+ *
+ * The two identity forms cannot collide. A serialization is a JSON object, and a citation key is the
+ * prefixed `idKind:id` text. Thus one map holds both.
  */
 import { serializeReference } from "../contracts/report-reference.js";
+/** The citation key of one citation reference, in the prefixed `idKind:id` form. */
+export function citationKeyOf(reference) {
+    return `${reference.idKind}:${reference.id}`;
+}
+/**
+ * Key each chain by its output path.
+ *
+ * The appendix reads one chain for one path, thus the map is the read form of the list. A repeated output
+ * path keeps the first record, because the durable list refuses a repeated path and a second one carries no
+ * new meaning.
+ */
+export function derivationChains(records) {
+    const chains = new Map();
+    for (const record of records ?? []) {
+        if (!chains.has(record.outputPath)) {
+            chains.set(record.outputPath, record);
+        }
+    }
+    return chains;
+}
 /**
  * The mutable ledger of references.
  *
- * The page walk makes one ledger, and it threads the ledger through each claim and each citation. The
- * order of the entries is the order of the first mark, thus the marker numbers count up by first
- * appearance.
+ * The page walk makes one ledger, and it threads the ledger through each claim, each card, and each
+ * citation. The order of the entries is the order of the first mark, thus the marker numbers count up by
+ * first appearance across the whole page.
  */
 export class ReferenceLedger {
-    order = [];
-    markers = new Map();
+    references = [];
+    marks = new Map();
     /**
-     * Give the marker number of a reference. A new reference gets the next number, and it joins the
-     * order. A reference that matches an earlier one gives the earlier number, thus the list holds it one
-     * time.
+     * Give the marker number of a reference. A new reference gets the next number of the ladder, and it
+     * joins the order of the ladder. A reference that matches an earlier one gives the earlier number, thus
+     * the appendix holds it one time.
+     *
+     * A citation matches on its key alone. The `raw` text and the display fields of a citation are the
+     * words of the author, and two blocks over one paper carry different words. The key names the paper,
+     * thus one paper takes one number and the appendix holds it one time.
      */
     mark(reference) {
-        const key = serializeReference(reference);
-        const seen = this.markers.get(key);
+        const key = reference.kind === "citation" ? citationKeyOf(reference) : serializeReference(reference);
+        const seen = this.marks.get(key);
         if (seen !== undefined) {
             return seen;
         }
-        const marker = this.order.length + 1;
-        this.markers.set(key, marker);
-        this.order.push(reference);
-        return marker;
+        // `push` gives back the new length of the array, which is the number of the entry that it added.
+        const n = this.references.push(reference);
+        this.marks.set(key, n);
+        return n;
     }
-    /** The references in first-appearance order. The marker of an entry is its position plus one. */
+    /** Every reference in first-appearance order. The marker of an entry is its position plus one. */
     entries() {
-        return this.order;
+        return this.references;
     }
 }

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

@@ -8,18 +8,36 @@
  *
  * One shared `ReferenceLedger` threads through the whole walk. Thus a claim marker and a citation marker
  * count by first appearance across the page, and a reference that two blocks share keeps one number and one
- * list entry.
+ * list entry. The ledger holds one ladder over both reference kinds, thus the page carries one marker
+ * notation and one appendix.
  *
  * The output is a pure function of the two inputs. The renderer reads no clock, no random value, and no
  * locale. Thus the same document and the same values give the same bytes.
  */
 import { type Result } from "neverthrow";
 import type { ReportDocument } from "../contracts/report-blocks.js";
-import type { RenderProblem, RenderValues } from "./types.js";
+import { type CitationRecords } from "../report-model/reference-resolver.js";
+import { type DerivationChain } from "./references.js";
+import type { RenderedPage, RenderProblem, RenderValues } from "./types.js";
 /**
- * Render a report document and its value map to one HTML string.
+ * Render a report document, its value map, and the pinned citation records to one page and its data assets.
  *
  * The walk collects every value problem. When any problem exists, the render returns the problems and no
- * HTML. When no problem exists, the render assembles the page and returns the string.
+ * page. When no problem exists, the render assembles the page and returns it beside the assets that the
+ * page references.
+ *
+ * The records are the bibliography of the pin, and they are optional. A caller that passes none renders
+ * each citation from its key alone, thus a stored pin that holds no record map renders as it did before.
+ *
+ * The derivations are the chains of the session, and they are optional too. An appendix entry whose path a
+ * chain names states its sources and its script. A document that binds no derived path renders
+ * byte-identically with the chains and without them. A chain carries the relative source of its staged
+ * script and of its derived file as data, thus the entry links both and this module stages nothing.
+ *
+ * The renderer writes no file. The data assets ride the result, and the caller stages them beside the page.
+ * Thus the render stays pure, and two renders of one document give byte-identical assets.
+ *
+ * One artifact gives one payload. A table block and a chart block that bind it read that one asset, and a
+ * chart under the inline bound carries its rows in its own option and registers none.
  */
-export declare function renderReportPage(document: ReportDocument, values: RenderValues): Result<string, RenderProblem[]>;
+export declare function renderReportPage(document: ReportDocument, values: RenderValues, records?: CitationRecords, derivations?: readonly DerivationChain[]): Result<RenderedPage, RenderProblem[]>;

package/dist/report-render/render.js

@@ -8,51 +8,87 @@
  *
  * One shared `ReferenceLedger` threads through the whole walk. Thus a claim marker and a citation marker
  * count by first appearance across the page, and a reference that two blocks share keeps one number and one
- * list entry.
+ * list entry. The ledger holds one ladder over both reference kinds, thus the page carries one marker
+ * notation and one appendix.
  *
  * The output is a pure function of the two inputs. The renderer reads no clock, no random value, and no
  * locale. Thus the same document and the same values give the same bytes.
  */
 import { err, ok } from "neverthrow";
+import { serializeReference } from "../contracts/report-reference.js";
+import { citationRecordOf } from "../report-model/reference-resolver.js";
 import { renderChart } from "./views/chart-view.js";
-import { deriveChartOption } from "./chart.js";
+import { deriveChartRender } from "./chart.js";
 import { assemblePage, renderBand, renderReferenceSection } from "./views/page-view.js";
 import { renderClaim, renderNav, renderSection, renderText } from "./views/prose.js";
-import { ReferenceLedger } from "./references.js";
-import { renderCitation, renderFigure, renderMetric, renderMetricGrid, renderTable } from "./views/values.js";
+import { citationKeyOf, derivationChains, ReferenceLedger } from "./references.js";
+import { encodeTablePayload, tableDataAsset } from "./table-data.js";
+import { renderCitation, renderFigure, renderMetric, renderMetricGrid, renderTable, tableColumns, tableDisplay } from "./views/values.js";
 /**
- * Render a report document and its value map to one HTML string.
+ * Render a report document, its value map, and the pinned citation records to one page and its data assets.
  *
  * The walk collects every value problem. When any problem exists, the render returns the problems and no
- * HTML. When no problem exists, the render assembles the page and returns the string.
+ * page. When no problem exists, the render assembles the page and returns it beside the assets that the
+ * page references.
+ *
+ * The records are the bibliography of the pin, and they are optional. A caller that passes none renders
+ * each citation from its key alone, thus a stored pin that holds no record map renders as it did before.
+ *
+ * The derivations are the chains of the session, and they are optional too. An appendix entry whose path a
+ * chain names states its sources and its script. A document that binds no derived path renders
+ * byte-identically with the chains and without them. A chain carries the relative source of its staged
+ * script and of its derived file as data, thus the entry links both and this module stages nothing.
+ *
+ * The renderer writes no file. The data assets ride the result, and the caller stages them beside the page.
+ * Thus the render stays pure, and two renders of one document give byte-identical assets.
+ *
+ * One artifact gives one payload. A table block and a chart block that bind it read that one asset, and a
+ * chart under the inline bound carries its rows in its own option and registers none.
  */
-export function renderReportPage(document, values) {
+export function renderReportPage(document, values, records, derivations) {
     const problems = [];
     const ledger = new ReferenceLedger();
+    const data = { payloads: new Map(), mounts: 0 };
     const content = [];
     for (const [index, section] of document.sections.entries()) {
-        content.push(renderBand(index, renderBlock(section, values, ledger, 0, problems)));
+        content.push(renderBand(index, renderBlock(section, values, ledger, records, data, 0, problems)));
     }
     if (problems.length > 0) {
         return err(problems);
     }
+    const dataAssets = [...data.payloads.values()].map((entry) => tableDataAsset(entry.ids, entry.payload));
     const nav = renderNav(document.sections);
-    const references = renderReferenceSection(ledger, document.sections.length);
-    return ok(assemblePage(document.title, nav, content.join(""), references));
+    const references = renderReferenceSection(ledger, document.sections.length, records, derivationChains(derivations));
+    return ok({ html: assemblePage(document.title, nav, content.join(""), references, dataAssets, data.mounts > 0), dataAssets });
+}
+/**
+ * Register the payload of one bound artifact, and name this block as a reader of it.
+ *
+ * The first block of an artifact encodes the payload. A later block over the same binding adds its id and
+ * encodes nothing, thus the page carries one copy of the rows.
+ */
+function registerPayload(data, binding, blockId, encode) {
+    const key = serializeReference(binding);
+    const registered = data.payloads.get(key);
+    if (registered !== undefined) {
+        registered.ids.push(blockId);
+        return;
+    }
+    data.payloads.set(key, { ids: [blockId], payload: encode() });
 }
 /**
  * Render one block to its HTML, and collect a value problem into `problems`. A block whose value is missing
  * or of the wrong shape adds one problem and renders nothing. The empty result drops out, because the whole
  * render fails when any problem exists.
  */
-function renderBlock(block, values, ledger, depth, problems) {
+function renderBlock(block, values, ledger, records, data, depth, problems) {
     switch (block.kind) {
         case "text":
             return renderText(block);
         case "claim":
             return renderClaim(block, ledger);
         case "citation":
-            return renderCitation(block, ledger);
+            return renderCitation(block, ledger, citationRecordOf(records, citationKeyOf(block.binding)));
         case "metric": {
             const entry = values[block.id];
             if (entry === undefined) {
@@ -63,7 +99,7 @@ function renderBlock(block, values, ledger, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "scalar"));
                 return "";
             }
-            return renderMetric(block, entry);
+            return renderMetric(block, ledger, entry);
         }
         case "table": {
             const entry = values[block.id];
@@ -75,7 +111,13 @@ function renderBlock(block, values, ledger, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "table"));
                 return "";
             }
-            return renderTable(block, entry);
+            // The rows of the block ride a data asset, and the card holds one empty mount. The payload
+            // carries the column order, thus a cell of an encoded row names its column by position and the
+            // display entry of that column sits at the same index.
+            const columns = tableColumns(entry);
+            data.mounts += 1;
+            registerPayload(data, block.binding, block.id, () => payloadOf(block.binding, entry, columns));
+            return renderTable(block, ledger, entry.rows.length, entry.total);
         }
         case "figure": {
             const entry = values[block.id];
@@ -87,7 +129,7 @@ function renderBlock(block, values, ledger, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "figure"));
                 return "";
             }
-            return renderFigure(block, entry);
+            return renderFigure(block, ledger, entry);
         }
         case "chart": {
             const entry = values[block.id];
@@ -99,31 +141,48 @@ function renderBlock(block, values, ledger, depth, problems) {
                 problems.push(wrongShape(block.id, entry.type, "table"));
                 return "";
             }
-            const option = deriveChartOption(block, entry.rows, entry.columns);
-            if (option.isErr()) {
-                problems.push(option.error);
+            // A chart whose inline option would carry every row reads the payload of its artifact instead.
+            // The payload key is the block id, thus a chart and a table over one artifact read one payload
+            // under two ids. One binding resolves one row set, thus the column places and the row places of
+            // the descriptors address the registered payload whichever block encoded it.
+            const columns = tableColumns(entry);
+            const derived = deriveChartRender(block, entry.rows, entry.columns, { key: block.id, columns });
+            if (derived.isErr()) {
+                problems.push(derived.error);
                 return "";
             }
-            return renderChart(block, option.value);
+            if (derived.value.readsPayload) {
+                registerPayload(data, block.binding, block.id, () => payloadOf(block.binding, entry, columns));
+            }
+            return renderChart(block, ledger, derived.value.option);
         }
         case "section":
-            return renderSection(block, depth, renderChildren(block.blocks, values, ledger, depth + 1, problems));
+            return renderSection(block, depth, renderChildren(block.blocks, values, ledger, records, data, depth + 1, problems));
     }
 }
+/**
+ * The payload of one bound artifact: the encoded rows, the display of each column, and the pre-bound total.
+ *
+ * A table and a chart bind the same whole-table reference, thus one function serves both and the two read
+ * one shape. The binding gives the declared labels and meanings, and the value gives the rows.
+ */
+function payloadOf(binding, entry, columns) {
+    return encodeTablePayload(columns, entry.rows, tableDisplay(binding, entry, columns), entry.total);
+}
 /**
  * Render the children of one section, and group a consecutive run of metric siblings into one grid.
  *
  * A run of two or more metric blocks reads as one row of statistics, thus the grid holds the whole run. A
  * lone metric stays one card, and no grid wraps it. A block of a different kind ends the run.
  */
-function renderChildren(blocks, values, ledger, depth, problems) {
+function renderChildren(blocks, values, ledger, records, data, depth, problems) {
     const parts = [];
     let index = 0;
     while (index < blocks.length) {
         const run = metricRunLength(blocks, index);
         const rendered = [];
         for (let offset = 0; offset < Math.max(run, 1); offset += 1) {
-            rendered.push(renderBlock(blocks[index + offset], values, ledger, depth, problems));
+            rendered.push(renderBlock(blocks[index + offset], values, ledger, records, data, depth, problems));
         }
         parts.push(run > 1 ? renderMetricGrid(rendered.join("")) : rendered.join(""));
         index += Math.max(run, 1);

package/dist/report-render/table-data.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The data-script payload of one table block.
+ *
+ * A table of many thousands of rows stamped into the markup makes a page of many megabytes. A `fetch` is
+ * refused on a `file://` page, thus a data file cannot load the way an image does. A classic script asset
+ * loads on any page, and the payload registers itself under one global map when the browser runs it.
+ *
+ * The encode is columnar. The rows are arrays in column order, thus no row repeats the column names. A
+ * string that occurs more than one time in a column moves into the dictionary of that column, and each
+ * cell that holds it becomes its index. A category column of one thousand rows and four values then costs
+ * four strings and one thousand small integers.
+ *
+ * The payload also carries the display of each column: the header label, the number kind, and the bound of
+ * a stored zero. The server resolves the three, and the page formats each cell under them. It carries the
+ * pre-bound row total of the artifact beside them, thus the footer states the shown count against it.
+ *
+ * The module is pure, and it reads no file. The renderer derives a payload, and the caller writes it.
+ */
+import type { NumberKind } from "./number-format.js";
+/**
+ * The global map that each payload registers under, keyed by the block id.
+ *
+ * The page script reads the same name, thus the payload and the reader cannot disagree over a rename.
+ */
+export declare const TABLE_DATA_GLOBAL = "__REPORT_TABLES";
+/** One cell of an encoded row: a raw value, a dictionary index, or `null` for a cell that the row lacks. */
+export type EncodedCell = string | number | null;
+/** The filter that a column takes on the page: the number filter of a magnitude, or the text filter of a name. */
+export type ColumnFilter = "number" | "text";
+/**
+ * How one column shows on the page: the header label, the number kind of the column, the filter of the
+ * column, and the bound of a stored zero where the column holds one.
+ *
+ * The server resolves each of the four, and the page reads them. Thus the declaration, the token guess, and
+ * the read of a whole column stay on the server, and the page formats and filters alone.
+ */
+export interface ColumnDisplay {
+    label: string;
+    kind: NumberKind;
+    filter: ColumnFilter;
+    bound?: number;
+}
+/**
+ * One encoded table.
+ *
+ * `columns` is the column order, and each row of `rows` holds one cell for each column in that order.
+ * `dict` holds the repeated values of a column, keyed by the column name. A cell of such a column is a
+ * number when it names an entry of that list, and the value itself at every other time.
+ *
+ * `display` holds one entry for each column, in the same order. A list and not a map, thus a column named
+ * `__proto__` needs no guard on the page and the entry of a column sits at the index of its name.
+ *
+ * `total` is the row count of the artifact before a row bound cut it. The page states the shown count
+ * against it, thus a reader of a cut table never reads the cut as the whole artifact.
+ */
+export interface TablePayload {
+    columns: string[];
+    rows: EncodedCell[][];
+    dict: Record<string, string[]>;
+    display: ColumnDisplay[];
+    total: number;
+}
+/** One data asset that the caller writes beside the page: the staged file name, and the source text of it. */
+export interface DataAsset {
+    name: string;
+    bytes: string;
+}
+/**
+ * Encode a resolved table into its payload.
+ *
+ * The caller gives the column order, and the header of the card reads that same order. Thus the position
+ * of a cell in a row names its column.
+ *
+ * A cell that a row does not hold rides as `null`. A table tolerates a ragged row, thus the payload states
+ * the absence in place and never shifts the rest of the row.
+ *
+ * `display` arrives in the column order, thus the entry of a column sits at the index of its name.
+ *
+ * `total` is the row count of the artifact before a row bound cut it. A caller that resolved no bound knows
+ * no larger count, thus it gives none and the row count answers.
+ */
+export declare function encodeTablePayload(columns: readonly string[], rows: ReadonlyArray<Record<string, string | number>>, display: readonly ColumnDisplay[], total?: number): TablePayload;
+/**
+ * The data asset of one bound artifact: the content-addressed file name, and the source text.
+ *
+ * The name carries the hash of the bytes, in the content-address style of a staged figure. Thus two
+ * previews of unchanged data give one name, a changed table gives a new name, and the sweep of the stage
+ * removes the name that nothing references any more.
+ *
+ * The block ids are the readers of the payload, in document order.
+ */
+export declare function tableDataAsset(blockIds: readonly string[], payload: TablePayload): DataAsset;

package/dist/report-render/table-data.js

@@ -0,0 +1,129 @@
+/**
+ * The data-script payload of one table block.
+ *
+ * A table of many thousands of rows stamped into the markup makes a page of many megabytes. A `fetch` is
+ * refused on a `file://` page, thus a data file cannot load the way an image does. A classic script asset
+ * loads on any page, and the payload registers itself under one global map when the browser runs it.
+ *
+ * The encode is columnar. The rows are arrays in column order, thus no row repeats the column names. A
+ * string that occurs more than one time in a column moves into the dictionary of that column, and each
+ * cell that holds it becomes its index. A category column of one thousand rows and four values then costs
+ * four strings and one thousand small integers.
+ *
+ * The payload also carries the display of each column: the header label, the number kind, and the bound of
+ * a stored zero. The server resolves the three, and the page formats each cell under them. It carries the
+ * pre-bound row total of the artifact beside them, thus the footer states the shown count against it.
+ *
+ * The module is pure, and it reads no file. The renderer derives a payload, and the caller writes it.
+ */
+import { createHash } from "node:crypto";
+import { scriptJson } from "./script-json.js";
+/**
+ * The global map that each payload registers under, keyed by the block id.
+ *
+ * The page script reads the same name, thus the payload and the reader cannot disagree over a rename.
+ */
+export const TABLE_DATA_GLOBAL = "__REPORT_TABLES";
+/** The count of hash characters in an asset name. It matches the sidecar of an artifact, thus one form reads across the directory. */
+const HASH_CHARS = 12;
+/**
+ * The dictionary of one column, or `undefined` when the column takes none.
+ *
+ * A column takes a dictionary when every cell of it is a string. The condition keeps the decode
+ * unambiguous: a number in such a column can only be an index, and a string can only be a value. A column
+ * that holds one number rides raw, thus no reader must tell an index from a measurement.
+ *
+ * The dictionary holds each string that occurs more than one time, in first-appearance order. A string
+ * that occurs one time saves nothing as an entry, thus it stays in its row. The order is a function of the
+ * rows alone, thus one table gives one dictionary and two encodes of it match.
+ */
+function columnDictionary(rows, column) {
+    const counts = new Map();
+    for (const row of rows) {
+        const cell = row[column];
+        if (typeof cell !== "string") {
+            return undefined;
+        }
+        counts.set(cell, (counts.get(cell) ?? 0) + 1);
+    }
+    const repeated = [];
+    for (const [value, count] of counts) {
+        if (count > 1) {
+            repeated.push(value);
+        }
+    }
+    return repeated.length > 0 ? repeated : undefined;
+}
+/**
+ * Encode a resolved table into its payload.
+ *
+ * The caller gives the column order, and the header of the card reads that same order. Thus the position
+ * of a cell in a row names its column.
+ *
+ * A cell that a row does not hold rides as `null`. A table tolerates a ragged row, thus the payload states
+ * the absence in place and never shifts the rest of the row.
+ *
+ * `display` arrives in the column order, thus the entry of a column sits at the index of its name.
+ *
+ * `total` is the row count of the artifact before a row bound cut it. A caller that resolved no bound knows
+ * no larger count, thus it gives none and the row count answers.
+ */
+export function encodeTablePayload(columns, rows, display, total) {
+    const dict = {};
+    const indexes = new Map();
+    for (const column of columns) {
+        const values = columnDictionary(rows, column);
+        if (values === undefined) {
+            continue;
+        }
+        dict[column] = values;
+        indexes.set(column, new Map(values.map((value, index) => [value, index])));
+    }
+    const encodedRows = rows.map((row) => columns.map((column) => {
+        const cell = row[column];
+        if (cell === undefined) {
+            return null;
+        }
+        // A dictionary column holds strings alone, thus a cell of another type never carries an index.
+        const index = typeof cell === "string" ? indexes.get(column)?.get(cell) : undefined;
+        return index === undefined ? cell : index;
+    }));
+    return { columns: [...columns], rows: encodedRows, dict, display: [...display], total: total ?? rows.length };
+}
+/**
+ * The source text of one payload asset.
+ *
+ * The text assigns into the global map under the block id. The map takes the null-prototype form, thus a
+ * block id such as `constructor` stays an ordinary entry. The block id rides as JSON, thus hostile text is
+ * data and never source.
+ *
+ * A table block and a chart block over one artifact read one payload. The first id takes the parsed value,
+ * and each further id takes the same object. Thus the page holds one copy of the rows, and each reader
+ * finds it under its own block id.
+ *
+ * The payload itself rides through `JSON.parse` and never as an object literal. An object literal with a
+ * `__proto__` key sets the prototype of the object instead of an own entry, thus a column of that name
+ * would arrive as a mangled object with no such column. `JSON.parse` defines an own property for every
+ * key, thus each column name reaches the page as a column name.
+ */
+function payloadSource(blockIds, payload) {
+    const registry = `window.${TABLE_DATA_GLOBAL}`;
+    const json = scriptJson(JSON.stringify(payload));
+    const primary = `${registry}[${scriptJson(blockIds[0])}]`;
+    const aliases = blockIds.slice(1).map((id) => `${registry}[${scriptJson(id)}]=${primary};`);
+    return `${registry}=${registry}||Object.create(null);${primary}=JSON.parse(${json});${aliases.join("")}\n`;
+}
+/**
+ * The data asset of one bound artifact: the content-addressed file name, and the source text.
+ *
+ * The name carries the hash of the bytes, in the content-address style of a staged figure. Thus two
+ * previews of unchanged data give one name, a changed table gives a new name, and the sweep of the stage
+ * removes the name that nothing references any more.
+ *
+ * The block ids are the readers of the payload, in document order.
+ */
+export function tableDataAsset(blockIds, payload) {
+    const bytes = payloadSource(blockIds, payload);
+    const hash = createHash("sha256").update(bytes).digest("hex").slice(0, HASH_CHARS);
+    return { name: `t-${hash}.data.js`, bytes };
+}