@jitsusama/agentic-harness.core 0.1.0

package/dist/result/details.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Bounding an answer that already carries its own records.
+ *
+ * Several families hand their structured records to a result's
+ * details, because that is what their renderers draw from. Those
+ * records are exactly what a caller would query, so nothing new
+ * has to be gathered to keep the answer bounded: the view gets
+ * cut, and what it was rendered from gets stored.
+ *
+ * This is deliberately a heuristic over an interface. Retrofitting
+ * every handler in every family to declare its collection would be
+ * a hundred edit sites and a hundred chances to forget one,
+ * whereas the details are already there and already right.
+ *
+ * What the heuristic decides is only what to call the payload, not
+ * whether to keep one. It used to decide both, and a seam whose
+ * shape it did not recognize returned its answer whole at any
+ * length: a family whose rows nest under a listing key had nothing
+ * at the top level that was an array, so the bounding never ran.
+ * The gate said that family was wired, because it was, and being
+ * wired turned out to be a different claim from working.
+ *
+ * The payload is now the whole details object rather than the one
+ * collection inside it. A document read renders its body and
+ * carries its comments alongside; storing only the comments cited
+ * the one part that had not been cut.
+ */
+import type { ResultStore } from "./store.js";
+/** The records a details object carries, when it carries one set. */
+export interface DetailRecords {
+    readonly items: readonly unknown[];
+    /** The key they arrived under, which is their name in the caller's words. */
+    readonly unit: string;
+}
+/**
+ * The one collection in a details object, when there is exactly
+ * one.
+ *
+ * List-shaped answers carry a single collection: messages, files,
+ * events, locations. Single-subject answers carry none: one
+ * channel, one user, one document. Anything with two collections
+ * is ambiguous and left alone, because citing the wrong one points
+ * a caller's query at a shape that is not there, and a query that
+ * silently matches nothing is worse than no handle at all.
+ *
+ * An empty collection is also nothing to cite. There is no detail
+ * behind an answer that found nothing.
+ */
+export declare function recordsIn(details: unknown): DetailRecords | undefined;
+/**
+ * Bound a rendered answer, citing the records behind it.
+ *
+ * The narrowing advice is the caller's to supply, because every
+ * family narrows differently and advice that names a parameter the
+ * tool does not have costs a call to disprove.
+ */
+export declare function boundedByDetails(store: ResultStore, answer: {
+    text: string;
+    details: unknown;
+    narrowing: string;
+}): string;

package/dist/result/details.js

