agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
71 lines • 3.71 kB
JavaScript
/**
* semantics/types — the semantic tool-result vocabulary, as a PURE leaf
* (9.53.0, the `toolOutcome.ts` precedent).
*
* WHY IT LIVES HERE. Two sides read these words and neither may own the
* other: the agent loop's dispatch boundary (core/agent/stages/toolCalls.ts)
* recognizes the envelope at run time, and the `check:semantics` build gate
* (semantics/check.ts) judges the same shapes with no agent anywhere in
* sight. Declaring the vocabulary in a leaf both sides import keeps the
* dependency pointing the right way — the loop and the gate depend on the
* words, never on each other.
*
* The one exception to "zero imports" is TYPE-ONLY and deliberate: the
* envelope's `coverage` field ABSORBS the existing coverage vocabulary
* (`CoverageItem` / `CoverageInput`, semantics/coverage/types.ts — itself a
* pure-data leaf) instead of duplicating it. Two spellings of "ground this
* result does not cover" would eventually disagree; type-only imports erase
* at runtime, so this module stays a runtime leaf.
*
* ## What the envelope is
*
* A tool that answers "how many IOPS did fc1/3 do last hour?" today returns
* prose or an ad-hoc object, and every caveat that makes the number honest —
* the collection interval, whether the values are counters that must not be
* summed, when the world was actually measured, which clusters were not
* collected — is re-implemented by hand inside every tool and held in place
* by review. Culture scales to one disciplined author; it does not scale to
* a hundred tools. The semantic envelope makes those caveats TYPED DATA that
* travel with the values, so honesty is inherited, not re-authored — and so
* a build gate can refuse a triage tool that forgot its own limits.
*
* It is a SIBLING recognizer beside the effects envelope and the coverage
* primitives — its own reserved marker (`af_semantics`, the
* `af_absent`/`af_coverage` family), never new keys on the effects envelope.
* The three compose on one result: `{ content: describedResult({…}), effects:
* […], status }` is a tool that returns typed data AND proposes a transition.
*/
/**
* The reserved key that makes a semantic envelope recognizable. Reserved
* vocabulary on the tool-result wire (the `af_absent` / `af_coverage`
* precedent): a plain object carrying `af_semantics: true` that validates
* cleanly is an envelope; every other value any tool has ever returned keeps
* its bytes.
*/
export const SEMANTICS_MARKER = 'af_semantics';
/** The closed set, as data — validators and docs read one list. */
export const RESULT_CLASSES = ['triage', 'inventory'];
/**
* Aggregation words that suggest the values are counters — the words that
* make `grain.is_counter` REQUIRED (stated true or false). Matched as whole
* tokens, singular or plural, case-insensitive.
*/
export const COUNTER_AGGREGATION_WORDS = [
'sum',
'count',
'total',
'cumulative',
'counter',
'delta',
];
/**
* The static sentence every semantic envelope carries in the model's view.
* Never interpolated (the `ABSENCE_NOTE` law): everything else the model
* reads is the tool's own data, and a note that quoted any of it back would
* hand the evidence corpus a second copy of values it already indexes.
*/
export const SEMANTICS_NOTE = 'Typed data, not prose. `grain` and `provenance` are caveats that travel with the ' +
'numbers: check `is_counter` before summing values from a series, read `measured_at` ' +
'(and `age_seconds`) as how old the data is, and treat everything under `not_covered` ' +
'as ground this result does NOT cover — a clean look here says nothing about it.';
//# sourceMappingURL=types.js.map