agentfootprint 10.3.0 → 10.4.0

package/dist/esm/semantics/coverage/timeLimits.d.ts

@@ -0,0 +1,67 @@
+/**
+ * coverage/timeLimits.ts — the time layer's limits lines for ONE turn (step T8),
+ * composed from the record and nothing else.
+ *
+ * Two readers ask it, so the person and the model are told the same thing:
+ *
+ * - the limits block (`stages/prepareFinal.ts`), which prints the lines under
+ *   `Period` and `Clocks` for the PERSON after the answer;
+ * - the served time line (`agent/arguments/serve.ts` · `timeLimitsSentence`),
+ *   which hands the MODEL the same lines as the library's conclusion, late, at
+ *   the decision point, before it writes the answer.
+ *
+ * What it reads: the facts `timeLimitFacts.ts` · `timeLimitFactsOf` reads —
+ * the turn's `period` rows whose result checks hold, the turn's
+ * `source-clock` rows (`time/checkRecord.ts` · `clocksDiffer`) and the
+ * clock row's zone — rendered here (`period.ts` · `periodCheckLine`,
+ * `clockLines`). `undefined` when there is no clock (nothing to render in) or
+ * nothing to say.
+ *
+ * Loaded through `import()` only, under `.time()` (`stages/prepareFinal.ts`;
+ * `arguments/serve.ts`, itself loaded under the arm): it renders through
+ * `time/present.ts`, which a plain agent never loads.
+ */
+import { type PeriodRow } from './period.js';
+import { type BoundPresentation } from '../../time/present.js';
+import type { TimeLimitLines } from './answer.js';
+import { type TimeLimitFacts, type TimeLimitsAudience } from './timeLimitFacts.js';
+export type { TimeLimitLines };
+/** The clocks line under an unknown zone (G15): the ranges are in UTC because the person's zone is not known. */
+export declare const UNKNOWN_ZONE_LINE = "times are shown in UTC \u2014 the person's time zone is not known";
+/**
+ * The model's line for a call whose source holds none or only part of the
+ * time it asked about (`PeriodRow.held`): what the call asked about and what
+ * its source holds, each AS DECLARED (inclusive ends, no end moved) and
+ * rendered in the presentation zone by the time layer's one renderer — the
+ * same spans the person's `Period:` line prints (`period.ts` · `periodLine`) — then
+ * how much of the asked time that is. `undefined` when the row carries none.
+ *
+ * @example
+ * ```ts
+ * heldLine(row, bindPresentation({ zone: 'America/Los_Angeles' }));
+ * // 'pscale_client_health asked about 2026-09-30 06:00:00–11:59:50 America/Los_Angeles (UTC-07:00);
+ * //  its source holds 2026-10-01 09:22:44.300–10:02:44.300 America/Los_Angeles (UTC-07:00), which
+ * //  covers none of that time'
+ * ```
+ */
+export declare function heldLine(row: PeriodRow, presentation: BoundPresentation): string | undefined;
+/**
+ * The turn's time limits lines, from the ledger — {@link renderTimeLimits}
+ * over `timeLimitFacts.ts` · `timeLimitFactsOf`. `turn` undefined reads every
+ * row (a ledger that carries one turn). `audience` `'model'` (the served time
+ * line) names the person's window as theirs and keeps, of the clocks, only the
+ * label that two differ.
+ *
+ * @example
+ * ```ts
+ * timeLimitLinesOf(ledger, 1);
+ * // { period: ['client_activity read less than was asked — asked: …; read: …'], clocks: [] }
+ * ```
+ */
+export declare function timeLimitLinesOf(ledger: readonly unknown[] | undefined, turn: number | undefined, audience?: TimeLimitsAudience): TimeLimitLines | undefined;
+/**
+ * The limits lines for `audience`, rendered in the facts' zone by the time
+ * layer's one renderer (`time/present.ts` · `bindPresentation`) —
+ * `undefined` when there are no facts or nothing to say.
+ */
+export declare function renderTimeLimits(facts: TimeLimitFacts | undefined, audience?: TimeLimitsAudience): TimeLimitLines | undefined;

package/dist/esm/semantics/coverage/timeLimits.js