@@ -0,0 +1,121 @@
+/**
+ * Bounding an answer that already carries its own records.
+ *
+ * Several families hand their structured records to a result's
+ * details, because that is what their renderers draw from. Those
+ * records are exactly what a caller would query, so nothing new
+ * has to be gathered to keep the answer bounded: the view gets
+ * cut, and what it was rendered from gets stored.
+ *
+ * This is deliberately a heuristic over an interface. Retrofitting
+ * every handler in every family to declare its collection would be
+ * a hundred edit sites and a hundred chances to forget one,
+ * whereas the details are already there and already right.
+ *
+ * What the heuristic decides is only what to call the payload, not
+ * whether to keep one. It used to decide both, and a seam whose
+ * shape it did not recognize returned its answer whole at any
+ * length: a family whose rows nest under a listing key had nothing
+ * at the top level that was an array, so the bounding never ran.
+ * The gate said that family was wired, because it was, and being
+ * wired turned out to be a different claim from working.
+ *
+ * The payload is now the whole details object rather than the one
+ * collection inside it. A document read renders its body and
+ * carries its comments alongside; storing only the comments cited
+ * the one part that had not been cut.
+ */
+import { cite } from "./cite.js";
+import { count } from "./counts.js";
+import { citeListing, LISTING_BUDGET_BYTES } from "./listing.js";
+import { withinLineBudget } from "./view.js";
+/**
+ * The one collection in a details object, when there is exactly
+ * one.
+ *
+ * List-shaped answers carry a single collection: messages, files,
+ * events, locations. Single-subject answers carry none: one
+ * channel, one user, one document. Anything with two collections
+ * is ambiguous and left alone, because citing the wrong one points
+ * a caller's query at a shape that is not there, and a query that
+ * silently matches nothing is worse than no handle at all.
+ *
+ * An empty collection is also nothing to cite. There is no detail
+ * behind an answer that found nothing.
+ */
+export function recordsIn(details) {
+    if (typeof details !== "object" || details === null)
+        return undefined;
+    const arrays = Object.entries(details).filter(([, value]) => Array.isArray(value));
+    if (arrays.length !== 1)
+        return undefined;
+    const [unit, items] = arrays[0];
+    if (items.length === 0)
+        return undefined;
+    return { items, unit };
+}
+/**
+ * Bound a rendered answer, citing the records behind it.
+ *
+ * The narrowing advice is the caller's to supply, because every
+ * family narrows differently and advice that names a parameter the
+ * tool does not have costs a call to disprove.
+ */
+export function boundedByDetails(store, answer) {
+    const records = recordsIn(answer.details);
+    if (records !== undefined && rendersTheRecords(answer.details)) {
+        return citeListing(store, {
+            view: answer.text,
+            records: records.items,
+            unit: records.unit,
+            narrowing: answer.narrowing,
+        });
+    }
+    return citeWhole(store, answer, records);
+}
+/**
+ * Whether the details are the collection, rather than carrying one
+ * among other things.
+ *
+ * A listing's details are its records and the paging around them.
+ * A document's details are a file, its body and its comments, and
+ * the comments are not what the view rendered. Only the first can
+ * be cited as though the collection were the answer.
+ */
+function rendersTheRecords(details) {
+    if (typeof details !== "object" || details === null)
+        return false;
+    return Object.values(details).every((value) => Array.isArray(value) || typeof value !== "object");
+}
+/**
+ * Bound the view and keep everything behind it.
+ *
+ * Used where the records cannot be picked out with confidence.
+ * Keeping the whole details is the conservative choice: whatever
+ * the view was rendered from is somewhere in there, so the cut is
+ * recoverable even though the query has to start a level higher.
+ * When there is nothing structured at all, the rendering itself is
+ * what would be lost, so the rendering is what is kept.
+ */
+function citeWhole(store, answer, records) {
+    const bounded = withinLineBudget(answer.text, LISTING_BUDGET_BYTES);
+    if (bounded.cut === 0)
+        return bounded.text;
+    const hasDetails = typeof answer.details === "object" &&
+        answer.details !== null &&
+        Object.keys(answer.details).length > 0;
+    return cite(store, {
+        payload: hasDetails ? answer.details : answer.text,
+        view: `${bounded.text}\n\n` +
+            `Cut ${count(bounded.cut)} of ` +
+            `${count(bounded.total)} lines to fit the ` +
+            `${count(LISTING_BUDGET_BYTES)} byte budget. ` +
+            answer.narrowing,
+        shown: bounded.shown,
+        total: bounded.total,
+        unit: "lines",
+        stored: records
+            ? { count: records.items.length, unit: records.unit }
+            : { unit: hasDetails ? "result detail" : "rendered answer" },
+    }).text;
+}

