agentfootprint 10.9.0 → 11.0.0

package/dist/esm/semantics/coverage/search/door.js

@@ -0,0 +1,130 @@
+/**
+ * search/door — which result door a search tool's value came through, and the
+ * facts composition reads off it.
+ *
+ * Pattern: one pure reader over the three doors a tool returns through —
+ *          `absent()`, `coverage()`, `describedResult()` — by their own
+ *          recognizers. No fourth door.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A search tool's coverage comes from its declaration, so a result that ALSO
+ * hand-writes a `checked` list is declined (`checked-beside-declared`): the
+ * library reads it as written, files today's row, and composes nothing — a
+ * row it did not compose establishes nothing. A `coverage()` wrapped around
+ * `absent({ checked: 'declared' })` is refused: the declaration is the
+ * boundary, so the absence is returned on its own.
+ */
+import { readSemantics } from '../../envelope.js';
+import { readItemExtras } from '../items.js';
+import { readPeriod, unservedPeriod } from '../period.js';
+import { readAbsence, readCoverageLedger, readDeclaredAbsence, readDeclaredLedger, } from '../recognize.js';
+import { refusal } from '../refusal.js';
+import { valueText } from './facets.js';
+import { readPaging, readResolved, } from './resultFacts.js';
+const nonEmpty = (list) => Array.isArray(list) && list.length > 0;
+/** A hand-written list, read as found: every entry kept (a gap is never lost). */
+function handList(list, section, toolName) {
+    if (!Array.isArray(list))
+        return [];
+    return list.map((raw) => {
+        const rec = raw;
+        const what = typeof rec?.what === 'string' && rec.what.trim() !== '' ? rec.what : valueText(raw);
+        return {
+            what,
+            ...(typeof rec?.why === 'string' && rec.why.trim() !== '' && { why: rec.why }),
+            ...readItemExtras(raw, section, toolName),
+        };
+    });
+}
+function periodOf(wire) {
+    return readPeriod(unservedPeriod(wire)).period;
+}
+function semanticRows(sem) {
+    return (sem.facts?.length ?? 0) + (sem.series?.length ?? 0) + (sem.edges?.length ?? 0);
+}
+/** A `coverage()` around `absent({ checked: 'declared' })` declares a second boundary. */
+function refuseWrappedAbsence(result) {
+    if (readDeclaredAbsence(result) === undefined)
+        return;
+    throw refusal("absent({ checked: 'declared' }) is returned on its own — the tool's `search` is its " +
+        'boundary, so a coverage() around it would declare a second one.');
+}
+/**
+ * Read `value` as one of the three doors, or `undefined` when it is none of
+ * them (plain data: nothing is composed).
+ */
+export function readSearchDoor(value, toolName) {
+    const declared = readDeclaredAbsence(value);
+    if (declared !== undefined) {
+        return {
+            outcome: 'door',
+            facts: {
+                door: 'declared-absence',
+                rows: 0,
+                resolved: readResolved(declared.resolved),
+                paging: readPaging(declared.paging),
+                period: periodOf(declared.period),
+                handNotChecked: handList(declared.not_checked, 'notChecked', toolName),
+                handCannotCover: handList(declared.cannot_cover, 'cannotCover', toolName),
+                absence: declared,
+            },
+        };
+    }
+    if (readAbsence(value) !== undefined)
+        return { outcome: 'checked-beside-declared' };
+    const sem = readSemantics(value);
+    if (sem !== undefined) {
+        if (nonEmpty(sem.coverage?.checked))
+            return { outcome: 'checked-beside-declared' };
+        return {
+            outcome: 'door',
+            facts: {
+                door: 'described',
+                rows: semanticRows(sem),
+                resolved: readResolved(sem.resolved),
+                paging: readPaging(sem.paging),
+                period: periodOf(sem.period),
+                handNotChecked: handList(sem.coverage?.not_checked, 'notChecked', toolName),
+                handCannotCover: handList(sem.coverage?.cannot_cover, 'cannotCover', toolName),
+            },
+        };
+    }
+    const declaredLedger = readDeclaredLedger(value);
+    if (declaredLedger !== undefined) {
+        refuseWrappedAbsence(declaredLedger.result);
+        if (readAbsence(declaredLedger.result) !== undefined) {
+            return { outcome: 'checked-beside-declared' };
+        }
+        const marker = declaredLedger.af_coverage;
+        return {
+            outcome: 'door',
+            facts: {
+                door: 'declared-coverage',
+                rows: Array.isArray(declaredLedger.result) ? declaredLedger.result.length : undefined,
+                period: periodOf(marker.period),
+                handNotChecked: handList(marker.not_checked, 'notChecked', toolName),
+                handCannotCover: handList(marker.cannot_cover, 'cannotCover', toolName),
+                ledger: declaredLedger,
+            },
+        };
+    }
+    const covered = readCoverageLedger(value);
+    if (covered === undefined)
+        return undefined;
+    refuseWrappedAbsence(covered.result);
+    if (nonEmpty(covered.af_coverage.checked) || readAbsence(covered.result) !== undefined) {
+        return { outcome: 'checked-beside-declared' };
+    }
+    return {
+        outcome: 'door',
+        facts: {
+            door: 'coverage',
+            rows: Array.isArray(covered.result) ? covered.result.length : undefined,
+            period: periodOf(covered.af_coverage.period),
+            handNotChecked: handList(covered.af_coverage.not_checked, 'notChecked', toolName),
+            handCannotCover: handList(covered.af_coverage.cannot_cover, 'cannotCover', toolName),
+        },
+    };
+}
+//# sourceMappingURL=door.js.map

