agentfootprint 10.2.0 → 10.3.1

package/dist/esm/core/time/ask.d.ts

@@ -1,126 +0,0 @@
-/**
- * core/time/ask — the one time ask (time design § 6): what a time field's
- * answer must be, why one is refused, and the choices a reading offers.
- *
- * Pattern: one judge per boundary (the `range.ts` precedent). A typed ask's
- *          `InputField.format` (`core/inputRequest.ts`) names what the answer
- *          is; {@link checkTimeAnswer} is the ONE judge of it — at definition
- *          (a choice, a supplied value) and at the resume door (the person's
- *          answer). A refusal is a CODE with its facts; the sentence is a
- *          catalog entry (`src/locales/timeAsk.ts` · `defaultTimeAskMessages`)
- *          the app may override (`.time({ messages })`), filled here
- *          ({@link refusalReason}) — the library writes a reason only for a
- *          check the app armed by declaring the field (TQ7).
- * Role:    core/ leaf (the time layer). Imports `instant.ts`, `zone.ts`,
- *          `range.ts`, `present.ts` and the row / candidate TYPES only.
- * Emits:   N/A.
- *
- * ## What an answer must be (§ 6.1, § 6.2)
- *
- * | `format` | The answer | Refused as |
- * |----------|------------|------------|
- * | `instant` | an ISO 8601 date-time WITH its offset, strict profile (`2026-10-09T08:00-07:00`) | `not-an-instant`; `no-offset` (a date-time with no zone); `dst-gap` |
- * | `time-range` | an ISO 8601 interval `from/to` of two such instants, `from` before `to` | `not-a-range`; either end's refusal; `out-of-order` |
- * | `zone` | an IANA zone name (`America/Los_Angeles`) — never an abbreviation or a bare offset | `not-a-zone` |
- * | `time-range`, for a tool's period | the same, inside the tool's declared facts | `time-future`; `time-past`; `beyond-retention`; `over-max-range` |
- *
- * A `time-range` answer given for a tool's period is also judged against the
- * tool's declared FACTS (§ 6.2, step T5a — `convert.ts` ·
- * `periodFactProblem`), when the caller hands them with the turn's clock:
- * `time-future` (a `past` source asked for a window after now), `time-past`
- * (a `future` source asked for one that ended), `beyond-retention` (the WHOLE
- * window older than the source keeps — a partial overlap is taken) and
- * `over-max-range` (wider than the source reads at once).
- *
- * `dst-gap` is asked only when the ask knows the person's zone (the run
- * clock's, under `.time()`): a wall time that zone's clocks skip, written with
- * one of the two offsets around the change (`2026-03-08T02:30-08:00` in Los
- * Angeles) names an instant nobody's clock showed. An instant written in some
- * other offset is that instant, and is taken.
- *
- * ## The choices a reading offers (§ 6.1, § 6.3)
- *
- * `readingAsk.ts` · `timeAskOf` (split out: it renders labels through
- * `present.ts`, which only an armed agent loads) turns a `time-reading` row whose choice is `open` into one
- * field: a `format: 'zone'` field when the person named a zone the layer
- * cannot read (`PST`), else a `format: 'time-range'` field whose `enum` is
- * the candidates left (each an ISO interval) and whose `labels` render each in
- * the reader's locale, the zone named, with the end the person said. A
- * `kind: 'model'` reader's window is offered as the LIBRARY'S reading to
- * confirm ("I read “yesterday” as … — is that right?"), never as the person's
- * words (§ 5.5). So is EVERY `rule` reading (the owner's decision "Always
- * confirm", time design TQ29 — `rowsBuild.ts` · `timeReadingRows`): the choice is
- * the reading pre-filled WITH ITS ZONE ("I read “yesterday” as Thu, Oct 8,
- * 2026, PDT in America/Los_Angeles — is that right?"), so a person who meant
- * another zone's day corrects it in one answer. Free entry stays open: a
- * field is `strict` only when the app says so.
- *
- * @example
- * ```ts
- * checkTimeAnswer('time-range', '2026-10-09T08:40-07:00/2026-10-09T08:00-07:00');
- * // { problem: 'out-of-order', facts: { from: '2026-10-09T08:40-07:00', to: '2026-10-09T08:00-07:00' } }
- * checkTimeAnswer('instant', '2026-10-09T08:00'); // { problem: 'no-offset', facts: { value: '2026-10-09T08:00' } }
- * checkTimeAnswer('instant', '2026-03-08T02:30-08:00', 'America/Los_Angeles'); // { problem: 'dst-gap', … }
- * checkTimeAnswer('zone', 'PST'); // { problem: 'not-a-zone', facts: { value: 'PST' } }
- * refusalReason([checkTimeAnswer('zone', 'PST')!], defaultTimeAskMessages);
- * // '“PST” is not a time zone name. Name one such as America/Los_Angeles.'
- * ```
- */
-import { type PeriodFacts } from './periodForm.js';
-import { type InstantText } from './instant.js';
-import { type ZoneName } from './zone.js';
-/** What a time field's answer is (time design § 6.1). The value stays a string on the wire. */
-export type TimeFormat = 'instant' | 'time-range' | 'zone';
-export declare const TIME_FORMATS: readonly TimeFormat[];
-/** Whether `value` names a {@link TimeFormat}. */
-export declare function isTimeFormat(value: unknown): value is TimeFormat;
-/** Why a time answer was refused — a code; the sentence is the catalog's. */
-export type TimeAnswerProblem = 'not-an-instant' | 'no-offset' | 'not-a-range' | 'out-of-order' | 'dst-gap' | 'not-a-zone' | 'time-future' | 'time-past' | 'beyond-retention' | 'over-max-range';
-/** One refused answer: the code and the facts its sentence names (the value as given, capped). */
-export interface TimeAnswerRefusal {
-    readonly problem: TimeAnswerProblem;
-    readonly facts: Readonly<Record<string, string>>;
-}
-export declare const quoted: (value: string) => string;
-/** A tool's declared facts and the turn's clock — what a `time-range` answer for that tool's period is judged against. */
-export interface ToolTimeFacts {
-    readonly facts: PeriodFacts;
-    readonly now: InstantText;
-}
-/**
- * Why `value` is not a well-formed answer of `format`, or `undefined` when it
- * is one. `zone` — the person's zone, when the ask knows it (the run clock's)
- * — arms the DST-gap check; without it the answer is judged for shape, order
- * and offset only. `tool` — a tool's declared facts and the clock — judges a
- * well-formed `time-range` against them too.
- */
-export declare function checkTimeAnswer(format: TimeFormat, value: string, zone?: ZoneName, tool?: ToolTimeFacts): TimeAnswerRefusal | undefined;
-/**
- * Every sentence the time ask can put before a person — the keys of the
- * catalog (`src/locales/timeAsk.ts`). `answer.*` is a refusal's reason, one
- * per {@link TimeAnswerProblem}; `ask.*` a question; `choice.confirm` the
- * label on a reading to confirm — every reading the armed reader made.
- * Placeholders are `{{name}}`; the label also takes `zone`.
- */
-export declare const TIME_ASK_MESSAGE_KEYS: readonly ["answer.not-an-instant", "answer.no-offset", "answer.not-a-range", "answer.out-of-order", "answer.dst-gap", "answer.not-a-zone", "answer.time-future", "answer.time-past", "answer.beyond-retention", "answer.over-max-range", "ask.which", "ask.confirm", "ask.zone", "ask.zone-unknown", "choice.confirm"];
-export type TimeAskMessageKey = (typeof TIME_ASK_MESSAGE_KEYS)[number];
-/** A whole catalog: one sentence per key. */
-export type TimeAskMessages = Readonly<Record<TimeAskMessageKey, string>>;
-/**
- * The app's overrides (`.time({ messages })`) read — every key one the
- * catalog has, every value a non-blank sentence of at most 4096 characters —
- * or a problem in words.
- */
-export declare function readTimeAskMessages(value: unknown): {
-    readonly value: Partial<TimeAskMessages>;
-} | {
-    readonly problem: string;
-};
-/** A catalog sentence with its `{{name}}` placeholders filled; a placeholder with no fact is left as written. */
-export declare function fillMessage(template: string, facts: Readonly<Record<string, string>>): string;
-/**
- * The reason a re-ask carries (`InputRefusal.reason`): one catalog sentence
- * per refused field, in field order, joined by a space — at most 4096
- * characters, the refusal's own bound.
- */
-export declare function refusalReason(refusals: readonly TimeAnswerRefusal[], messages: TimeAskMessages): string;