package/dist/result/digest.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Saying what a payload is shaped like, in a few hundred bytes.
+ *
+ * A handle on its own is a locked door: the caller knows the
+ * payload exists but not what to ask it. A digest is the label on
+ * the door, and it has to stay small whether it describes ten
+ * records or ten million, so every dimension that could grow with
+ * the input is bounded independently: depth, keys per object,
+ * elements profiled, and the final byte count.
+ *
+ * What it deliberately does not do is sample. A field's value
+ * profile is either over the whole array or replaced by the
+ * length and a first-element shape, never a partial scan
+ * presented as a total, because a caller who queries on the
+ * strength of a wrong profile has been misled by the thing meant
+ * to orient them.
+ */
+/** Budgets that keep a summary bounded regardless of the input's size. */
+export interface JsonSummaryOptions {
+    maxKeys?: number;
+    maxDepth?: number;
+    maxBytes?: number;
+    maxElements?: number;
+    /** Render the shape across indented lines instead of one compact line. */
+    pretty?: boolean;
+}
+/**
+ * Render a bounded structural summary of a parsed JSON value.
+ *
+ * An object becomes its keys mapped to value profiles, an array of objects
+ * becomes its length plus a per-key value-frequency profile, and a scalar
+ * becomes its type. Recursion stops at `maxDepth`, only `maxKeys` keys are shown
+ * before the rest are counted, arrays past `maxElements` degrade to a sample so
+ * the walk stays bounded, and the whole string is capped at `maxBytes`. With
+ * `pretty` the same shape is laid out across indented lines for a human to read.
+ */
+export declare function summarizeJson(value: unknown, opts?: JsonSummaryOptions): string;

package/dist/result/digest.js