package/dist/esm/semantics/coverage/search/door.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"door.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/door.ts"],"names":[],"mappings":"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"}

package/dist/esm/semantics/coverage/search/events.d.ts

@@ -0,0 +1,42 @@
+/**
+ * search/events — what a `search` tool's composed coverage puts on an EVENT.
+ *
+ * Pattern: one pure projection, read by the dispatch funnel for
+ *          `tools.absent` and `tools.coverage_declared`.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A (it shapes the payload; the funnel emits).
+ *
+ * Composed VALUES ride no event, in any mode. Events reach exporters, sinks
+ * and browsers that the run's redaction policy does not govern the way it
+ * governs the committed row, so a value the call sent — or a default, a
+ * host-filled identity, a result-declared instant — rides as a REFERENCE
+ * `{ resultId, argument }` to the row that holds it. What does ride:
+ *
+ *   • `checked` — the declaration's constants only (the declared source and
+ *     the fixed qualifiers), as `{ what }`;
+ *   • `notChecked` / `cannotCover` — the plain gap lists, whose words name
+ *     arguments and verdicts, never a value;
+ *   • `composition` — origin, the row's address, `complete`, the facet
+ *     references and the typed gaps.
+ *
+ * `lookedFor` is the tool's own words: today's bytes while `.negativeClaims()`
+ * is unarmed, and a reference to the row's field under the arm.
+ */
+import type { CoverageCompositionPayload, CoverageFieldReference, CoverageItemPayload } from '../../../events/payloads.js';
+import type { CoverageFacts } from '../read.js';
+/** The payload fields a composed statement contributes. */
+export interface ComposedEventFields {
+    readonly checked: readonly CoverageItemPayload[];
+    readonly notChecked: readonly CoverageItemPayload[];
+    readonly cannotCover: readonly CoverageItemPayload[];
+    readonly composition: CoverageCompositionPayload;
+    readonly lookedFor?: string;
+    readonly lookedForRef?: CoverageFieldReference;
+}
+/**
+ * The event fields of one composed statement. `facts` must carry `composed`
+ * (the funnel asks only for those).
+ */
+export declare function composedEventFields(facts: CoverageFacts, opts: {
+    readonly armed: boolean;
+}): ComposedEventFields;

package/dist/esm/semantics/coverage/search/events.js