package/dist/esm/core/time/ask.js

@@ -1,231 +0,0 @@
-/**
- * core/time/ask — the one time ask (time design § 6): what a time field's
- * answer must be, why one is refused, and the choices a reading offers.
- *
- * Pattern: one judge per boundary (the `range.ts` precedent). A typed ask's
- *          `InputField.format` (`core/inputRequest.ts`) names what the answer
- *          is; {@link checkTimeAnswer} is the ONE judge of it — at definition
- *          (a choice, a supplied value) and at the resume door (the person's
- *          answer). A refusal is a CODE with its facts; the sentence is a
- *          catalog entry (`src/locales/timeAsk.ts` · `defaultTimeAskMessages`)
- *          the app may override (`.time({ messages })`), filled here
- *          ({@link refusalReason}) — the library writes a reason only for a
- *          check the app armed by declaring the field (TQ7).
- * Role:    core/ leaf (the time layer). Imports `instant.ts`, `zone.ts`,
- *          `range.ts`, `present.ts` and the row / candidate TYPES only.
- * Emits:   N/A.
- *
- * ## What an answer must be (§ 6.1, § 6.2)
- *
- * | `format` | The answer | Refused as |
- * |----------|------------|------------|
- * | `instant` | an ISO 8601 date-time WITH its offset, strict profile (`2026-10-09T08:00-07:00`) | `not-an-instant`; `no-offset` (a date-time with no zone); `dst-gap` |
- * | `time-range` | an ISO 8601 interval `from/to` of two such instants, `from` before `to` | `not-a-range`; either end's refusal; `out-of-order` |
- * | `zone` | an IANA zone name (`America/Los_Angeles`) — never an abbreviation or a bare offset | `not-a-zone` |
- * | `time-range`, for a tool's period | the same, inside the tool's declared facts | `time-future`; `time-past`; `beyond-retention`; `over-max-range` |
- *
- * A `time-range` answer given for a tool's period is also judged against the
- * tool's declared FACTS (§ 6.2, step T5a — `convert.ts` ·
- * `periodFactProblem`), when the caller hands them with the turn's clock:
- * `time-future` (a `past` source asked for a window after now), `time-past`
- * (a `future` source asked for one that ended), `beyond-retention` (the WHOLE
- * window older than the source keeps — a partial overlap is taken) and
- * `over-max-range` (wider than the source reads at once).
- *
- * `dst-gap` is asked only when the ask knows the person's zone (the run
- * clock's, under `.time()`): a wall time that zone's clocks skip, written with
- * one of the two offsets around the change (`2026-03-08T02:30-08:00` in Los
- * Angeles) names an instant nobody's clock showed. An instant written in some
- * other offset is that instant, and is taken.
- *
- * ## The choices a reading offers (§ 6.1, § 6.3)
- *
- * `readingAsk.ts` · `timeAskOf` (split out: it renders labels through
- * `present.ts`, which only an armed agent loads) turns a `time-reading` row whose choice is `open` into one
- * field: a `format: 'zone'` field when the person named a zone the layer
- * cannot read (`PST`), else a `format: 'time-range'` field whose `enum` is
- * the candidates left (each an ISO interval) and whose `labels` render each in
- * the reader's locale, the zone named, with the end the person said. A
- * `kind: 'model'` reader's window is offered as the LIBRARY'S reading to
- * confirm ("I read “yesterday” as … — is that right?"), never as the person's
- * words (§ 5.5). So is EVERY `rule` reading (the owner's decision "Always
- * confirm", time design TQ29 — `rowsBuild.ts` · `timeReadingRows`): the choice is
- * the reading pre-filled WITH ITS ZONE ("I read “yesterday” as Thu, Oct 8,
- * 2026, PDT in America/Los_Angeles — is that right?"), so a person who meant
- * another zone's day corrects it in one answer. Free entry stays open: a
- * field is `strict` only when the app says so.
- *
- * @example
- * ```ts
- * checkTimeAnswer('time-range', '2026-10-09T08:40-07:00/2026-10-09T08:00-07:00');
- * // { problem: 'out-of-order', facts: { from: '2026-10-09T08:40-07:00', to: '2026-10-09T08:00-07:00' } }
- * checkTimeAnswer('instant', '2026-10-09T08:00'); // { problem: 'no-offset', facts: { value: '2026-10-09T08:00' } }
- * checkTimeAnswer('instant', '2026-03-08T02:30-08:00', 'America/Los_Angeles'); // { problem: 'dst-gap', … }
- * checkTimeAnswer('zone', 'PST'); // { problem: 'not-a-zone', facts: { value: 'PST' } }
- * refusalReason([checkTimeAnswer('zone', 'PST')!], defaultTimeAskMessages);
- * // '“PST” is not a time zone name. Name one such as America/Los_Angeles.'
- * ```
- */
-import { periodFactProblem } from './periodForm.js';
-import { compareInstants, instantOf, utcWallMs } from './instant.js';
-import { isZoneName, readWall } from './zone.js';
-export const TIME_FORMATS = Object.freeze(['instant', 'time-range', 'zone']);
-/** Whether `value` names a {@link TimeFormat}. */
-export function isTimeFormat(value) {
-    return TIME_FORMATS.includes(value);
-}
-/** A date-time a person wrote with no offset: it could be any zone's. */
-const NO_OFFSET = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?$/;
-const WALL = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?/;
-/** A quoted value in a sentence is cut here: a reason names the answer, it does not repeat an essay. */
-const QUOTE_CHARS = 64;
-export const quoted = (value) => value.length <= QUOTE_CHARS ? value : `${value.slice(0, QUOTE_CHARS - 1)}…`;
-/**
- * Whether `value` writes a wall time the clocks of `zone` skip, with one of
- * the two offsets around that change — an instant no clock in the zone showed.
- */
-function inDstGap(value, offsetMinutes, zone) {
-    const m = WALL.exec(value);
-    if (m === null)
-        return false;
-    const [year, month, day, hour, minute] = [m[1], m[2], m[3], m[4], m[5]].map(Number);
-    const second = m[6] === undefined ? 0 : Number(m[6]);
-    const reading = readWall({ year, month, day, hour, minute, second }, zone);
-    if (reading.kind !== 'gap')
-        return false;
-    const wall = utcWallMs(year, month, day, hour, minute, second);
-    const offsetMs = offsetMinutes * 60_000;
-    // `readWall` names the gap's two readings: `earlier` with the offset AFTER the change, `later` with the one before.
-    return offsetMs === wall - reading.earlier || offsetMs === wall - reading.later;
-}
-function checkInstant(value, zone) {
-    const instant = instantOf(value, 'strict');
-    if (instant === undefined) {
-        return {
-            problem: NO_OFFSET.test(value) ? 'no-offset' : 'not-an-instant',
-            facts: { value: quoted(value) },
-        };
-    }
-    if (zone !== undefined && inDstGap(value, instant.offsetMinutes, zone)) {
-        return {
-            problem: 'dst-gap',
-            facts: { value: quoted(value), wall: value.slice(0, 16).replace('T', ' '), zone },
-        };
-    }
-    return undefined;
-}
-/**
- * Why `value` is not a well-formed answer of `format`, or `undefined` when it
- * is one. `zone` — the person's zone, when the ask knows it (the run clock's)
- * — arms the DST-gap check; without it the answer is judged for shape, order
- * and offset only. `tool` — a tool's declared facts and the clock — judges a
- * well-formed `time-range` against them too.
- */
-export function checkTimeAnswer(format, value, zone, tool) {
-    const known = zone !== undefined && isZoneName(zone) ? zone : undefined;
-    switch (format) {
-        case 'zone':
-            return isZoneName(value)
-                ? undefined
-                : { problem: 'not-a-zone', facts: { value: quoted(value) } };
-        case 'instant':
-            return checkInstant(value, known);
-        case 'time-range': {
-            const halves = value.split('/');
-            if (halves.length !== 2)
-                return { problem: 'not-a-range', facts: { value: quoted(value) } };
-            const [from, to] = halves;
-            const refused = checkInstant(from, known) ?? checkInstant(to, known);
-            if (refused !== undefined)
-                return refused;
-            const a = instantOf(from, 'strict');
-            const b = instantOf(to, 'strict');
-            if (a === undefined || b === undefined || compareInstants(a, b) >= 0) {
-                return { problem: 'out-of-order', facts: { from: quoted(from), to: quoted(to) } };
-            }
-            if (tool === undefined)
-                return undefined;
-            const problem = periodFactProblem({ from, to }, tool.facts, tool.now);
-            if (problem === undefined)
-                return undefined;
-            return {
-                problem,
-                facts: {
-                    from: quoted(from),
-                    to: quoted(to),
-                    ...(tool.facts.retention !== undefined && { retention: tool.facts.retention }),
-                    ...(tool.facts.maxRange !== undefined && { maxRange: tool.facts.maxRange }),
-                },
-            };
-        }
-    }
-}
-// ─── The catalog ─────────────────────────────────────────────────────────
-/**
- * Every sentence the time ask can put before a person — the keys of the
- * catalog (`src/locales/timeAsk.ts`). `answer.*` is a refusal's reason, one
- * per {@link TimeAnswerProblem}; `ask.*` a question; `choice.confirm` the
- * label on a reading to confirm — every reading the armed reader made.
- * Placeholders are `{{name}}`; the label also takes `zone`.
- */
-export const TIME_ASK_MESSAGE_KEYS = Object.freeze([
-    'answer.not-an-instant',
-    'answer.no-offset',
-    'answer.not-a-range',
-    'answer.out-of-order',
-    'answer.dst-gap',
-    'answer.not-a-zone',
-    'answer.time-future',
-    'answer.time-past',
-    'answer.beyond-retention',
-    'answer.over-max-range',
-    'ask.which',
-    'ask.confirm',
-    'ask.zone',
-    'ask.zone-unknown',
-    'choice.confirm',
-]);
-const MAX_SENTENCE = 4096;
-/**
- * The app's overrides (`.time({ messages })`) read — every key one the
- * catalog has, every value a non-blank sentence of at most 4096 characters —
- * or a problem in words.
- */
-export function readTimeAskMessages(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        return { problem: 'messages must be an object of catalog key → sentence' };
-    }
-    const out = {};
-    for (const [key, sentence] of Object.entries(value)) {
-        if (!TIME_ASK_MESSAGE_KEYS.includes(key)) {
-            return {
-                problem: `messages has no key '${key}' — the keys are ${TIME_ASK_MESSAGE_KEYS.join(', ')}`,
-            };
-        }
-        if (typeof sentence !== 'string' ||
-            sentence.trim().length === 0 ||
-            sentence.length > MAX_SENTENCE) {
-            return {
-                problem: `messages['${key}'] must be a non-blank sentence of at most ${MAX_SENTENCE} characters`,
-            };
-        }
-        out[key] = sentence;
-    }
-    return { value: out };
-}
-/** A catalog sentence with its `{{name}}` placeholders filled; a placeholder with no fact is left as written. */
-export function fillMessage(template, facts) {
-    return template.replace(/\{\{(\w+)\}\}/g, (whole, name) => Object.prototype.hasOwnProperty.call(facts, name) ? facts[name] : whole);
-}
-/**
- * The reason a re-ask carries (`InputRefusal.reason`): one catalog sentence
- * per refused field, in field order, joined by a space — at most 4096
- * characters, the refusal's own bound.
- */
-export function refusalReason(refusals, messages) {
-    const reason = refusals
-        .map((r) => fillMessage(messages[`answer.${r.problem}`], r.facts))
-        .join(' ');
-    return reason.length <= MAX_SENTENCE ? reason : `${reason.slice(0, MAX_SENTENCE - 1)}…`;
-}
-//# sourceMappingURL=ask.js.map