@@ -0,0 +1,227 @@
+/**
+ * Saying what a payload is shaped like, in a few hundred bytes.
+ *
+ * A handle on its own is a locked door: the caller knows the
+ * payload exists but not what to ask it. A digest is the label on
+ * the door, and it has to stay small whether it describes ten
+ * records or ten million, so every dimension that could grow with
+ * the input is bounded independently: depth, keys per object,
+ * elements profiled, and the final byte count.
+ *
+ * What it deliberately does not do is sample. A field's value
+ * profile is either over the whole array or replaced by the
+ * length and a first-element shape, never a partial scan
+ * presented as a total, because a caller who queries on the
+ * strength of a wrong profile has been misled by the thing meant
+ * to orient them.
+ */
+const DEFAULT_MAX_KEYS = 40;
+const DEFAULT_MAX_DEPTH = 3;
+const DEFAULT_MAX_BYTES = 6000;
+// The pretty form spends bytes on newlines and indentation, so it gets a larger
+// cap: it is a terminal-only view a human reads on demand, never model context.
+const DEFAULT_PRETTY_MAX_BYTES = 20000;
+// Above this many array elements the profile stops tallying values and falls
+// back to a first-element sample. Tallying is linear in element count, so this
+// keeps the walk bounded no matter how large the parsed payload is, and it means
+// a reported value count is always over the whole array, never a partial scan
+// dressed up as exact. Every realistic result sits far below it.
+const DEFAULT_MAX_ELEMENTS = 20000;
+// How a profiled field's values are rendered: at most this many distinct values
+// listed before folding the rest into a "(+N more)" tail, and above the high
+// cardinality cutoff no values are listed at all, only the type and the distinct
+// count, so an id-like field opts itself out instead of listing noise. Long
+// scalar values are clipped so one value cannot dominate the summary.
+const TOP_VALUES = 6;
+const HIGH_CARDINALITY = 50;
+const MAX_VALUE_LEN = 24;
+/**
+ * Render a bounded structural summary of a parsed JSON value.
+ *
+ * An object becomes its keys mapped to value profiles, an array of objects
+ * becomes its length plus a per-key value-frequency profile, and a scalar
+ * becomes its type. Recursion stops at `maxDepth`, only `maxKeys` keys are shown
+ * before the rest are counted, arrays past `maxElements` degrade to a sample so
+ * the walk stays bounded, and the whole string is capped at `maxBytes`. With
+ * `pretty` the same shape is laid out across indented lines for a human to read.
+ */
+export function summarizeJson(value, opts = {}) {
+    const maxKeys = opts.maxKeys ?? DEFAULT_MAX_KEYS;
+    const maxDepth = opts.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const maxElements = opts.maxElements ?? DEFAULT_MAX_ELEMENTS;
+    const pretty = opts.pretty ?? false;
+    const maxBytes = opts.maxBytes ?? (pretty ? DEFAULT_PRETTY_MAX_BYTES : DEFAULT_MAX_BYTES);
+    return capBytes(describe(value, 0, maxDepth, maxKeys, maxElements, pretty), maxBytes);
+}
+/** The indentation for a given nesting depth in the pretty layout. */
+function pad(depth) {
+    return "  ".repeat(depth);
+}
+function describe(value, depth, maxDepth, maxKeys, maxElements, pretty) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return describeArray(value, depth, maxDepth, maxKeys, maxElements, pretty);
+    if (typeof value === "object")
+        return describeObject(value, depth, maxDepth, maxKeys, maxElements, pretty);
+    if (typeof value === "string")
+        return `string(${value.length})`;
+    return typeof value;
+}
+function describeArray(value, depth, maxDepth, maxKeys, maxElements, pretty) {
+    if (value.length === 0)
+        return "array(0)";
+    if (depth >= maxDepth)
+        return `array(${value.length})`;
+    // Past the element bound, sample the first element instead of tallying: the
+    // count is too large to profile without an unbounded walk, so show the shape
+    // and let the handle carry the detail a query can pull.
+    if (value.length > maxElements) {
+        const first = describe(value[0], depth + 1, maxDepth, maxKeys, maxElements, pretty);
+        return `array(${value.length}, first=${first})`;
+    }
+    if (value.every(isScalar))
+        return `array(${value.length}) of ${profileScalars(value)}`;
+    if (value.every(isPlainObject))
+        return `array(${value.length}) of {${profileObjectArray(value, depth, maxKeys, pretty)}}`;
+    const first = describe(value[0], depth + 1, maxDepth, maxKeys, maxElements, pretty);
+    return `array(${value.length}, first=${first})`;
+}
+/** A JSON scalar for profiling: a primitive or null, never an object or array. */
+function isScalar(value) {
+    return value === null || typeof value !== "object";
+}
+/** A plain (non-array) object, the shape the object-array profile expects. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Profile an array of objects: each key mapped to a profile of its values. */
+function profileObjectArray(rows, depth, maxKeys, pretty) {
+    const keys = [];
+    const seen = new Set();
+    for (const row of rows)
+        for (const key of Object.keys(row))
+            if (!seen.has(key)) {
+                seen.add(key);
+                keys.push(key);
+            }
+    const shown = keys.slice(0, maxKeys);
+    const parts = shown.map((key) => {
+        const values = rows
+            .map((row) => row[key])
+            .filter((v) => v !== undefined);
+        return `${key}: ${describeField(values, rows.length)}`;
+    });
+    const rest = keys.length - shown.length;
+    if (rest > 0)
+        parts.push(`(+${rest} more)`);
+    return joinEntries(parts, depth, pretty);
+}
+/**
+ * Profile a field, saying so when it is missing rather than saying
+ * nothing.
+ *
+ * A field can appear in the key set and hold a value on no record at
+ * all, and profiling only the values that exist then produced an
+ * empty string: "threadTs: " followed by the next field. A reader
+ * cannot tell from that whether the field is empty, absent, or a
+ * rendering fault, and it looks most like the last one. Real Slack
+ * data is where it showed up, since a message outside a thread
+ * carries neither a thread timestamp nor a reply count.
+ *
+ * Partial absence is worth the same honesty: a field carried by
+ * half the records is a different shape from one carried by all of
+ * them, and a query written against the first will come back
+ * shorter than expected for a reason the digest could have named.
+ */
+function describeField(values, rows) {
+    if (values.length === 0)
+        return `absent on all ${rows}`;
+    const missing = rows - values.length;
+    const profile = profileField(values);
+    return missing > 0 ? `${profile}, absent×${missing}` : profile;
+}
+/** Profile one field's collected values: scalars by frequency, else by type. */
+function profileField(values) {
+    if (values.every(isScalar))
+        return profileScalars(values);
+    if (values.every(isPlainObject))
+        return "object";
+    if (values.every(Array.isArray))
+        return "array";
+    return "mixed";
+}
+/**
+ * Profile a list of scalar values by frequency. Below the cardinality cutoff the
+ * most common values are listed with their counts; above it only the type and
+ * the distinct count are shown so a high-cardinality field stays compact.
+ */
+function profileScalars(values) {
+    const counts = new Map();
+    for (const value of values) {
+        const key = JSON.stringify(value) ?? "null";
+        const entry = counts.get(key);
+        if (entry)
+            entry.count++;
+        else
+            counts.set(key, { value, count: 1 });
+    }
+    if (counts.size > HIGH_CARDINALITY)
+        return `${scalarType(values)} (${counts.size} distinct)`;
+    const ranked = [...counts.values()].sort((a, b) => b.count - a.count);
+    const listed = ranked
+        .slice(0, TOP_VALUES)
+        .map((e) => e.count > 1 ? `${display(e.value)}×${e.count}` : display(e.value))
+        .join(", ");
+    const rest = ranked.length - TOP_VALUES;
+    return rest > 0 ? `${listed}, (+${rest} more)` : listed;
+}
+/** The shared type name of a list of scalars, or "mixed" when they disagree. */
+function scalarType(values) {
+    const types = new Set(values.map((v) => (v === null ? "null" : typeof v)));
+    return types.size === 1 ? [...types][0] : "mixed";
+}
+/** Render a scalar value for display, clipping a long string so it cannot dominate. */
+function display(value) {
+    if (typeof value !== "string")
+        return String(value);
+    return value.length > MAX_VALUE_LEN
+        ? `${value.slice(0, MAX_VALUE_LEN)}...`
+        : value;
+}
+function describeObject(value, depth, maxDepth, maxKeys, maxElements, pretty) {
+    const keys = Object.keys(value);
+    if (depth >= maxDepth)
+        return `object(${keys.length} keys)`;
+    const shown = keys.slice(0, maxKeys);
+    const parts = shown.map((key) => `${key}: ${describe(value[key], depth + 1, maxDepth, maxKeys, maxElements, pretty)}`);
+    const rest = keys.length - shown.length;
+    if (rest > 0)
+        parts.push(`(+${rest} more)`);
+    return `{${joinEntries(parts, depth, pretty)}}`;
+}
+/**
+ * Join the entries of an object or object-array profile. Compact form runs them
+ * on one line; pretty form puts each on its own indented line so a human can
+ * scan the shape, with the closing brace back at the parent's indentation.
+ */
+function joinEntries(parts, depth, pretty) {
+    if (!pretty)
+        return parts.join(", ");
+    if (parts.length === 0)
+        return "";
+    const inner = pad(depth + 1);
+    return `\n${parts.map((part) => inner + part).join("\n")}\n${pad(depth)}`;
+}
+/** Hard-cap a summary to `maxBytes`, cutting on a character boundary and marking the cut. */
+function capBytes(text, maxBytes) {
+    const buf = Buffer.from(text, "utf-8");
+    if (buf.length <= maxBytes)
+        return text;
+    const marker = "...";
+    const budget = Math.max(0, maxBytes - marker.length);
+    let end = budget;
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    return buf.toString("utf-8", 0, end) + marker;
+}