@@ -0,0 +1,100 @@
+/**
+ * search/events — what a `search` tool's composed coverage puts on an EVENT.
+ *
+ * Pattern: one pure projection, read by the dispatch funnel for
+ *          `tools.absent` and `tools.coverage_declared`.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A (it shapes the payload; the funnel emits).
+ *
+ * Composed VALUES ride no event, in any mode. Events reach exporters, sinks
+ * and browsers that the run's redaction policy does not govern the way it
+ * governs the committed row, so a value the call sent — or a default, a
+ * host-filled identity, a result-declared instant — rides as a REFERENCE
+ * `{ resultId, argument }` to the row that holds it. What does ride:
+ *
+ *   • `checked` — the declaration's constants only (the declared source and
+ *     the fixed qualifiers), as `{ what }`;
+ *   • `notChecked` / `cannotCover` — the plain gap lists, whose words name
+ *     arguments and verdicts, never a value;
+ *   • `composition` — origin, the row's address, `complete`, the facet
+ *     references and the typed gaps.
+ *
+ * `lookedFor` is the tool's own words: today's bytes while `.negativeClaims()`
+ * is unarmed, and a reference to the row's field under the arm.
+ */
+/** Whether an item's `what` is the declaration's own words (no value of the call's). */
+const isConstant = (item) => item.from === 'tool' || item.from === 'fixed';
+function plainCopy(item) {
+    return {
+        what: item.what,
+        ...(item.why !== undefined && { why: item.why }),
+        ...(item.short !== undefined && { short: item.short }),
+        ...(item.kind !== undefined && { kind: item.kind }),
+    };
+}
+function gapCopy(gap) {
+    const bears = gap.bears;
+    return {
+        kind: gap.kind,
+        what: gap.what,
+        ...(gap.why !== undefined && { why: gap.why }),
+        ...(bears !== undefined && {
+            bears: typeof bears === 'string'
+                ? bears
+                : {
+                    filter: bears.filter,
+                    ...(bears.values !== undefined && { values: [...bears.values] }),
+                },
+        }),
+        ...(gap.argument !== undefined && { argument: gap.argument }),
+    };
+}
+/** One reference per facet, argument and origin — a list population is one reference. */
+function references(items, resultId) {
+    const out = [];
+    const seen = new Set();
+    for (const item of items) {
+        if (isConstant(item))
+            continue;
+        const key = `${item.facet}\u0000${item.from}\u0000${item.argument ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({
+            facet: item.facet,
+            from: item.from,
+            ref: { resultId, ...(item.argument !== undefined && { argument: item.argument }) },
+            ...(item.any === true && { any: true }),
+        });
+    }
+    return out;
+}
+/**
+ * The event fields of one composed statement. `facts` must carry `composed`
+ * (the funnel asks only for those).
+ */
+export function composedEventFields(facts, opts) {
+    const composed = facts.composed;
+    if (composed === undefined)
+        throw new TypeError('composedEventFields: not a composed statement');
+    const items = facts.coverage.checked;
+    const lookedFor = facts.lookedFor === undefined
+        ? {}
+        : opts.armed
+            ? { lookedForRef: { resultId: composed.resultId, field: 'lookedFor' } }
+            : { lookedFor: facts.lookedFor };
+    return {
+        checked: items.filter(isConstant).map((i) => ({ what: i.what })),
+        notChecked: facts.coverage.notChecked.map(plainCopy),
+        cannotCover: facts.coverage.cannotCover.map(plainCopy),
+        composition: {
+            origin: composed.origin,
+            resultId: composed.resultId,
+            complete: composed.complete,
+            facets: references(items, composed.resultId),
+            gaps: composed.gaps.map(gapCopy),
+        },
+        ...lookedFor,
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/esm/semantics/coverage/search/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/events.ts"],"names":[],"mappings":"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"}

package/dist/esm/semantics/coverage/search/facets.d.ts

@@ -0,0 +1,52 @@
+/**
+ * search/facets — the `checked` items one call's search covered.
+ *
+ * Pattern: one pure composer per list; this one is `checked`.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A facet enters `checked` from exactly these places, and nowhere else:
+ *
+ *   • the declared subject (`from: 'tool'`, `facet: 'subject'`) — what the
+ *     search looked for;
+ *   • the declared source (`from: 'tool'`) — or, when a `source` argument is
+ *     in effect, that argument: a sent value REPLACES the declared source and
+ *     keeps the declared words only when it equals the declared default;
+ *   • a declared fixed qualifier (`from: 'fixed'`);
+ *   • a value the call sent (`from: 'call'`), or a declared default the call
+ *     left out (`from: 'default'`, the value or `any`);
+ *   • an argument the host filled from the run's identity (`from: 'host'`,
+ *     its value by reference);
+ *   • the result's own `period.queried`, when no period argument is in effect
+ *     (`from: 'result'`).
+ *
+ * `cap`, `page`, `inert` and credential-filled arguments name no ground and
+ * compose no item; an unsent argument composes a gap instead (`gaps.ts`).
+ */
+import type { ComposedItem } from '../composedCoverage.js';
+import type { DeclaredPeriod } from '../period.js';
+import type { ArgumentReading } from './inEffect.js';
+import type { ResolvedDeclaration } from './resultFacts.js';
+import type { SearchArgument, ToolSearch } from './types.js';
+import type { PeriodShapes } from '../../../time/periodForm.js';
+/** What the facet composer reads. */
+export interface FacetInput {
+    readonly search: ToolSearch;
+    /** Each classified argument with its reading, in declaration order. */
+    readonly readings: ReadonlyArray<readonly [SearchArgument, ArgumentReading]>;
+    readonly resolved?: readonly ResolvedDeclaration[];
+    readonly resultPeriod?: DeclaredPeriod;
+    readonly period?: PeriodShapes;
+    /** When the call was dispatched — what a relative window is resolved at. */
+    readonly dispatchedAt?: string;
+}
+/**
+ * A value as composed text — a string as written, a number or boolean as
+ * printed, anything else as its JSON. Never spread into the item.
+ */
+export declare function valueText(value: unknown): string;
+/**
+ * The `checked` items, in a fixed order: the source, the subject, the fixed qualifiers,
+ * then each argument in declaration order, then a result-declared period.
+ */
+export declare function composeChecked(input: FacetInput): readonly ComposedItem[];

package/dist/esm/semantics/coverage/search/facets.js

@@ -0,0 +1,191 @@
+/**
+ * search/facets — the `checked` items one call's search covered.
+ *
+ * Pattern: one pure composer per list; this one is `checked`.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * A facet enters `checked` from exactly these places, and nowhere else:
+ *
+ *   • the declared subject (`from: 'tool'`, `facet: 'subject'`) — what the
+ *     search looked for;
+ *   • the declared source (`from: 'tool'`) — or, when a `source` argument is
+ *     in effect, that argument: a sent value REPLACES the declared source and
+ *     keeps the declared words only when it equals the declared default;
+ *   • a declared fixed qualifier (`from: 'fixed'`);
+ *   • a value the call sent (`from: 'call'`), or a declared default the call
+ *     left out (`from: 'default'`, the value or `any`);
+ *   • an argument the host filled from the run's identity (`from: 'host'`,
+ *     its value by reference);
+ *   • the result's own `period.queried`, when no period argument is in effect
+ *     (`from: 'result'`).
+ *
+ * `cap`, `page`, `inert` and credential-filled arguments name no ground and
+ * compose no item; an unsent argument composes a gap instead (`gaps.ts`).
+ */
+import { resolvedFor } from './binding.js';
+import { relativeSpan, resultSpan } from './span.js';
+import { valueWords } from './valueWords.js';
+/**
+ * A value as composed text — a string as written, a number or boolean as
+ * printed, anything else as its JSON. Never spread into the item.
+ */
+export function valueText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+        return String(value);
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/** Deep equality for the plain values a default may be. */
+function sameValue(a, b) {
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((v, i) => sameValue(v, b[i]));
+    }
+    return Object.is(a, b);
+}
+/** The facet each ground-naming role composes — a query's population is what matched it. */
+const ROLE_FACET = {
+    population: 'population',
+    filter: 'filter',
+    period: 'period',
+    query: 'population',
+    match: 'population',
+};
+/** The source item, or `undefined` when the source in effect is not known. */
+function sourceItem(input) {
+    const { search } = input;
+    const declared = { what: search.source.what, facet: 'source', said: search.source.said };
+    const entry = input.readings.find(([a]) => a.role === 'source');
+    if (entry === undefined)
+        return { ...declared, from: 'tool' };
+    const [arg, reading] = entry;
+    const isDefault = (v) => arg.whenOmitted !== undefined && sameValue(v, arg.whenOmitted);
+    switch (reading.kind) {
+        case 'sent': {
+            if (isDefault(reading.value)) {
+                return { ...declared, argument: arg.name, value: reading.value, from: 'call', quote: true };
+            }
+            const words = valueWords(arg.said, valueText(reading.value));
+            return {
+                what: `${arg.name}: ${valueText(reading.value)}`,
+                facet: 'source',
+                argument: arg.name,
+                value: reading.value,
+                from: 'call',
+                quote: true,
+                ...(words !== undefined && { said: [...words] }),
+            };
+        }
+        case 'default':
+            return { ...declared, argument: arg.name, value: reading.value, from: 'default' };
+        case 'any':
+            return { ...declared, from: 'tool' };
+        case 'host':
+            return hostItem(arg.name, reading.identity);
+        default:
+            // unsent (a gap) or credential-filled (names no ground)
+            return undefined;
+    }
+}
+function hostItem(argument, identity) {
+    return {
+        what: `${argument}: the caller's ${identity}`,
+        facet: 'filter',
+        argument,
+        value: { identity },
+        from: 'host',
+    };
+}
+/** The items one non-source argument composes — none, one, or one per list value. */
+function argumentItems(arg, reading, input) {
+    if (reading.kind === 'host')
+        return [hostItem(arg.name, reading.identity)];
+    if (!Object.hasOwn(ROLE_FACET, arg.role))
+        return [];
+    const facet = ROLE_FACET[arg.role];
+    if (reading.kind === 'any') {
+        return [{ what: `${arg.name}: any`, facet, argument: arg.name, any: true, from: 'default' }];
+    }
+    if (reading.kind !== 'sent' && reading.kind !== 'default')
+        return [];
+    const from = reading.kind === 'sent' ? 'call' : 'default';
+    const values = arg.role === 'population' && Array.isArray(reading.value) ? reading.value : [reading.value];
+    return values.map((value) => {
+        const words = arg.role === 'filter' ? valueWords(arg.said, valueText(value)) : undefined;
+        const resolved = arg.role === 'population' ? resolvedFor(arg.name, value, input.resolved) : undefined;
+        const span = arg.role === 'period'
+            ? relativeSpan(arg.name, value, input.period, input.dispatchedAt)
+            : undefined;
+        return {
+            what: `${arg.name}: ${valueText(value)}`,
+            facet,
+            argument: arg.name,
+            value,
+            from,
+            ...((from === 'call' || resolved !== undefined) && { quote: true }),
+            ...(resolved !== undefined && { resolved }),
+            ...(words !== undefined && { said: [...words] }),
+            ...(span !== undefined && { span }),
+        };
+    });
+}
+/** The period facet the RESULT declared, when no period argument is in effect. */
+function resultPeriodItem(input) {
+    const period = input.resultPeriod;
+    if (period === undefined)
+        return undefined;
+    if (input.readings.some(([a]) => a.role === 'period'))
+        return undefined;
+    const span = resultSpan(period);
+    return {
+        what: `period: ${period.queried.from} to ${period.queried.to}`,
+        facet: 'period',
+        from: 'result',
+        quote: true,
+        ...(span !== undefined && { span }),
+    };
+}
+/**
+ * The `checked` items, in a fixed order: the source, the subject, the fixed qualifiers,
+ * then each argument in declaration order, then a result-declared period.
+ */
+export function composeChecked(input) {
+    const items = [];
+    const source = sourceItem(input);
+    if (source !== undefined)
+        items.push(source);
+    // What the search looked for — the declaration's words; the statement names it.
+    items.push({
+        what: input.search.subject.what,
+        facet: 'subject',
+        from: 'tool',
+        said: [...input.search.subject.said],
+    });
+    for (const q of input.search.fixed ?? []) {
+        items.push({
+            what: `${q.name}: ${valueText(q.value)}`,
+            facet: 'filter',
+            argument: q.name,
+            value: q.value,
+            from: 'fixed',
+            said: [...q.said],
+        });
+    }
+    for (const [arg, reading] of input.readings) {
+        if (arg.role === 'source')
+            continue;
+        items.push(...argumentItems(arg, reading, input));
+    }
+    const fromResult = resultPeriodItem(input);
+    if (fromResult !== undefined)
+        items.push(fromResult);
+    return items;
+}
+//# sourceMappingURL=facets.js.map

