agentfootprint
Version:
The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.
92 lines • 6.2 kB
TypeScript
/**
* knownStrings — THE one rule an event is served by under ANY policy that
* selects at least one name: every value is checked by its KIND, wherever it
* sits.
*
* Pattern: one small pure function (`keepKnownValues`) over the closed sets
* the library and the run declared.
* Role: what makes the served path SAFE without a per-field list. A record
* handed out whole can carry the conversation anywhere — a field
* nobody listed, a list inside a record, a key of a map, a copy the
* library derives from a selected value under a name of its own — so
* nothing is trusted by its position. A value is kept only when its
* kind says it cannot be what a person, the model, a tool or the data
* wrote:
*
* - numbers, booleans and null pass;
* - a string passes only when it is one of the library's own WORDS — an
* event type, a status, verdict or stop word, a fixed sentence:
* {@link LIBRARY_WORDS}, built from the code's own types and exhaustive by
* type (a word added to a payload union does not compile until it is
* listed). Ids, the names an app declared and the host's identity are not
* words: they are the placeholder too (a run's minted ids and its
* declared names come back later, each with a single owner and its own
* review);
* - every other string is the placeholder, inside lists and records too;
* - an object's KEY is a field name when the library's payload types name
* that field ({@link FIELD_NAMES}); any other key is data, checked by the
* same rule — the keys that fail are kept out together, as one
* placeholder entry;
* - a value that is not plain data (a class instance, a Map, a Date) cannot
* be vouched for and is the placeholder.
*
* What it serves is always a fresh copy of plain data (`keepKnownValues`).
* State, the snapshot and the commit log are not served by it: footprintjs's
* rule decides those, by name.
*/
import type { ABSENCE_NOTE, ABSENCE_NOTE_COMPOSED } from '../semantics/coverage/absent.js';
import type { CompletenessGapItem, CoveredResult, NamesFacetItem, SourceGapItem, ToolAbsence } from '../semantics/coverage/types.js';
import type { FigureDerivation } from '../core/agent/evidence/types.js';
import type { AgentfootprintEventMap, AgentfootprintEventType } from '../events/registry.js';
import type { CursorMoveCause, SkillEdgeKind } from '../injection-engine/skillGraph.js';
import type { GuardOperator } from '../injection-engine/skillGuard.js';
import type { InjectionTrigger } from '../injection-engine/types.js';
type Payloads = AgentfootprintEventMap[AgentfootprintEventType]['payload'];
/**
* The library's own envelopes a payload carries inside a field typed loosely
* (a tool's `result`, what the model read): `absent()`'s and `coverage()`'s,
* and the items an `among` miss composes into an absence's lists (typed
* apart from `CoverageItem`, which they extend). Their field names and words
* are the library's as much as a payload's.
*/
type Envelopes = ToolAbsence | CoveredResult | NamesFacetItem | SourceGapItem | CompletenessGapItem;
/** A depth counter for the type walks below (payload types nest a few levels). */
type Next = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, never];
/** Every string literal reachable in `T` — the members of its verdict-word unions. */
type StringLiterals<T, D extends number = 0> = [D] extends [never] ? never : T extends string ? string extends T ? never : T : T extends readonly (infer E)[] ? StringLiterals<E, Next[D]> : T extends (...args: never[]) => unknown ? never : T extends object ? {
[K in keyof T]-?: StringLiterals<T[K], Next[D]>;
}[keyof T] : never;
/** Every field name reachable in `T` — never an index signature's open key. */
type FieldNamesOf<T, D extends number = 0> = [D] extends [never] ? never : T extends readonly (infer E)[] ? FieldNamesOf<E, Next[D]> : T extends (...args: never[]) => unknown ? never : T extends object ? (string extends keyof T ? never : keyof T & string) | {
[K in keyof T]-?: FieldNamesOf<T[K], Next[D]>;
}[keyof T] : never;
/**
* The library's words its payload types carry as plain `string` — each a
* closed set in the code that writes it: a slot's ordering, a route's origin,
* a skill map's node kind, an evidence value's shape, the stop words every
* provider adapter normalizes to (`adapters/llm/*` · `normalizeStopReason`).
*/
type PlainStringWords = 'history-order' | 'registry+injections' | 'registry+provider+injections' | 'tree' | 'entry' | 'route' | 'model' | 'skill' | 'predicate' | 'identifier' | 'number' | 'no-read' | 'stop' | 'tool_use' | 'max_tokens';
/** (a) The library's own words. */
export type LibraryWord = AgentfootprintEventType | StringLiterals<Payloads> | StringLiterals<Envelopes> | typeof ABSENCE_NOTE | typeof ABSENCE_NOTE_COMPOSED | CursorMoveCause | SkillEdgeKind | GuardOperator | FigureDerivation | InjectionTrigger['kind'] | PlainStringWords;
/** The field names of the library's payloads. */
export type FieldName = FieldNamesOf<Payloads> | FieldNamesOf<Envelopes>;
/** (a) The library's own words — one exported frozen set. */
export declare const LIBRARY_WORDS: Readonly<Record<string, true>>;
/** The field names the library's payload types declare. */
export declare const FIELD_NAMES: Readonly<Record<string, true>>;
/** What one string is served as — itself when it is a library word, else the placeholder. */
export declare function servedString(value: string): string;
/**
* THE RULE — `value` with every string that is not a library word served as
* the placeholder, at every depth; numbers, booleans and null kept; a key
* that is not a payload field name checked like any string.
*
* Always a FRESH copy of plain data — never the object it was given: each
* value is read once (a getter is not asked twice), and only own enumerable
* string keys and array positions are copied, so nothing the walk did not
* check (a symbol key, a hidden property, a method on a list) rides along.
*/
export declare function keepKnownValues(value: unknown): unknown;
export {};
//# sourceMappingURL=knownStrings.d.ts.map