package/dist/esm/core/time/ask.js.map

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

package/dist/esm/core/time/axis.d.ts

@@ -1,224 +0,0 @@
-/**
- * core/time/axis — a dataset's TIME AXIS: the declaration, its one judge, and
- * the read-side view that turns the declared column into comparable instants.
- *
- * Pattern: declared, never guessed; judged at mint, never repaired; values
- *          read through ONE view ({@link normaliseInstants}) that never
- *          touches the stored rows. Moved here from `artifacts/timeAxis.ts`
- *          (which `artifacts/index.ts` still re-exports), so the axis speaks
- *          the time layer's one grammar: `interval` is a `duration.ts`
- *          duration under {@link AXIS_UNITS}, `zone` is a `zone.ts` zone name.
- * Role:    core/ leaf (the time layer's one owner). Imports `instant.ts`,
- *          `duration.ts` and `zone.ts`. Asked by `artifacts/minting.ts` ·
- *          `prepareArtifact` and `artifacts/datasetResult.ts` ·
- *          `stageDatasetArtifacts` (the judge), and by any consumer that
- *          compares a dataset's times (the view).
- * Emits:   N/A.
- *
- * ## Why a producer declares it
- *
- * A table of rows is a time series only when one column IS time, and the
- * reader of the rows cannot know that honestly: `ts` holding 1726000000 is
- * epoch SECONDS to the tool that wrote it and a large integer to everything
- * else; `'2026-09-14T10:00:00'` is UTC or the collector's wall clock. So the
- * producer SAYS it, on the ticket (`PutArtifactInput.timeAxis`, carried on
- * `ArtifactMeta.timeAxis`). A malformed declaration is REFUSED at mint
- * ({@link timeAxisIssues}) — never trimmed or defaulted — and the shape is
- * CLOSED: a misspelt `agg` is refused by name, never dropped.
- *
- * ## The view — values, not the declaration
- *
- * The judge never reads a value; {@link normaliseInstants} does, at read time.
- * It turns the declared column into UTC `Z` instants spelled at ONE precision,
- * so a lexicographic compare downstream is chronological, and it is honest
- * about every value it could not place:
- *
- * | Value | Under | Read as |
- * |-------|-------|---------|
- * | a number | `epoch-s` / `epoch-ms` | that instant, exactly as written (no float rounding) |
- * | ISO with `Z` or `±HH:MM` | `iso`, any zone | that instant (the lenient profile — a producer's spelling) |
- * | ISO with NO offset | `iso`, no `zone` | **naive** — counted, never read as UTC; `status: 'naive-values'`, or refused under `naive: 'refuse'` |
- * | ISO with no offset | `iso` + `zone` | a wall time in that zone; one instant, or — in a fall-back overlap — the row-order rule below; in a spring-forward gap, counted `dstGap` |
- * | anything else | — | counted `unreadable` (`missing` when the row lacks the column) |
- *
- * **The fall-back rule.** In the hour the clocks go back, one wall time names
- * two instants. Read in the rows' order, the values before the wall clock
- * steps back take the earlier offset and those from the step on the later
- * (a note `{ kind: 'dst-overlap', resolvedBy: 'row-order' }` per value). When
- * the order cannot tell — a lone `01:30`, no step back, two steps back, or a
- * column whose wall times are not in order anywhere — the value is counted
- * `dstAmbiguous` and handled like a naive one. Nothing is picked silently.
- *
- * @example
- * ```ts
- * timeAxisIssues({ column: 'ts', unit: 'epoch-s', zone: 'UTC' }); // ['timeAxis.zone is for wall-clock ISO values; …']
- * normaliseInstants([{ ts: 1726300800 }, { ts: 1726304400.5 }], { column: 'ts', unit: 'epoch-s' });
- * // { status: 'instants', precision: 'millisecond',
- * //   points: [{ row: 0, at: '2024-09-14T08:00:00.000Z' }, { row: 1, at: '2024-09-14T09:00:00.500Z' }], … }
- * normaliseInstants([{ t: '2026-09-14T10:00:00' }], { column: 't', unit: 'iso' });
- * // { status: 'naive-values', count: 1, points: [], … } — never read as UTC
- * ```
- */
-import { type InstantText } from './instant.js';
-/** How the time column's values are written. */
-export type TimeAxisUnit = 'iso' | 'epoch-s' | 'epoch-ms';
-/** How one row summarises the interval it stands for. */
-export type TimeAxisAggregate = 'avg' | 'min' | 'max' | 'sum' | 'count' | 'last';
-/** The closed sets, in one place, for the judge and for its own messages. */
-export declare const TIME_AXIS_UNITS: readonly TimeAxisUnit[];
-export declare const TIME_AXIS_AGGREGATES: readonly TimeAxisAggregate[];
-/**
- * A dataset's declared time axis.
- *
- * @example hourly buckets, two measures summarised differently
- *   { column: 'hour', unit: 'iso', interval: '1h',
- *     aggregate: { read_iops: 'avg', peak_iops: 'max' } }
- * @example raw samples every five minutes, epoch seconds
- *   { column: 'ts', unit: 'epoch-s', interval: '5m', aggregate: 'raw' }
- */
-export interface DatasetTimeAxis {
-    /** The column that holds time. */
-    readonly column: string;
-    /** `'iso'` — ISO-8601 strings; `'epoch-s'` / `'epoch-ms'` — numbers since
-     *  1970-01-01T00:00:00Z in seconds / milliseconds. */
-    readonly unit: TimeAxisUnit;
-    /** IANA zone name (`'Europe/London'`) the values are WALL-CLOCK in — never
-     *  an abbreviation such as `'PST'` or a bare offset. `'iso'` only — an epoch
-     *  is an instant and has no zone to declare. Absent: every ISO value must
-     *  carry its own offset (`Z` or `±HH:MM`); a value without one is NEVER
-     *  read as UTC — {@link normaliseInstants} counts it (`naive-values`) or,
-     *  by the reader's choice, refuses the column. */
-    readonly zone?: string;
-    /** Width of the interval one row stands for: a positive whole number and
-     *  one of `s m h d w` (`'30s'`, `'5m'`, `'1h'`, `'1d'`, `'1w'`) — the time
-     *  layer's one duration grammar, any number of digits. With
-     *  `aggregate: 'raw'` it is the sampling cadence. */
-    readonly interval?: string;
-    /**
-     * How each row summarises its interval. `'raw'` — every row is a sample as
-     * collected, nothing was reduced. One aggregate — every measure column was
-     * reduced the same way. A record — measure column to its own aggregate
-     * (`{ avg_iops: 'avg', peak_iops: 'max' }`); a column not named there is
-     * not a declared measure. Any aggregate other than `'raw'` requires
-     * `interval`, and `interval` requires `aggregate`: a summary of an interval
-     * nobody named, or an interval with no word for what happened in it, is
-     * half a declaration.
-     */
-    readonly aggregate?: 'raw' | TimeAxisAggregate | Readonly<Record<string, TimeAxisAggregate>>;
-}
-/**
- * THE ONE JUDGE of a time-axis declaration. Returns every problem, in words a
- * producer can act on; an empty list means the declaration is well-formed.
- * Never throws, never repairs, never reads a value.
- */
-export declare function timeAxisIssues(value: unknown): string[];
-/** What a consumer finds on a ticket. `malformed` exists for tickets minted
- *  outside this library's put (a foreign writer, an old store) — a consumer
- *  shows it as an error, never as an undeclared dataset. */
-export type TimeAxisReading = {
-    readonly status: 'absent';
-} | {
-    readonly status: 'declared';
-    readonly axis: DatasetTimeAxis;
-} | {
-    readonly status: 'malformed';
-    readonly issues: readonly string[];
-};
-/** Read the declaration off a ticket (`ArtifactMeta`, or anything shaped like
- *  one). Absent is absent; anything present is judged. */
-export declare function readTimeAxis(meta: unknown): TimeAxisReading;
-/**
- * The declared SUMMARY in words, for a chart title — the one wording every
- * consumer shares, so two screens never describe one ticket two ways.
- *
- *   `{ interval: '1h', aggregate: { a: 'avg', b: 'max' } }` → `'hourly avg and max'`
- *   `{ interval: '5m', aggregate: 'max' }`                 → `'5-minute max'`
- *   `{ interval: '5m', aggregate: 'raw' }`                 → `'raw samples every 5 minutes'`
- *   `{ aggregate: 'raw' }`                                 → `'raw samples'`
- *
- * `undefined` when the declaration says nothing about summarising (column and
- * unit only) — there is no summary to put in a title, and inventing "raw"
- * would claim something the producer did not.
- */
-export declare function describeTimeAxis(axis: DatasetTimeAxis): string | undefined;
-/** What {@link normaliseInstants} does with a naive value: count it (`'flag'`, the default) or refuse the column. */
-export type NaiveValues = 'flag' | 'refuse';
-/** Options of {@link normaliseInstants}. */
-export interface NormaliseOptions {
-    /** A value whose clock is unknown (naive, or a fall-back wall time the row
-     *  order cannot place): `'flag'` counts it and reads the rest; `'refuse'`
-     *  places nothing. Never read as UTC either way. Default `'flag'`. */
-    readonly naive?: NaiveValues;
-}
-/** The one precision every point of a view is spelled at: the finest any value was written in. */
-export type AxisPrecision = 'second' | 'millisecond' | 'nanosecond';
-/** One placed value: the row it came from and its UTC instant. */
-export interface AxisPoint {
-    /** The row's index in the rows as stored. */
-    readonly row: number;
-    /** The instant in UTC (`Z`), at the view's one precision — so comparing two
-     *  spellings as text compares them in time. */
-    readonly at: InstantText;
-}
-/** A value the fall-back overlap doubled, placed by the rows' order. */
-export interface AxisOverlapNote {
-    readonly kind: 'dst-overlap';
-    readonly resolvedBy: 'row-order';
-    readonly row: number;
-    /** Which of the two instants the wall time names: before the clock stepped back, or after. */
-    readonly which: 'earlier' | 'later';
-}
-/** Every value the view could not place, by reason. */
-export interface AxisCounts {
-    /** An ISO value with no offset under an axis with no `zone`. */
-    readonly naive: number;
-    /** A wall time the fall-back doubles, where the rows' order cannot tell which. */
-    readonly dstAmbiguous: number;
-    /** A wall time the spring-forward skips — it names no instant. */
-    readonly dstGap: number;
-    /** Present, but not a value of the declared unit (or outside years 0000–9999). */
-    readonly unreadable: number;
-    /** The row lacks the column, holds `null`, or is not a record. */
-    readonly missing: number;
-}
-/**
- * The read-side view of a declared time column.
- *
- * - `instants` — every value whose clock is known was placed.
- * - `naive-values` — `count` values have no known clock (`naive` +
- *   `dstAmbiguous`); they are not in `points`, and nothing should compare or
- *   join the series with another source as if they were.
- * - `refused` — the same, under `naive: 'refuse'`: nothing is placed.
- *
- * `points` are sorted in time (ties by row); `unreadable`, `missing` and
- * `dstGap` are counted under every status.
- */
-export type NormalisedAxis = {
-    readonly status: 'instants';
-    readonly points: readonly AxisPoint[];
-    readonly precision: AxisPrecision;
-    readonly notes: readonly AxisOverlapNote[];
-    readonly counts: AxisCounts;
-} | {
-    readonly status: 'naive-values';
-    readonly count: number;
-    readonly points: readonly AxisPoint[];
-    readonly precision: AxisPrecision;
-    readonly notes: readonly AxisOverlapNote[];
-    readonly counts: AxisCounts;
-} | {
-    readonly status: 'refused';
-    readonly reason: 'naive-values';
-    readonly count: number;
-    readonly counts: AxisCounts;
-};
-/**
- * THE READ-SIDE VIEW of a declared time column: every value turned into a UTC
- * `Z` instant at one precision, sorted in time, with every value it could not
- * place counted by reason (the module table). The rows are only read — never
- * copied into, reordered or rewritten — so the stored bytes are unchanged.
- *
- * A malformed `axis` throws a `TypeError` naming its issues (read a ticket
- * with `readTimeAxis` first; a declaration is never repaired).
- */
-export declare function normaliseInstants(rows: readonly unknown[], axis: DatasetTimeAxis, options?: NormaliseOptions): NormalisedAxis;