package/dist/esm/semantics/coverage/search/facets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"facets.js","sourceRoot":"","sources":["../../../../../src/semantics/coverage/search/facets.ts"],"names":[],"mappings":"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"}

package/dist/esm/semantics/coverage/search/gaps.d.ts

@@ -0,0 +1,63 @@
+/**
+ * search/gaps — the ground one call's search did NOT cover, typed.
+ *
+ * Pattern: one pure composer per list; this one is the gaps.
+ * Role:    semantics/ layer, pure.
+ * Emits:   N/A.
+ *
+ * Each gap names the facet it bears on, so a checker decides relevance by
+ * facet and never by reading prose:
+ *
+ *   • `argument-unsent` — any classified argument of any role but `inert` the
+ *     call did not send, with no `whenOmitted`, or sent as an empty list: its
+ *     default may live inside `execute`, and an empty list names nothing (it is
+ *     never "every value"). Bears on that argument's facet (cap and page:
+ *     completeness).
+ *   • `cap-reached` — rows at the cap in effect (an argument's, or the
+ *     declared server cap), rows that cannot be counted under a cap, or a
+ *     server cap of `'unknown'`. Bears on completeness.
+ *   • `paged` — a page argument sent, a result whose `paging.next` is not
+ *     null, or a tool with a `page` argument whose result declares no
+ *     `paging`. Bears on completeness.
+ *   • `partial` — the tool declared its outcome `partial` or `pending`.
+ *   • `period` — the declared period's verdict is not `covered`.
+ *   • `scope` — the declaration's own constants.
+ *   • `prose` — a hand-written `notChecked` / `cannotCover` item; no facet.
+ *
+ * Every `what` the library writes here names an ARGUMENT or a verdict, never
+ * a value the call sent.
+ */
+import type { CoverageGap } from '../composedCoverage.js';
+import { type DeclaredPeriod } from '../period.js';
+import type { CoverageItem } from '../types.js';
+import type { ArgumentReading } from './inEffect.js';
+import type { PagingDeclaration } from './resultFacts.js';
+import type { SearchArgument, ToolSearch } from './types.js';
+import type { ToolResultStatus } from '../../toolOutcome.js';
+/** What the gap composer reads. */
+export interface GapInput {
+    readonly search: ToolSearch;
+    readonly readings: ReadonlyArray<readonly [SearchArgument, ArgumentReading]>;
+    /** How many rows the result carried; `undefined` when it cannot be counted. */
+    readonly rows: number | undefined;
+    readonly paging?: PagingDeclaration;
+    readonly period?: DeclaredPeriod;
+    readonly status?: ToolResultStatus;
+    readonly handNotChecked: readonly CoverageItem[];
+    readonly handCannotCover: readonly CoverageItem[];
+}
+/** The gaps, and the two plain lists every older reader prints. */
+export interface ComposedGaps {
+    readonly gaps: readonly CoverageGap[];
+    readonly notChecked: readonly CoverageItem[];
+    readonly cannotCover: readonly CoverageItem[];
+}
+/**
+ * Every gap of one call, in a fixed order, with the plain lists: the
+ * composed gaps (but `period`, which the period row carries) and the
+ * hand-written `notChecked` under `notChecked`; the declared constants and the
+ * hand-written `cannotCover` under `cannotCover`.
+ */
+export declare function composeGaps(input: GapInput): ComposedGaps;
+/** The gap kinds that keep a row from being complete — and `prose`, which names no facet. */
+export declare function blocksComplete(gap: CoverageGap): boolean;