agentfootprint 10.3.0 → 10.3.1

package/dist/esm/semantics/described.js

@@ -0,0 +1,229 @@
+/**
+ * semantics/described — `describedResult()`, the declaration door spelled the
+ * way code is written.
+ *
+ * Pattern: one core, one authoring door (`envelope.ts` · `mintSemantics`). This file
+ *          is the camelCase door: it says how its author spells the
+ *          declaration and respells each object to the wire. It judges
+ *          nothing itself — every rule lives in the core, once.
+ * Role:    lib/ layer, pure.
+ * Emits:   N/A (the caller emits `agentfootprint.tools.semantics_declared`).
+ *
+ * ## One authoring spelling, one unchanged wire
+ *
+ * `semantic()` copied the wire's snake_case names into its declaration
+ * (`measured_at`, `is_counter`, `filter_note`) beside camelCase ones
+ * (`notChecked`, `cannotCover`), so an author wrote two spellings in one
+ * object — and "semantic" already means vector retrieval everywhere else in
+ * this library. `describedResult()` takes the same fields in camelCase and
+ * mints the same wire, byte for byte. The wire does not change: the model and
+ * any foreign process keep reading snake_case.
+ *
+ * The authoring door takes ONE spelling and refuses snake_case, quoting the key its
+ * author wrote and naming the one meant (`provenance.measured_at` → "did you
+ * mean `measuredAt`?"). A migration that swaps only the function name then
+ * fails loudly at the line that needs the new spelling, instead of silently
+ * minting without it. The declaration never accepts both spellings in one object.
+ */
+import { COVERAGE_DECLARATION_KEYS } from './coverage/items.js';
+import { refusal, refuseUnknownKeys } from './coverage/refusal.js';
+import { CLARIFY_DECLARATION_KEYS, mintSemantics, provenanceIssues, WIRE_SPELLING, } from './envelope.js';
+/**
+ * Each declared key → its wire key, per object, tied to the types in BOTH
+ * directions: a declared key with no wire name, or a wire name the wire type
+ * does not have, fails to compile. The order is the order a refusal lists the
+ * fields in.
+ */
+const GRAIN_NAMES = {
+    interval: 'interval',
+    aggregation: 'aggregation',
+    isCounter: 'is_counter',
+    collapsed: 'collapsed',
+};
+const PROVENANCE_NAMES = {
+    measuredAt: 'measured_at',
+    ageSeconds: 'age_seconds',
+    source: 'source',
+    sourceExportDate: 'source_export_date',
+};
+const RENDER_NAMES = {
+    default: 'default',
+    columns: 'columns',
+    sort: 'sort',
+    filterNote: 'filter_note',
+    chartHint: 'chart_hint',
+};
+const WIRE_NAMES = {
+    grain: GRAIN_NAMES,
+    provenance: PROVENANCE_NAMES,
+    render: RENDER_NAMES,
+};
+/**
+ * How this door's author spells the six snake_case wire fields — each value
+ * checked against the tables above, so a renamed declared key that is not
+ * renamed here fails to compile instead of naming a field nobody wrote.
+ */
+const CAMEL_SPELLING = {
+    is_counter: 'isCounter',
+    measured_at: 'measuredAt',
+    age_seconds: 'ageSeconds',
+    source_export_date: 'sourceExportDate',
+    filter_note: 'filterNote',
+    chart_hint: 'chartHint',
+};
+/**
+ * The nine top-level fields, tied to the type in both directions.
+ */
+const DECLARATION_KEYS = Object.keys({
+    series: true,
+    facts: true,
+    edges: true,
+    grain: true,
+    provenance: true,
+    period: true,
+    coverage: true,
+    clarify: true,
+    render: true,
+});
+/**
+ * `value` with each key renamed to its wire name, in the author's key order.
+ * A value that is not a plain object is handed through untouched, so the rule
+ * set names it for what it is — "`provenance` must be an object ({ measuredAt,
+ * source, … })" — where a spread would have turned `null` into `{}` and a
+ * string into indexed characters. A plain object carries only known keys
+ * here: the door refused every other key first.
+ */
+function toWire(field, value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return value;
+    const names = WIRE_NAMES[field];
+    const declared = value;
+    const out = {};
+    // `Object.hasOwn`, never `names[key]` alone: a key such as `toString` would
+    // otherwise read a function off Object.prototype and rename to it.
+    for (const key of Object.keys(declared)) {
+        out[Object.hasOwn(names, key) ? names[key] : key] = declared[key];
+    }
+    return out;
+}
+const DESCRIBED_DOOR = {
+    name: 'describedResult',
+    declarationKeys: DECLARATION_KEYS,
+    derivedKeys: ['notCovered', 'not_covered'],
+    objectKeys: [
+        ['grain', Object.keys(GRAIN_NAMES)],
+        ['provenance', Object.keys(PROVENANCE_NAMES)],
+        ['coverage', COVERAGE_DECLARATION_KEYS],
+        ['clarify', CLARIFY_DECLARATION_KEYS],
+        ['render', Object.keys(RENDER_NAMES)],
+    ],
+    toWire,
+    spelling: CAMEL_SPELLING,
+};
+/**
+ * Mint an author's (camelCase) `provenance` into the wire's spelling by THIS
+ * door's rules — `absent()` asks it (honesty step 7b), so an absence says its
+ * source and time in the shape, the spelling and the rule set a described
+ * result does: `measuredAt` and `source` required, `ageSeconds` a finite
+ * number ≥ 0, `sourceExportDate` a non-empty string, a snake_case key refused
+ * naming the camelCase one. THROWS the refusal (`refused: …`) at the line the
+ * author wrote. A fresh object, keys in the author's order.
+ */
+export function mintProvenance(declared) {
+    if (typeof declared === 'object' && declared !== null && !Array.isArray(declared)) {
+        refuseUnknownKeys(declared, Object.keys(PROVENANCE_NAMES), 'provenance');
+    }
+    const wire = toWire('provenance', declared);
+    const [first] = provenanceIssues(wire, CAMEL_SPELLING);
+    if (first !== undefined)
+        throw refusal(`${first.message} (field: ${first.field})`);
+    return wire;
+}
+/**
+ * Read a WIRE provenance (an absence minted anywhere — a Python helper, an
+ * older process) into the record's camelCase form, by the same rule set —
+ * never repaired. `{}` when none is declared (`undefined` or `null`).
+ */
+export function readProvenance(wire) {
+    if (wire === undefined || wire === null)
+        return {};
+    const [problem] = provenanceIssues(wire, WIRE_SPELLING);
+    if (problem !== undefined)
+        return { problem };
+    const p = wire;
+    return {
+        provenance: {
+            measuredAt: p.measured_at,
+            source: p.source,
+            ...(p.age_seconds !== undefined && { ageSeconds: p.age_seconds }),
+            ...(p.source_export_date !== undefined && { sourceExportDate: p.source_export_date }),
+        },
+    };
+}
+/**
+ * Return rows, a series or relationships from a system of record — WITH the
+ * caveats that make them honest — in a shape the framework recognizes, the
+ * record keeps whole, and a build gate can refuse.
+ *
+ * **Where it lives.** It is the tool's RESPONSE: `execute` returns it, and
+ * nothing is added to the system prompt or the tool's schema. The model reads
+ * a compact projection ({@link semanticsForModel}: the data, `grain`,
+ * `provenance`, the `not_covered` lines composed from `coverage`, a non-null
+ * `clarify` and a static note) — never the `checked` list, the `render` hints
+ * or the marker. The run record keeps the FULL envelope
+ * (`agentfootprint.tools.semantics_declared`), even when the result is over
+ * the tool's `resultCeiling` and refused. A declared `coverage` also flows
+ * through the channel `coverage()` uses, which is the only part that can reach
+ * the final answer (`.limitsTravelWithTheAnswer()`).
+ *
+ * **Values from the data.** `provenance.measuredAt` is when the WORLD was
+ * measured, taken from the data — the export's time, the moment of a live
+ * read, the newest sample of a series, the end of a window — never typed in.
+ * It is never parsed: the library passes your words through.
+ *
+ * **The period** (honesty step 7b). `period: { queried, held, readAt? }` says
+ * what time the READ covered — the instants it asked for, and what the store
+ * holds (or `'unknown'`) — as ISO 8601 instants with a zone. The model reads it
+ * as declared; the results layer compares the instants and files its verdict
+ * (covered · partly held · not held · unknown). A malformed period is refused
+ * here.
+ *
+ * Refuses (throws, at the call site — the `absent()` law) any declaration
+ * this vocabulary cannot honor: series without `grain`, series or facts
+ * without `provenance.measuredAt` and `provenance.source`, a counter-looking
+ * aggregation with `isCounter` unstated, and every malformed shape. Each
+ * refusal starts `refused: `, names the field as you spelled it, and — inside
+ * `execute` — is the call's error result, which the model reads in place of
+ * the data; the run continues. A snake_case key (`measured_at`,
+ * `not_checked`) is refused, naming the camelCase one.
+ *
+ * Use `absent()` when nothing matched and `coverage()` for
+ * any other value that has limits; never wrap one helper's result in another.
+ *
+ * @example rows from a nightly export — the time comes from the export
+ * ```ts
+ * const exportTime = snapshot.exportedAt; // when the WORLD was measured
+ * return describedResult({
+ *   facts: rows.map((r) => ({ entity: r.vm, datastore: r.datastore, size_tb: r.sizeTb })),
+ *   provenance: { measuredAt: exportTime, source: 'RVTools export' },
+ *   coverage: {
+ *     checked: [`every VM in the RVTools export of ${exportTime}`],
+ *     cannotCover: [{ what: 'hosts that are not VMware', why: 'RVTools sees VMware only' }],
+ *   },
+ * });
+ * ```
+ *
+ * @example a series — `measuredAt` is the newest sample
+ * ```ts
+ * const newest = rows.reduce((a, b) => (a.time > b.time ? a : b)).time;
+ * return describedResult({
+ *   series: rows.map((r) => ({ t: r.time, entity: r.port, metric: 'avg_iops', value: r.iops })),
+ *   grain: { interval: '30m', aggregation: 'avg', isCounter: false },
+ *   provenance: { measuredAt: newest, source: 'InfluxDB SwitchPortStats' },
+ * });
+ * ```
+ */
+export function describedResult(decl) {
+    return mintSemantics(decl, DESCRIBED_DOOR);
+}
+//# sourceMappingURL=described.js.map

