agentfootprint 9.128.1 → 9.131.0

package/dist/types/artifacts/timeAxis.d.ts

@@ -1,115 +0,0 @@
-/**
- * artifacts/timeAxis — a dataset's TIME AXIS, declared by its producer.
- *
- * 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; `bucket` is a timestamp or a label; `'2026-09-14T10:00:00'` is UTC or
- * the collector's wall clock. A viewer that guesses draws some series and
- * leaves the rest as tables — and a guess that is right most of the time is
- * a guess nobody notices is wrong.
- *
- * So the producer SAYS it, on the ticket (`PutArtifactInput.timeAxis`, carried
- * on `ArtifactMeta.timeAxis`): which column is time, how its values are
- * written, the zone when they are wall-clock, and how each row summarises its
- * interval. A consumer that honours a declaration draws a time series without
- * guessing and says what the points ARE ({@link describeTimeAxis} — "hourly
- * avg and max"); an undeclared dataset keeps whatever heuristic the consumer
- * had.
- *
- * ── The law: declared, never repaired ───────────────────────────────────────
- * A malformed declaration is REFUSED at mint ({@link timeAxisIssues} is the
- * one judge, asked by `prepareArtifact` and by `stageDatasetArtifacts` before
- * its first write) — never trimmed, defaulted or half-kept. A declaration a
- * store had "fixed" would be a promise the producer never made. The shape is
- * CLOSED: an unknown key is refused by name, because a misspelt `agg` that
- * was silently dropped would draw raw samples under a title claiming a
- * summary nobody declared.
- *
- * What the declaration does NOT promise: that the column is present in every
- * row, or that its values parse. The ticket is metadata; the rows are the
- * payload, and the store never scans a payload to judge its description. A
- * consumer that finds the declared column missing says so, visibly — the
- * declaration is what makes that absence a finding instead of a table.
- *
- * Pure and dependency-free: the browser half of an app imports it to read the
- * same declaration the server minted.
- */
-/** 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 (`'Europe/London'`) the values are WALL-CLOCK in. `'iso'`
-     *  only — an epoch is an instant and has no zone to declare. Absent: the
-     *  ISO strings carry their own offset (or are UTC). */
-    readonly zone?: string;
-    /** Width of the interval one row stands for: a positive integer and one of
-     *  `s m h d w` (`'30s'`, `'5m'`, `'1h'`, `'1d'`, `'1w'`). 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.
- */
-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;
-//# sourceMappingURL=timeAxis.d.ts.map

package/dist/types/artifacts/timeAxis.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"timeAxis.d.ts","sourceRoot":"","sources":["../../../src/artifacts/timeAxis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,SAAS,GAAG,UAAU,CAAC;AAE1D,yDAAyD;AACzD,MAAM,MAAM,iBAAiB,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjF,6EAA6E;AAC7E,eAAO,MAAM,eAAe,EAAE,SAAS,YAAY,EAAmC,CAAC;AACvF,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAO5D,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,kCAAkC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;0DACsD;IACtD,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;2DAEuD;IACvD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;yDAEqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,GAAG,iBAAiB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;CAC9F;AAsBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CA2EvD;AAED;;4DAE4D;AAC5D,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEzE;0DAC0D;AAC1D,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,eAAe,CAO3D;AAoCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAU1E"}