package/dist/result/follow.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Whether anything in this process can follow a handle.
+ *
+ * Every citation ends by telling the reader how to query the
+ * handle. That capability comes from one consumer of this library,
+ * and the consumers that mint handles are others, each loadable on
+ * their own. Load a browser tool without a query tool and every
+ * citation names a tool that is not there, which is worse than a
+ * long answer: the reader is told the rest of the data is one call
+ * away and the call does not exist.
+ *
+ * Kept on globalThis rather than in a module variable, because a
+ * module variable is not process-global when a host loads each
+ * consumer as its own module instance (pi loads each extension
+ * separately, for one). The symbol-keyed slot is the same
+ * mechanism the other registries in this package use for the same
+ * reason, and it also survives a module reimport.
+ */
+/**
+ * Declare that a tool in this process can follow handles.
+ *
+ * Called by whichever consumer registers the query tool, on
+ * activation. Idempotent.
+ */
+export declare function offerQueryTool(name: string): void;
+/** Withdraw the offer, when the consumer goes away or a test ends. */
+export declare function withdrawQueryTool(): void;
+/** The tool a citation should name, or undefined when there is none. */
+export declare function queryTool(): string | undefined;

package/dist/result/follow.js

@@ -0,0 +1,37 @@
+/**
+ * Whether anything in this process can follow a handle.
+ *
+ * Every citation ends by telling the reader how to query the
+ * handle. That capability comes from one consumer of this library,
+ * and the consumers that mint handles are others, each loadable on
+ * their own. Load a browser tool without a query tool and every
+ * citation names a tool that is not there, which is worse than a
+ * long answer: the reader is told the rest of the data is one call
+ * away and the call does not exist.
+ *
+ * Kept on globalThis rather than in a module variable, because a
+ * module variable is not process-global when a host loads each
+ * consumer as its own module instance (pi loads each extension
+ * separately, for one). The symbol-keyed slot is the same
+ * mechanism the other registries in this package use for the same
+ * reason, and it also survives a module reimport.
+ */
+/** Where the offer lives, shared by every copy of this module. */
+const SLOT = Symbol.for("pi:agentic-harness:result-query-tool");
+/**
+ * Declare that a tool in this process can follow handles.
+ *
+ * Called by whichever consumer registers the query tool, on
+ * activation. Idempotent.
+ */
+export function offerQueryTool(name) {
+    globalThis[SLOT] = name;
+}
+/** Withdraw the offer, when the consumer goes away or a test ends. */
+export function withdrawQueryTool() {
+    globalThis[SLOT] = undefined;
+}
+/** The tool a citation should name, or undefined when there is none. */
+export function queryTool() {
+    return globalThis[SLOT];
+}