@@ -0,0 +1,115 @@
+/**
+ * coverage/timeLimits.ts — the time layer's limits lines for ONE turn (step T8),
+ * composed from the record and nothing else.
+ *
+ * Two readers ask it, so the person and the model are told the same thing:
+ *
+ * - the limits block (`stages/prepareFinal.ts`), which prints the lines under
+ *   `Period` and `Clocks` for the PERSON after the answer;
+ * - the served time line (`agent/arguments/serve.ts` · `timeLimitsSentence`),
+ *   which hands the MODEL the same lines as the library's conclusion, late, at
+ *   the decision point, before it writes the answer.
+ *
+ * What it reads: the facts `timeLimitFacts.ts` · `timeLimitFactsOf` reads —
+ * the turn's `period` rows whose result checks hold, the turn's
+ * `source-clock` rows (`time/checkRecord.ts` · `clocksDiffer`) and the
+ * clock row's zone — rendered here (`period.ts` · `periodCheckLine`,
+ * `clockLines`). `undefined` when there is no clock (nothing to render in) or
+ * nothing to say.
+ *
+ * Loaded through `import()` only, under `.time()` (`stages/prepareFinal.ts`;
+ * `arguments/serve.ts`, itself loaded under the arm): it renders through
+ * `time/present.ts`, which a plain agent never loads.
+ */
+import { clockLines, periodCheckLine } from './period.js';
+import { bindPresentation } from '../../time/present.js';
+import { timeLimitFactsOf, } from './timeLimitFacts.js';
+// LENS · late-line · request-ephemeral (and the person's limits block)
+// reads: nothing — a fixed clause, added when the turn's clock zone is unknown (G15)
+// law: names WHY the ranges are in UTC, so no reader takes UTC for the person's zone.
+/** The clocks line under an unknown zone (G15): the ranges are in UTC because the person's zone is not known. */
+export const UNKNOWN_ZONE_LINE = "times are shown in UTC — the person's time zone is not known";
+// LENS · late-line · request-ephemeral
+// reads: one `period` row's `held` (the declared `queried` and `held` spans its `not-held` /
+//        `partly-held` verdict came from), rendered in the person's zone by the bound renderer
+// law: the library's CONCLUSION for the MODEL: the time the source holds, already in the person's
+//      zone, beside the time the call asked about — so no model converts a source's UTC instants
+//      (take 3: "9:22 AM–5:02 PM Pacific" for a 16:22–17:02 UTC span).
+/**
+ * The model's line for a call whose source holds none or only part of the
+ * time it asked about (`PeriodRow.held`): what the call asked about and what
+ * its source holds, each AS DECLARED (inclusive ends, no end moved) and
+ * rendered in the presentation zone by the time layer's one renderer — the
+ * same spans the person's `Period:` line prints (`period.ts` · `periodLine`) — then
+ * how much of the asked time that is. `undefined` when the row carries none.
+ *
+ * @example
+ * ```ts
+ * heldLine(row, bindPresentation({ zone: 'America/Los_Angeles' }));
+ * // 'pscale_client_health asked about 2026-09-30 06:00:00–11:59:50 America/Los_Angeles (UTC-07:00);
+ * //  its source holds 2026-10-01 09:22:44.300–10:02:44.300 America/Los_Angeles (UTC-07:00), which
+ * //  covers none of that time'
+ * ```
+ */
+export function heldLine(row, presentation) {
+    const h = row.held;
+    if (h === undefined)
+        return undefined;
+    const share = row.verdict === 'partly-held'
+        ? 'which covers only part of that time'
+        : 'which covers none of that time';
+    return (`${row.toolName} asked about ${presentation.span(h.queried.from, h.queried.to)}; ` +
+        `its source holds ${presentation.span(h.held.from, h.held.to)}, ${share}`);
+}
+/**
+ * The turn's time limits lines, from the ledger — {@link renderTimeLimits}
+ * over `timeLimitFacts.ts` · `timeLimitFactsOf`. `turn` undefined reads every
+ * row (a ledger that carries one turn). `audience` `'model'` (the served time
+ * line) names the person's window as theirs and keeps, of the clocks, only the
+ * label that two differ.
+ *
+ * @example
+ * ```ts
+ * timeLimitLinesOf(ledger, 1);
+ * // { period: ['client_activity read less than was asked — asked: …; read: …'], clocks: [] }
+ * ```
+ */
+export function timeLimitLinesOf(ledger, turn, audience = 'person') {
+    return renderTimeLimits(timeLimitFactsOf(ledger, turn, audience), audience);
+}
+/**
+ * The limits lines for `audience`, rendered in the facts' zone by the time
+ * layer's one renderer (`time/present.ts` · `bindPresentation`) —
+ * `undefined` when there are no facts or nothing to say.
+ */
+export function renderTimeLimits(facts, audience = 'person') {
+    if (facts === undefined)
+        return undefined;
+    const presentation = bindPresentation({ zone: facts.zone });
+    const period = [];
+    const held = [];
+    for (const row of facts.period) {
+        const line = periodCheckLine(row, presentation, audience);
+        if (line !== undefined)
+            period.push(line);
+        // The source's held span, for the model (the person's `Period:` line already prints it).
+        const holds = audience === 'model' ? heldLine(row, presentation) : undefined;
+        if (holds !== undefined)
+            held.push(holds);
+    }
+    // The person reads every wall-clock source; the model only the label that two differ — one
+    // declared clock is compared as instants and changes nothing the answer states.
+    const clocks = [
+        ...(audience === 'person'
+            ? clockLines(facts.sources, facts.differ)
+            : facts.differ === undefined
+                ? []
+                : clockLines([], facts.differ)),
+        // The ranges above are spelled in UTC only because the person's zone is unknown (G15).
+        ...(facts.zoneUnknown === true && period.length + held.length > 0 ? [UNKNOWN_ZONE_LINE] : []),
+    ];
+    if (period.length + clocks.length + held.length === 0)
+        return undefined;
+    return { period, clocks, ...(held.length > 0 && { held }) };
+}
+//# sourceMappingURL=timeLimits.js.map

