agentfootprint 12.2.0 → 13.0.0

package/dist/esm/adapters/observability/auditShapes.d.ts

@@ -0,0 +1,78 @@
+/**
+ * auditShapes — WHAT the audit chain's bounded mode keeps of each event: one
+ * shape per registered event type, every field of its payload ruled.
+ *
+ * Pattern: a declarative table, total over the registry
+ *          (`{ [T in keyof AgentfootprintEventMap]-?: BoundRule }`), built from
+ *          the combinators in `auditBounding.ts`.
+ * Role:    the bounding layer's data. `audit.ts` asks it for every event in
+ *          `payloadMode: 'bounded'`; an event type it does not know is
+ *          `unknownEventShape` — every field a marker.
+ * Emits:   N/A.
+ *
+ * A new event type, or a new field on a payload, does not compile until it is
+ * classified here. Content (what a person, the model, a tool or the data
+ * wrote, or a message composed from it) is a marker; structure (ids, names,
+ * kinds, codes, verdicts, counts, the library's own sentences, the words the
+ * app declared up front) is kept — and every kept value is CHECKED at runtime
+ * as the kind its type declares: `num`, `bool`, `str` (an open string: an id,
+ * a name, a label), `oneOf` (a closed union: exactly its words). No container
+ * is kept whole; each is spelled out field by field, so a child its type does
+ * not declare is a marker. The type walker
+ * (`test/type-regressions/AuditBoundingDepth.test.ts`) holds every rule here
+ * to the type beneath it; the runtime sweep
+ * (`test/observability-providers/audit-bounded-sweep.test.ts`) hands every rule
+ * what its kind forbids.
+ *
+ * The positions a record keeps although their value may come from the run —
+ * meta's who, decision evidence, a policy's tag, an app's reason word, a seen
+ * tool's name — are the rules `auditKeptByContract.ts` names, placed here.
+ *
+ * `audit.ts` looks an event's shape up in `eventShapeTable` — a `Map`, so an
+ * event NAME is never a key into a plain object (`constructor`, `__proto__`).
+ */
+import type { AgentfootprintEventMap } from '../../events/registry.js';
+import { type BoundRule } from './auditBounding.js';
+/** Attachment summary: preserve every declared field, check every runtime child. */
+export declare const boundScripts: BoundRule;
+/**
+ * A typed answer's limits: the three lists, the declared periods, what a read
+ * found still running and the values an `assume` rule filled. Every sentence
+ * and value is a marker; the tool and argument NAMES, the call ids, counts,
+ * kinds and the library's `'unknown'` stay.
+ */
+export declare const boundAnswerCoverage: BoundRule;
+/**
+ * A typed answer's negatives: each statement and the population it is about
+ * are markers; the answer field's declared name, the codes, verdicts, ids,
+ * tool names and counts stay.
+ */
+export declare const boundAnswerNegatives: BoundRule;
+type EventType = keyof AgentfootprintEventMap;
+/**
+ * Each record's meta: the run and stage ids, paths, indices and engine
+ * coordinates the dispatcher stamps — and the who the caller named
+ * (`sessionId`, `principal`, `tenant`), kept by contract. A field `EventMeta`
+ * does not declare, or a value of another kind, is a marker. (`wallClockMs` is
+ * the record's `timestamp`; `runId` its run anchor — `audit.ts` lifts both.)
+ */
+export declare const boundMeta: BoundRule;
+/**
+ * The whole-event shapes as a `Map`, by event type — what `audit.ts` looks an
+ * event up in. An event's name is the emitter's to choose (`agent.emit()`
+ * takes any string), so it is never a key into a plain object: a name
+ * `Object.prototype` holds (`constructor`, `toString`, `__proto__`) finds no
+ * shape here, and that event is bounded as unknown — every field a marker.
+ */
+export declare function eventShapeTable(toolRan: (name: string) => boolean): ReadonlyMap<string, BoundRule>;
+/**
+ * The whole-event shapes, by event type. `toolRan` answers whether this
+ * strategy has seen a tool of that name run (`createToolRunTracker`): a
+ * `tryInsteadTool` names another tool, and that name is kept only then —
+ * otherwise it is the tool author's word for a tool this agent may not hold
+ * (`otel.ts` · `coverageAttrs`, the same rule).
+ */
+export declare function eventShapes(toolRan: (name: string) => boolean): {
+    readonly [T in EventType]-?: BoundRule;
+};
+export {};