package/dist/result/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tool answers that are bounded without being lossy.
+ *
+ * A tool with a large payload has always had two bad options:
+ * spend the caller's context on all of it, or cut it and lose the
+ * part that mattered. This library is the third option. The
+ * payload goes to a session store under an opaque handle, the
+ * answer carries a bounded view and a digest of the shape, and one
+ * query language reaches everything that was not shown.
+ *
+ * The pieces are separate because they are useful separately: a
+ * family that already knows how to page its own lists needs only
+ * the store and the citation, while one holding a single large
+ * document needs the digest too.
+ */
+export { type Citable, type Cited, cite } from "./cite.js";
+export { count } from "./counts.js";
+export { boundedByDetails, type DetailRecords, recordsIn, } from "./details.js";
+export { type JsonSummaryOptions, summarizeJson } from "./digest.js";
+export { offerQueryTool, queryTool, withdrawQueryTool } from "./follow.js";
+export { citeListing, LISTING_BUDGET_BYTES, type Listing, } from "./listing.js";
+export { cleanupSessionResults, isPidAlive, openSessionStore, RESULT_ROOT, reapAbandonedResults, SESSION_QUOTA_BYTES, sessionResultDir, } from "./location.js";
+export { DEFAULT_ANSWER_BYTES, DEFAULT_MAX_MATCHES, type QueryAnswer, type QueryOptions, queryStored, type TextBlock, } from "./query.js";
+export { type SpilledPayload, spillText } from "./spill.js";
+export { createResultStore, HandleExpiredError, MINTED_HANDLE_SHAPE, type ResultStore, type StoredResult, } from "./store.js";
+export { type BudgetedView, withinLineBudget } from "./view.js";

package/dist/result/index.js