package/dist/esm/semantics/described.js.map

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

package/dist/esm/semantics/envelope.d.ts

@@ -0,0 +1,195 @@
+/**
+ * semantics/envelope — minting, recognizing and projecting the semantic
+ * tool-result envelope (9.53.0).
+ *
+ * Pattern: minted by a helper, RECOGNIZED by the framework (the `absent()` /
+ *          tool-effects precedent). A return shape the framework does not
+ *          understand is a convention, and a convention cannot ride the
+ *          record, feed a UI, or be refused by a build gate.
+ * Role:    lib/ layer, pure. The dispatch loop calls `readSemantics` at the
+ *          execute boundary; `describedResult()` is what a tool author writes;
+ *          `checkSemantics` (check.ts) judges the same shapes offline.
+ * Emits:   N/A (the caller emits `agentfootprint.tools.semantics_declared`).
+ *
+ * ## Two views of one envelope — the design decision, stated
+ *
+ * The MODEL reads a compact, rendering-free projection
+ * ({@link semanticsForModel}): the data (`series`/`facts`/`edges`), the
+ * caveats that must travel with it (`grain`, `provenance`), the composed
+ * `not_covered` prose, a non-null `clarify`, and the static note. Dropped
+ * from the model's view: the `af_semantics` marker (machine-only), `render`
+ * (a UI hint — the tool never renders, and a model parroting rendering
+ * directives is noise), the three-list `coverage` detail (it rides the
+ * coverage channel and the record; the model reads the composed
+ * `not_covered` lines instead), and a `clarify: null` (a stated non-question
+ * is a fact for the record, not something the model acts on).
+ *
+ * The RECORD gets everything: the full envelope — render, coverage,
+ * marker and all — lands on the `tools.semantics_declared` event BEFORE the
+ * result ceiling is measured, so grain and provenance survive to recordings
+ * and UIs even when the content itself is refused as oversized. The
+ * `coverage` field is additionally declared through the SAME channel the
+ * `coverage()` primitive uses (`tools.coverage_declared`, tracked state, the
+ * final-answer limits block) — absorbed, never duplicated.
+ *
+ * ## One rule set for authoring and recognition
+ *
+ * The mint refuses a declaration this vocabulary cannot honor at the
+ * CALL SITE (the `absent()` law) — so a minted envelope is honest by
+ * construction: series carry their grain, data carries its provenance,
+ * counter-looking aggregations state `is_counter`. `semanticIssues()` judges
+ * the RENDERED shape — the same rules over a value somebody may have built
+ * by hand — and is what recognition and the `check:semantics` gate both
+ * stand on. Recognition is STRICT (the zero-cost guarantee): a marker-
+ * bearing value with any issue is NOT recognized — it keeps its bytes on
+ * the data path (dev-warned, and named field-by-field by the gate), because
+ * this library does not half-apply a shape it cannot fully honor.
+ *
+ * ## One authoring door, one unchanged wire
+ *
+ * `describedResult()` declares camelCase names, then `mintSemantics` applies
+ * the same rule set used to recognize stored snake_case envelopes. Validation
+ * and record reading keep one owner; old wire records never need an adapter.
+ */
+import { type DeclaredPeriod } from './coverage/period.js';
+import type { Coverage } from './coverage/types.js';
+import { type DescribedResultDeclaration, type SemanticCoverage, type ToolSemantics } from './types.js';
+/** The codes an envelope can be faulted with — shared by recognition (any
+ *  issue ⇒ not recognized) and the `check:semantics` gate (issues become
+ *  findings under these same names). */
+export type SemanticIssueCode = 'malformed-semantics' | 'series-without-grain' | 'counter-aggregation-unstated' | 'data-without-provenance';
+/** One fault, naming the field so a refusal can teach and a gate can point. */
+export interface SemanticIssue {
+    readonly code: SemanticIssueCode;
+    /** The offending / missing field, dot-pathed ('grain.is_counter'). */
+    readonly field: string;
+    readonly message: string;
+}
+/** Whole-token match against {@link COUNTER_AGGREGATION_WORDS}, singular or
+ *  plural, case-insensitive — 'sum' and 'Counts' look like counters,
+ *  'summary' does not. */
+export declare function isCounterLookingAggregation(aggregation: string): boolean;
+/**
+ * The keys a {@link SemanticClarify} has — spelled the same in declarations
+ * and recorded envelopes — tied to the type in BOTH directions.
+ */
+export declare const CLARIFY_DECLARATION_KEYS: readonly string[];
+/**
+ * The six fields whose WIRE name is snake_case — the only names a declaration
+ * door may spell differently. Everything else (`interval`, `source`,
+ * `default`, the data rows, the eight top-level fields) is one word on both
+ * sides.
+ */
+export type SpelledField = 'is_counter' | 'measured_at' | 'age_seconds' | 'source_export_date' | 'filter_note' | 'chart_hint';
+/** How one door's author spells each {@link SpelledField}. */
+export type Spelling = Readonly<Record<SpelledField, string>>;
+/** The wire's own spelling — what `semanticIssues`, recognition, the gate
+ *  speak. */
+export declare const WIRE_SPELLING: Spelling;
+/** The objects inside a declaration whose keys a door checks by name. */
+export type DeclaredObject = 'grain' | 'provenance' | 'coverage' | 'clarify' | 'render';
+/** The objects inside a declaration a door copies into their wire spelling. */
+export type RespelledObject = 'grain' | 'provenance' | 'render';
+/**
+ * How the authoring door spells its declaration and translates it to the
+ * wire. The rule set is shared with record recognition; only field spelling
+ * differs between authoring refusals and stored-record findings.
+ */
+export interface DeclarationDoor {
+    /** The helper's name, for the one refusal that names the call itself. */
+    readonly name: string;
+    /** The top-level keys a declaration may carry. */
+    readonly declarationKeys: readonly string[];
+    /** The keys that would hand-write the DERIVED `not_covered` prose list. */
+    readonly derivedKeys: readonly string[];
+    /** Each object a declaration may carry, with the keys it has in this
+     *  door's spelling — refused BEFORE anything is copied. */
+    readonly objectKeys: ReadonlyArray<readonly [field: DeclaredObject, known: readonly string[]]>;
+    /** Copy one declared object into the wire's spelling, keeping key order.
+     *  What it does with a value that is not a plain object is the door's own
+     *  call: the rule set names whatever reaches the candidate. */
+    readonly toWire: (field: RespelledObject, value: unknown) => unknown;
+    /** How this door's author spells the six snake_case wire fields. */
+    readonly spelling: Spelling;
+}
+/** Compose the `not_covered` prose lines FROM coverage — the one derivation,
+ *  used by the mint and by the drift check, so the two can never disagree. */
+export declare function composeNotCovered(coverage: SemanticCoverage): readonly string[];
+/**
+ * THE provenance rule — one present `provenance` object, in the wire's
+ * spelling, judged; every fault, each naming its field the way `s` spells it.
+ * `issuesIn` asks it for a described result, and `coverage/absent.ts` asks it
+ * for an absence's `provenance` (honesty step 7b), so the two doors cannot
+ * disagree about what a well-formed source and time is: `measured_at` and
+ * `source` required, `age_seconds` a finite number ≥ 0, `source_export_date`
+ * a non-empty string, no other key.
+ */
+export declare function provenanceIssues(provenance: unknown, s: Spelling): SemanticIssue[];
+/**
+ * Judge one RENDERED envelope shape against the whole rule set. Empty = a
+ * well-formed envelope this library can honor. Non-empty = the faults, each
+ * naming its field.
+ *
+ * Called with values that carry the marker; on anything else it reports the
+ * missing marker rather than guessing.
+ */
+export declare function semanticIssues(value: unknown): readonly SemanticIssue[];
+/**
+ * The ONE mint behind `describedResult()`. Refuses (throws, at the call site — the `absent()` law) any
+ * declaration this vocabulary cannot honor, in the door's own words; returns
+ * the rendered envelope otherwise.
+ *
+ * In order: the declaration must be an object; a hand-written `not_covered`
+ * is refused as derived; every key the declaration and its objects carry must
+ * be one the door reads (a casing slip names the spelling meant); coverage is
+ * normalized; the candidate is built in the WIRE spelling; and the whole rule
+ * set judges it, naming each field as the door's author spelled it.
+ */
+export declare function mintSemantics(decl: DescribedResultDeclaration, door: DeclarationDoor): ToolSemantics;
+/**
+ * Recognize (or decline to recognize) a value as a semantic envelope —
+ * STRICT, and the strictness is the zero-cost guarantee. Only a plain object
+ * whose `af_semantics` is exactly `true` AND that passes the whole rule set
+ * qualifies; every other value any tool has ever returned takes the path it
+ * always took, byte for byte.
+ *
+ * `undefined` means "not an envelope this library can honor" — a marker-
+ * bearing value with faults stays DATA (never half-applied); the dispatch
+ * loop dev-warns it and `check:semantics` names every fault.
+ */
+export declare function readSemantics(value: unknown): ToolSemantics | undefined;
+/**
+ * Name what is wrong with a value that CARRIES the marker but was not
+ * recognized. `undefined` for values without the marker (they are data, not
+ * near-misses) and for well-formed envelopes. Diagnosis only — never changes
+ * what any value does.
+ */
+export declare function explainSemantics(value: unknown): readonly SemanticIssue[] | undefined;
+/**
+ * The MODEL's view of one recognized envelope — compact and rendering-free.
+ *
+ * Keeps: the data (`series`/`facts`/`edges`), the caveats that must travel
+ * with it (`grain`, `provenance`), the composed `not_covered` prose, a
+ * non-null `clarify`, and the static note. Drops: the marker, `render`
+ * (UI hint), the three-list `coverage` detail (rides the coverage channel
+ * and the record), and a `clarify: null`. Shallow-copied so the history
+ * entry is not the object the tool still holds.
+ *
+ * The period is served as the tool declared it — plus, when the store did not
+ * hold all of the time the read asked about, the verdict word inside it and
+ * that word's one clause after the note (`coverage/period.ts` ·
+ * `servedPeriod`; honesty step 7b, bench round 1). A `covered` period and an
+ * envelope with none are served byte for byte as before.
+ */
+export declare function semanticsForModel(sem: ToolSemantics): Record<string, unknown>;
+/**
+ * The period a RECOGNIZED envelope declared, in the record's camelCase form
+ * (honesty step 7b) — `undefined` when it declared none. Recognition already
+ * held the period to the rule set (a fault keeps the whole envelope data), so
+ * this is a read, never a judgement.
+ */
+export declare function periodOfSemantics(sem: ToolSemantics): DeclaredPeriod | undefined;
+/** The envelope's coverage in the normalized three-list shape the coverage
+ *  machinery reads — how `readCoverageResult` absorbs a semantic envelope's
+ *  boundary into the one coverage channel. */
+export declare function coverageOfSemantics(sem: ToolSemantics): Coverage;