package/dist/esm/semantics/coverage/timeLimits.js.map

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

package/dist/esm/semantics/coverage/types.d.ts

@@ -0,0 +1,320 @@
+/**
+ * coverage/types — the shared vocabulary of the two coverage primitives.
+ *
+ * Pattern: one value type, two consumers — `absent()` says "I looked HERE and
+ *          found nothing", `coverage()` says "my answer covers THIS and not
+ *          THAT". Both are statements about the same thing: the ground a
+ *          result stands on. Spelling them with one vocabulary is what lets
+ *          the answer-level block merge an absence's boundary with a
+ *          verdict's without translating between two grammars.
+ * Role:    core/ layer, pure data. No behavior; TYPE-only imports (they erase
+ *          at runtime): the one period shape (`period.ts`) and the one
+ *          provenance shape `describedResult()` already declares
+ *          (`semantics/types.ts`), so an absence says its source and time
+ *          in the same words a described result does.
+ * Emits:   N/A.
+ */
+import type { DescribedResultDeclaration, SemanticProvenance } from '../types.js';
+import type { DeclaredPeriod, PeriodOnWire } from './period.js';
+/**
+ * One piece of ground, and (optionally) why it is where it is.
+ *
+ * `what` is prose the TOOL AUTHOR wrote — a source, a window, a filter, a
+ * fleet ("the fcns database on shq-fab-a", "the last 24h", "all four
+ * arrays"). It is never composed from the model's arguments by this library,
+ * because the library does not know which of them are real.
+ */
+export interface CoverageItem {
+    /** The source, window, filter or population. Non-empty. */
+    readonly what: string;
+    /**
+     * Why it sits where it does. REQUIRED on `cannotCover` (a permanent blind
+     * spot is a claim about capability, and a claim with no reason cannot be
+     * acted on or disproved); optional on `checked` and `notChecked`, where
+     * "we did" and "we did not need to" are often the whole story.
+     */
+    readonly why?: string;
+    /**
+     * A short plain form of `what`, for a person reading a report — "every VM
+     * disk in the RVTools export of 2026-09-19" for a `what` that names the two
+     * tables it read. Optional; at most 80 characters, one line, and never
+     * longer than `what`.
+     *
+     * RECORD-ONLY: it rides the events (`tools.absent`,
+     * `tools.coverage_declared`), the tracked `coverageDeclared` rows and the
+     * answer account, and is REMOVED from what the model is served
+     * (`read.ts` · `servedToModel`). It is also withheld from the evidence
+     * corpus (`evidence.ts`), because it is the field an author is most tempted
+     * to personalise: NEVER interpolate the caller's arguments into it — a true
+     * short form restates `what`, so no value should live only here.
+     */
+    readonly short?: string;
+    /**
+     * What kind of ground a `notChecked` or `cannotCover` item is — a CLOSED
+     * set, read by the answer account's existence check:
+     *
+     *   • `'existence'` — whether the thing asked about exists at all, or is
+     *     the kind of thing the question assumes ("whether that name is a
+     *     storage array").
+     *   • `'scope'` — a population, family or source outside what this tool
+     *     reaches ("hosts that are not VMware").
+     *
+     * Refused on `checked`. RECORD-ONLY, like `short`. Absent = not declared:
+     * a reader never infers a kind from `what`. Library code never switches
+     * EXHAUSTIVELY over this union (every switch has a `default` arm), so a
+     * later member is an additive change for producers.
+     */
+    readonly kind?: 'existence' | 'scope';
+}
+/** What an author may write in a coverage list: bare prose, or prose + why. */
+export type CoverageInput = string | CoverageItem;
+/**
+ * One thing the tool READ and found still RUNNING — a backup in progress, a
+ * replication session still synchronizing — whose outcome is therefore not
+ * known yet: neither a success nor a failure (`coverage()`'s `inProgress`).
+ *
+ * The TOOL decides which of its vendor's states are in flight — this library
+ * never reads a state name, and the vendor's own verdict field, when there is
+ * one, is the tool's to weigh. `what` is the author's prose, as for every
+ * coverage item; `short` is the same RECORD-ONLY short form. `count` says how
+ * many things this one entry stands for ("96 sessions still synchronizing" is
+ * one entry with `count: 96`); omitted, the entry is one thing. It is served —
+ * the model reads the number as the tool's own.
+ *
+ * No `kind`: that names ground a call did NOT reach, and an item in progress
+ * is ground it reached.
+ */
+export interface InProgressItem {
+    /** What is still running. Non-empty. */
+    readonly what: string;
+    /** Since when, or what the vendor reported — optional. */
+    readonly why?: string;
+    /** RECORD-ONLY short form, the {@link CoverageItem.short} rules. */
+    readonly short?: string;
+    /** How many things this entry stands for — a positive whole number; omitted = one. */
+    readonly count?: number;
+}
+/** What an author may write in `inProgress`: bare prose, or an {@link InProgressItem}. */
+export type InProgressInput = string | InProgressItem;
+/**
+ * The three lists, normalized. This is the shape everything downstream reads —
+ * the renderer, the event payload, the answer-level block.
+ *
+ * The three are NOT interchangeable, and the difference is the whole point:
+ *
+ *   • `checked` — ground this result actually stands on. A clean verdict here
+ *     means VERIFIED.
+ *   • `notChecked` — ground this run could have covered and did not (budget,
+ *     a timeout, a scope the caller chose). A clean verdict says nothing
+ *     about it. Re-asking with a wider scope can move it to `checked`.
+ *   • `cannotCover` — ground no call to this tool will ever reach (no
+ *     collector, no permission, no such telemetry). A clean verdict says
+ *     nothing about it, and no retry ever will. This is the list that turns
+ *     "everything looks fine" into "everything I can see looks fine".
+ */
+export interface Coverage {
+    readonly checked: readonly CoverageItem[];
+    readonly notChecked: readonly CoverageItem[];
+    readonly cannotCover: readonly CoverageItem[];
+}
+/** What a tool author passes to {@link import('./ledger.js').coverage}. */
+export interface CoverageDeclaration {
+    readonly checked?: readonly CoverageInput[];
+    readonly notChecked?: readonly CoverageInput[];
+    readonly cannotCover?: readonly CoverageInput[];
+}
+/**
+ * The other TOOL a suggestion points at, typed (9.113.0) — `tryInsteadTool`
+ * on the declaration, `try_instead_tool` on the envelope.
+ *
+ * The `tryInstead` sentence puts a tool's name inside prose ("…or check
+ * cluster_inventory for the collected names."), and a reader that wants to
+ * know WHICH tool was suggested could only find out by parsing that sentence.
+ * This library never parses a tool name out of prose, so the name rides here
+ * as data — BESIDE the sentence, never in its place: `try_instead` stays a
+ * string, so every reader of it reads what it always read.
+ *
+ * `tool` is NOT looked up. The tool may be served by a provider that resolves
+ * per iteration, or be offered on a later turn; `absent()` requires a
+ * non-empty name and records it as declared. Which names a provider accepts is
+ * `lib/toolName.ts` · `assertValidToolName`'s question, and the library only
+ * warns about it (dev mode), here as at `defineTool`.
+ */
+export interface TryInsteadTool {
+    /** The tool's registered name, as a call would name it. */
+    readonly tool: string;
+    /** Why that tool, in the author's words ("it lists the collected names"). */
+    readonly why?: string;
+}
+/** What a tool author passes to {@link import('./absent.js').absent}. */
+export interface AbsenceDeclaration {
+    /**
+     * What was looked for, in the author's own words ("FLOGI entries on
+     * fc1/3"). Required: an absence that cannot say what it did not find is
+     * indistinguishable from a tool that returned nothing by accident.
+     */
+    readonly what: string;
+    /**
+     * The coverage of the search — REQUIRED and non-empty. An absence that
+     * names no coverage is a `null` with extra steps: the reader still cannot
+     * tell "I looked and there is nothing" from "I could not look", which is
+     * the entire failure this primitive exists to prevent.
+     */
+    readonly checked: readonly CoverageInput[];
+    /** Ground the search did not reach this time — an absence here proves
+     *  nothing about it. */
+    readonly notChecked?: readonly CoverageInput[];
+    /** Ground no search by this tool can reach. Each needs a `why`. */
+    readonly cannotCover?: readonly CoverageInput[];
+    /**
+     * Where to go INSTEAD, in one sentence ("widen the window with
+     * `window: '7d'`, or ask for a different interface"). Optional, and the
+     * highest-value optional field in the shape: the loop this primitive stops
+     * is a model with nowhere else to go.
+     *
+     * Prose for the model. Nothing in this library reads a tool name out of it:
+     * when the sentence points at another tool, name that tool in
+     * {@link AbsenceDeclaration.tryInsteadTool} as well.
+     */
+    readonly tryInstead?: string;
+    /**
+     * The other TOOL the suggestion points at, as data (9.113.0) —
+     * `{ tool, why? }`. Beside the sentence, not instead of it: the sentence is
+     * what the model is told, this is what a reader reads without parsing
+     * prose. Either may be given without the other; when both are given they
+     * must name the same tool, and the library cannot check that they do — it
+     * would have to read a tool name out of the sentence. ONE tool; a list is
+     * refused (see `absent.ts` · `readToolSuggestion` for why).
+     */
+    readonly tryInsteadTool?: TryInsteadTool;
+    /**
+     * Where the search looked and how old that source is — the SAME shape
+     * `describedResult()` declares (`measuredAt`, `source`, and optionally
+     * `ageSeconds`, `sourceExportDate`), respelled to the same snake_case wire
+     * (honesty step 7b). `measuredAt` and `source` are both required once it is
+     * present. So the found branch and the not-found branch of one `execute`
+     * carry their source and time in one shape: "searched the 02:00 export —
+     * nothing" as data, not prose in `checked`. `measuredAt` is the tool's own
+     * words, never parsed.
+     */
+    readonly provenance?: NonNullable<DescribedResultDeclaration['provenance']>;
+    /**
+     * What the search's READ covered in time — the instants it asked for, and
+     * what the store holds (or `'unknown'`, said out loud) — honesty step 7b.
+     * Every value is an ISO 8601 instant with a zone; a malformed period is
+     * refused here. The results layer files its verdict (covered · partly held ·
+     * not held · unknown), and `.limitsTravelWithTheAnswer()` prints it.
+     */
+    readonly period?: DeclaredPeriod;
+}
+/**
+ * What a tool author passes to {@link import('./ledger.js').coverage}: the
+ * three lists, and the period the verdict's read covered (honesty step 7b).
+ * `coverage()` takes no `provenance` — a value that comes as rows from a
+ * system of record has `describedResult()`.
+ *
+ * @inline
+ */
+export type CoverageLedgerDeclaration = CoverageDeclaration & {
+    /**
+     * What the read behind this value covered in time — the instants it asked
+     * for, and what the store holds (or `'unknown'`). Refused when malformed.
+     */
+    readonly period?: DeclaredPeriod;
+    /**
+     * What the read found still RUNNING — its outcome not known yet (a backup in
+     * progress, a session still synchronizing). The tool decides what is in
+     * flight; the library never reads a vendor's state name. Needs `checked`
+     * beside it (an item in progress is ground the call read). An empty list
+     * says nothing and is omitted, like every coverage list. Served as
+     * `in_progress`, with one static clause after the note; recorded on the
+     * `coverageDeclared` row and `tools.coverage_declared`; printed under
+     * `.limitsTravelWithTheAnswer()`. It never changes the answer's standing.
+     */
+    readonly inProgress?: readonly InProgressInput[];
+};
+/**
+ * The rendered absence — the exact object a tool hands back and the model
+ * reads. Field names are snake_case and English on purpose: this value is
+ * read by a language model far more often than by code, and `af_absent` is
+ * the only field here that exists for the machine.
+ *
+ * The `af_absent` key is RESERVED vocabulary on the tool-result wire (the
+ * `propose-transition` / `require-instruction` precedent): a plain object
+ * carrying it is an absence, and nothing else in this library will treat any
+ * other shape as one.
+ */
+export interface ToolAbsence {
+    readonly af_absent: true;
+    /** The plain-English handle. Present so a model that skims one key still
+     *  reads the outcome rather than inferring it from a missing field. */
+    readonly outcome: 'nothing_found';
+    readonly looked_for: string;
+    readonly checked: readonly CoverageItem[];
+    readonly not_checked?: readonly CoverageItem[];
+    readonly cannot_cover?: readonly CoverageItem[];
+    /** Stated as data as well as prose — the note can be skimmed past, a
+     *  `true` in a field named for the question cannot. */
+    readonly retry_returns_the_same: true;
+    /** The author's sentence. A string, always — the typed tool rides its own
+     *  key, so a reader of this one never has to narrow it. */
+    readonly try_instead?: string;
+    /** The typed tool the suggestion points at (9.113.0), as declared — the
+     *  author's words, `{ tool, why? }`. The model reads it as written. */
+    readonly try_instead_tool?: TryInsteadTool;
+    /** Where the search looked and when that source was measured — the wire
+     *  `describedResult()` mints (`measured_at`, `source`, …), honesty step 7b. */
+    readonly provenance?: SemanticProvenance;
+    /** What the search's read covered in time — `queried`, `held` (or
+     *  `'unknown'`), `read_at` — honesty step 7b. */
+    readonly period?: PeriodOnWire;
+    /** The static sentence. Never interpolated — see `absent.ts`. */
+    readonly note: string;
+}
+/** The rendered coverage ledger, wrapped around the result it bounds. */
+export interface CoveredResult<T = unknown> {
+    readonly af_coverage: {
+        readonly checked?: readonly CoverageItem[];
+        readonly not_checked?: readonly CoverageItem[];
+        readonly cannot_cover?: readonly CoverageItem[];
+        /** What the read found still running — its outcome not known yet.
+         *  Serialized before `result`, like the lists. */
+        readonly in_progress?: readonly InProgressItem[];
+        /** What the read behind the value covered in time — honesty step 7b.
+         *  Serialized before `result`, like the lists. */
+        readonly period?: PeriodOnWire;
+        readonly note: string;
+    };
+    /** The tool's own answer, untouched. */
+    readonly result: T;
+}
+/**
+ * One coverage statement as the RUN recorded it — what the event carries and
+ * what accumulates in `AgentState.coverageDeclared`.
+ *
+ * `kind` is kept because the two read differently at the answer boundary: a
+ * `'ledger'` bounds a verdict the answer is probably built on, an
+ * `'absence'` bounds a search that found nothing.
+ */
+export interface DeclaredCoverage extends Coverage {
+    readonly kind: 'absence' | 'ledger';
+    readonly toolName: string;
+    readonly toolCallId?: string;
+    readonly iteration: number;
+    /** Present for `'absence'` only — what the search was for. */
+    readonly lookedFor?: string;
+    /**
+     * The period the declaration said its read covered, in the record's
+     * camelCase form (honesty step 7b) — present only when the envelope declared
+     * a well-formed one. A described result with a period and no coverage lists
+     * files a `'ledger'` row whose three lists are empty.
+     */
+    readonly period?: DeclaredPeriod;
+    /**
+     * What the call found still running — its outcome not known yet — as the
+     * `coverage()` declared it (copied item by item; `short` and `count` when
+     * valid). Present only on a `'ledger'` row whose envelope declared a
+     * well-formed, non-empty `in_progress`.
+     */
+    readonly inProgress?: readonly InProgressItem[];
+}

package/dist/esm/semantics/coverage/types.js

@@ -0,0 +1,18 @@
+/**
+ * coverage/types — the shared vocabulary of the two coverage primitives.
+ *
+ * Pattern: one value type, two consumers — `absent()` says "I looked HERE and
+ *          found nothing", `coverage()` says "my answer covers THIS and not
+ *          THAT". Both are statements about the same thing: the ground a
+ *          result stands on. Spelling them with one vocabulary is what lets
+ *          the answer-level block merge an absence's boundary with a
+ *          verdict's without translating between two grammars.
+ * Role:    core/ layer, pure data. No behavior; TYPE-only imports (they erase
+ *          at runtime): the one period shape (`period.ts`) and the one
+ *          provenance shape `describedResult()` already declares
+ *          (`semantics/types.ts`), so an absence says its source and time
+ *          in the same words a described result does.
+ * Emits:   N/A.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/esm/semantics/coverage/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/semantics/coverage/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}