@@ -0,0 +1,26 @@
+/**
+ * Tool answers that are bounded without being lossy.
+ *
+ * A tool with a large payload has always had two bad options:
+ * spend the caller's context on all of it, or cut it and lose the
+ * part that mattered. This library is the third option. The
+ * payload goes to a session store under an opaque handle, the
+ * answer carries a bounded view and a digest of the shape, and one
+ * query language reaches everything that was not shown.
+ *
+ * The pieces are separate because they are useful separately: a
+ * family that already knows how to page its own lists needs only
+ * the store and the citation, while one holding a single large
+ * document needs the digest too.
+ */
+export { cite } from "./cite.js";
+export { count } from "./counts.js";
+export { boundedByDetails, recordsIn, } from "./details.js";
+export { summarizeJson } from "./digest.js";
+export { offerQueryTool, queryTool, withdrawQueryTool } from "./follow.js";
+export { citeListing, LISTING_BUDGET_BYTES, } from "./listing.js";
+export { cleanupSessionResults, isPidAlive, openSessionStore, RESULT_ROOT, reapAbandonedResults, SESSION_QUOTA_BYTES, sessionResultDir, } from "./location.js";
+export { DEFAULT_ANSWER_BYTES, DEFAULT_MAX_MATCHES, queryStored, } from "./query.js";
+export { spillText } from "./spill.js";
+export { createResultStore, HandleExpiredError, MINTED_HANDLE_SHAPE, } from "./store.js";
+export { withinLineBudget } from "./view.js";

package/dist/result/listing.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A rendered listing, bounded for reading and stored for querying.
+ *
+ * Families render their own listings, and they should: a renderer
+ * that silently dropped rows would be lying in its own way.
+ * Bounding belongs here instead, at the point where the records
+ * are still to hand and can be kept.
+ *
+ * The counts in the citation are lines, because lines are what a
+ * reader can see and count for themselves. How many records those
+ * lines covered is not knowable from the text, and a citation
+ * nobody can check is a citation nobody should trust. What the
+ * payload actually holds is named separately, since a caller
+ * writing their first expression against lines when the payload
+ * holds records gets nothing back and no clue why.
+ */
+import type { ResultStore } from "./store.js";
+/** What a rendered listing spends before the rest is stored. */
+export declare const LISTING_BUDGET_BYTES = 8192;
+/** A listing, and the records behind it. */
+export interface Listing<T> {
+    /** The rendered view, however long it came out. */
+    readonly view: string;
+    /** The records the view was rendered from. */
+    readonly records: readonly T[];
+    /** What the records are, in the caller's words. */
+    readonly unit: string;
+    /** How to ask for less, in this kind's own vocabulary. */
+    readonly narrowing: string;
+    /**
+     * A line or two that must survive the cut.
+     *
+     * Some views end with the thing the caller needs in order to
+     * carry on: a cursor to read from next, a note that entries were
+     * dropped. Those sit at the end, which is exactly what a
+     * leading-lines budget removes, so the announcement stream lost
+     * its cursor and its overflow warning together and said nothing
+     * about either. Kept apart from the records because it is not a
+     * record, and appended after the cut rather than counted into it.
+     */
+    readonly trailer?: string;
+    /**
+     * Whether the view leaves records out on its own account.
+     *
+     * The budget is not the only thing that elides. An audit report
+     * lists five elements per rule and says "and 7,995 more", which
+     * fits any budget comfortably and is missing almost everything.
+     * Keying the citation on the cut alone meant the answer with the
+     * most left out was the one answer that offered no way to reach
+     * it.
+     */
+    readonly elided?: boolean;
+    readonly budget?: number;
+}
+/**
+ * Bound a listing and cite its records when the view was cut.
+ *
+ * A listing that fits is returned untouched, with no citation and
+ * no advice: the view is the whole truth and saying more would be
+ * noise.
+ */
+export declare function citeListing<T>(store: ResultStore, listing: Listing<T>): string;