agentfootprint 12.2.0 → 13.0.0

package/dist/esm/adapters/observability/auditBounding.js

@@ -0,0 +1,390 @@
+/**
+ * auditBounding — HOW the audit chain's bounded mode bounds a value: the
+ * markers, the sanitizer, the leaves and the combinators every shape is built
+ * from (`auditShapes.ts` says WHAT each event keeps; `auditKeptByContract.ts`
+ * names what a record keeps although it may carry a run's value).
+ *
+ * Pattern: small pure rules composed into shapes; every rule records what it is
+ *          (`ruleKind`), so a test can walk a shape beside the type it bounds
+ *          and hand every rule what its kind forbids.
+ * Role:    the bounding layer `auditExport({ payloadMode: 'bounded' })` runs
+ *          every payload and every record's meta through (`audit.ts`). No I/O,
+ *          no clock.
+ * Emits:   N/A.
+ *
+ * THE RULE, the one `otel.ts` maps spans by: **structure is kept, content is
+ * a marker**, bounding is CLOSED by default, and every kept value is CHECKED:
+ *
+ *   - Every registered event has a shape that names every field of its
+ *     payload type (`shapeOf` is exhaustive by type: a field added to a
+ *     payload does not compile until it is classified).
+ *   - A field a shape does not name, a value that is not the declared shape,
+ *     and every field of an event type the registry does not declare, is a
+ *     marker.
+ *   - A type says what a field holds; it cannot say what ARRIVES. So nothing is
+ *     kept on a type's word: a kept leaf checks at runtime the kind its type
+ *     promises — `num` a number, `bool` a boolean, `str` a string, `oneOf` one
+ *     of the words it lists — and anything else is a marker. No container is
+ *     kept whole: an object is a `shapeOf` (or a `recordOf`), a list a
+ *     `listOf`, every child ruled, so a child the type does not declare is a
+ *     marker however it got there (structural typing lets an object carry one).
+ *     The type walker (`test/type-regressions/AuditBoundingDepth.test.ts`)
+ *     holds every rule to the type beneath it; the runtime sweep
+ *     (`test/observability-providers/audit-bounded-sweep.test.ts`) hands every
+ *     rule what its kind forbids.
+ *   - Names are data. A key is kept as an own key of the record, whatever it is
+ *     (a name `Object.prototype` holds included: an assignment would drop
+ *     `__proto__`, or re-prototype the record), and no rule table is ever asked
+ *     for a name it merely inherits.
+ *
+ * Content becomes `'[N chars]'` (a string), `'[type: …]'` (anything else),
+ * `'[keys: …]'` (a free-form record: its key names, never its values), or a
+ * count (`'[N messages]'`, `'[N blocks]'`, `'[N summaries]'`). A kept string is
+ * capped at 256 characters, a list at 32 items.
+ */
+import { isErrorValue, wireError } from '../../lib/wireJson.js';
+// ─── JSON sanitization (verbatim mode, and the genesis record) ───────
+/** Caps mirror otel.ts's bounding discipline (defense-in-depth — the
+ *  registry payloads are mostly bounded upstream). */
+const MAX_STRING_CHARS = 256;
+const MAX_LIST_ITEMS = 32;
+const MAX_DEPTH = 8;
+/** A string capped like every string the chain keeps. */
+function capped(text) {
+    return text.length > MAX_STRING_CHARS ? `${text.slice(0, MAX_STRING_CHARS - 1)}…` : text;
+}
+/**
+ * A record whose every key is an OWN data property — `__proto__` included.
+ * `out[key] = value` would drop a `__proto__` key whose value is not an object
+ * and re-prototype the record when it is; either way the key is lost.
+ */
+function ownRecord(entries) {
+    return Object.fromEntries(entries);
+}
+/**
+ * Convert any value to a JSON-safe, size-bounded tree:
+ * strings capped, arrays capped with an overflow marker, cycles
+ * broken, depth capped, Date → ISO, bigint → string, non-finite →
+ * null, functions/symbols/undefined dropped (objects) or null
+ * (arrays). Every key an own key. Output always canonicalizes without
+ * throwing.
+ */
+export function sanitizeJson(value, depth = 0, seen = new Set()) {
+    if (value === null)
+        return null;
+    switch (typeof value) {
+        case 'string':
+            return capped(value);
+        case 'number':
+            return Number.isFinite(value) ? value : null;
+        case 'boolean':
+            return value;
+        case 'bigint':
+            return String(value);
+        case 'undefined':
+        case 'function':
+        case 'symbol':
+            return undefined;
+        default:
+            break;
+    }
+    const obj = value;
+    if (obj instanceof Date)
+        return obj.toISOString();
+    // The wire rule (`lib/wireJson.ts`): name, message, code, cause — never an
+    // Error's custom properties (an axios error's request headers).
+    if (isErrorValue(obj))
+        return sanitizeJson(wireError(obj), depth, seen);
+    if (depth >= MAX_DEPTH)
+        return '[truncated: depth]';
+    if (seen.has(obj))
+        return '[circular]';
+    seen.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            const list = obj.slice(0, MAX_LIST_ITEMS).map((item) => {
+                const sanitized = sanitizeJson(item, depth + 1, seen);
+                return sanitized === undefined ? null : sanitized;
+            });
+            if (obj.length > MAX_LIST_ITEMS)
+                list.push(`…+${obj.length - MAX_LIST_ITEMS} more`);
+            return list;
+        }
+        const entries = [];
+        for (const [key, entry] of Object.entries(obj)) {
+            const sanitized = sanitizeJson(entry, depth + 1, seen);
+            if (sanitized !== undefined)
+                entries.push([key, sanitized]);
+        }
+        return ownRecord(entries);
+    }
+    finally {
+        seen.delete(obj);
+    }
+}
+/** A value's kind — `undefined` for one JSON has no word for (a function, a symbol, a bigint). */
+export function valueKindOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    switch (typeof value) {
+        case 'string':
+            return 'string';
+        case 'number':
+            return 'number';
+        case 'boolean':
+            return 'boolean';
+        case 'object':
+            return 'object';
+        default:
+            return undefined;
+    }
+}
+const KINDS = new WeakMap();
+const described = (rule, kind) => {
+    KINDS.set(rule, kind);
+    return rule;
+};
+/** What a rule is — `undefined` only for a function this module did not build. */
+export function ruleKind(rule) {
+    return KINDS.get(rule);
+}
+/**
+ * The value kinds a rule KEEPS something of at its own position — what
+ * `either` dispatches on. A marker accepts none: it keeps nothing of any value.
+ *
+ * @internal
+ */
+export function acceptedKinds(rule) {
+    const k = KINDS.get(rule);
+    switch (k?.kind) {
+        case 'leaf':
+            return new Set([k.accepts]);
+        case 'oneOf':
+            return new Set([...k.values].map((value) => valueKindOf(value)));
+        case 'shape':
+        case 'record':
+            return new Set(['object']);
+        case 'list':
+            return new Set(['array']);
+        case 'orList':
+            return new Set(['array', ...acceptedKinds(k.item)]);
+        case 'nullOr':
+            return new Set(['null', ...acceptedKinds(k.inner)]);
+        case 'either':
+            return new Set(k.alternatives.flatMap((alternative) => [...acceptedKinds(alternative)]));
+        case 'when':
+            return new Set([...acceptedKinds(k.then), ...acceptedKinds(k.otherwise)]);
+        case 'byContract':
+            return acceptedKinds(k.inner);
+        default:
+            return new Set();
+    }
+}
+// ─── Markers — keep nothing of the value ─────────────────────────────
+export function typeofOf(value) {
+    return value === null ? 'null' : typeof value;
+}
+/** `'[23 chars]'` — length evidence without content. */
+export function charsMarker(value) {
+    return typeof value === 'string' ? `[${value.length} chars]` : `[type: ${typeofOf(value)}]`;
+}
+/** `'[keys: a, b, c]'` — shape evidence for free-form Records. */
+export function keysMarker(value) {
+    if (value === null || typeof value !== 'object')
+        return `[type: ${typeofOf(value)}]`;
+    const keys = Object.keys(value).slice(0, MAX_LIST_ITEMS);
+    return `[keys: ${keys.join(', ')}]`;
+}
+/** `'[type: object]'` — what kind of value, nothing of it (a tool's result). */
+export const typeMarker = (value) => `[type: ${typeofOf(value)}]`;
+/** A list's length, in the words of what it holds; anything else by `charsMarker`. */
+const countMarker = (noun) => described((value) => (Array.isArray(value) ? `[${value.length} ${noun}]` : charsMarker(value)), {
+    kind: 'marker',
+    marks: 'count',
+});
+described(charsMarker, { kind: 'marker', marks: 'chars' });
+described(keysMarker, { kind: 'marker', marks: 'keys' });
+described(typeMarker, { kind: 'marker', marks: 'type' });
+/** `'[3 messages]'` — a conversation's history. */
+export const messagesMarker = countMarker('messages');
+/** `'[2 blocks]'` — the model's thinking blocks. */
+export const blocksMarker = countMarker('blocks');
+/** `'[4 summaries]'` — the previews of what a slot dropped. */
+export const summariesMarker = countMarker('summaries');
+// ─── Leaves — a value of the declared kind, checked ──────────────────
+/** A count, a duration, a score, an index: kept when it IS a number (non-finite as `null`). */
+export const num = described((value) => typeof value === 'number' ? (Number.isFinite(value) ? value : null) : charsMarker(value), { kind: 'leaf', accepts: 'number' });
+/** A flag or a verdict: kept when it IS a boolean. */
+export const bool = described((value) => (typeof value === 'boolean' ? value : charsMarker(value)), { kind: 'leaf', accepts: 'boolean' });
+/**
+ * The record's own word — an id, a name, a code, a label the app declared: kept
+ * when it IS a string, capped. Where the type is a closed union of words, use
+ * `oneOf`, which keeps only those words.
+ */
+export const str = described((value) => (typeof value === 'string' ? capped(value) : charsMarker(value)), { kind: 'leaf', accepts: 'string' });
+/**
+ * One of the listed words (or numbers, or booleans): kept when the value IS one
+ * of them — so what it keeps is always a word this table wrote. Anything else
+ * is a marker.
+ */
+export function oneOf(...values) {
+    const words = new Set(values);
+    return described((value) => (words.has(value) ? value : charsMarker(value)), {
+        kind: 'oneOf',
+        values: new Set(words),
+    });
+}
+/**
+ * An object of a known shape, every field ruled (exhaustive by type, so a field
+ * added to `T` does not compile until it is). A field the rules do not name is
+ * a marker: whatever the value carries at runtime is bounded until someone
+ * decides it is the record's own words. Anything but an object is a marker too.
+ */
+export function shapeOf(rules) {
+    const byField = new Map(Object.entries(rules));
+    return described((value) => {
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return charsMarker(value);
+        }
+        const entries = [];
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                continue; // absent, as JSON has it
+            const bounded = (byField.get(key) ?? charsMarker)(entry);
+            if (bounded !== undefined)
+                entries.push([key, bounded]);
+        }
+        return ownRecord(entries);
+    }, { kind: 'shape', fields: new Map(byField) });
+}
+/** A list: each entry by `rule`, capped at 32 like every list. Anything else is a marker. */
+export function listOf(rule) {
+    return described((value) => {
+        if (!Array.isArray(value))
+            return charsMarker(value);
+        const out = [];
+        for (let i = 0; i < Math.min(value.length, MAX_LIST_ITEMS); i++) {
+            out.push(rule(value[i]) ?? null);
+        }
+        if (value.length > MAX_LIST_ITEMS)
+            out.push(`…+${value.length - MAX_LIST_ITEMS} more`);
+        return out;
+    }, { kind: 'list', item: rule });
+}
+/** A map with open keys: every key kept (a key is a name), every value by `rule`. Anything else is a marker. */
+export function recordOf(rule) {
+    return described((value) => {
+        if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+            return charsMarker(value);
+        }
+        const entries = [];
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined)
+                continue;
+            const bounded = rule(entry);
+            if (bounded !== undefined)
+                entries.push([key, bounded]);
+        }
+        return ownRecord(entries);
+    }, { kind: 'record', value: rule });
+}
+/** One value, or a list of them, each by `rule` — a guard's declared value is either. */
+export function orList(rule) {
+    const list = listOf(rule);
+    return described((value) => (Array.isArray(value) ? list(value) : rule(value)), {
+        kind: 'orList',
+        item: rule,
+    });
+}
+/** `null` stays `null` (a declared "none"); anything else by `rule`. */
+export function nullOr(rule) {
+    return described((value) => (value === null ? null : rule(value)), {
+        kind: 'nullOr',
+        inner: rule,
+    });
+}
+/**
+ * A value of one of several kinds — a library word or a window, a facet word or
+ * a filter: the first alternative that accepts the value's kind bounds it. A
+ * value no alternative accepts is a marker.
+ */
+export function either(...alternatives) {
+    const accepting = alternatives.map((alternative) => ({
+        rule: alternative,
+        kinds: acceptedKinds(alternative),
+    }));
+    return described((value) => {
+        const kind = valueKindOf(value);
+        const chosen = kind === undefined ? undefined : accepting.find((alt) => alt.kinds.has(kind))?.rule;
+        return (chosen ?? charsMarker)(value);
+    }, { kind: 'either', alternatives: [...alternatives] });
+}
+/**
+ * One rule or another, by a test of the value itself, the reason written down —
+ * the few places a field is structure only for some values (a name this
+ * strategy has seen run, the engine's own decision evidence).
+ */
+export function when(why, test, then, otherwise) {
+    return described((value) => (test(value) ? then : otherwise)(value), {
+        kind: 'when',
+        why,
+        then,
+        otherwise,
+    });
+}
+/**
+ * A position a bounded record keeps although its value may come from the run —
+ * one of the exceptions `auditKeptByContract.ts` names, in one place. The rule
+ * inside still checks the value like every other: an exception keeps a value of
+ * its declared kind, never whatever arrives.
+ */
+export function byContract(exception, rule) {
+    return described((value) => rule(value), { kind: 'byContract', exception, inner: rule });
+}
+/** An event type the registry does not declare (a consumer's own `emit`): every field a marker. */
+export const unknownEventShape = shapeOf({});
+// ─── The tools this strategy has seen run ────────────────────────────
+/** Names kept, and calls awaiting their end — each bounded, names and ids only. */
+const MAX_TOOL_NAMES = 1024;
+const MAX_OPEN_CALLS = 1024;
+/**
+ * Tool names this strategy has seen RUN — a `stream.tool_end` without `error`,
+ * `notExecuted` or `notDispatched`, matched to its `tool_start` by
+ * `toolCallId` — so a tool this agent holds, by construction. What a
+ * `tryInsteadTool` name is recognized against (`otel.ts` keeps the same set).
+ */
+export function createToolRunTracker() {
+    const open = new Map();
+    const ran = new Set();
+    return {
+        observe(type, payload) {
+            if (payload === null || typeof payload !== 'object')
+                return;
+            const p = payload;
+            if (typeof p.toolCallId !== 'string' || p.notDispatched !== undefined)
+                return;
+            if (type === 'agentfootprint.stream.tool_start' && typeof p.toolName === 'string') {
+                if (open.size >= MAX_OPEN_CALLS) {
+                    const [oldest] = open.keys();
+                    if (oldest !== undefined)
+                        open.delete(oldest);
+                }
+                open.set(p.toolCallId, p.toolName);
+                return;
+            }
+            if (type !== 'agentfootprint.stream.tool_end')
+                return;
+            const name = open.get(p.toolCallId);
+            open.delete(p.toolCallId);
+            const failed = p.error !== undefined && p.error !== false;
+            if (name === undefined || failed || p.notExecuted === true)
+                return;
+            if (ran.size < MAX_TOOL_NAMES || ran.has(name))
+                ran.add(name);
+        },
+        ran: (name) => ran.has(name),
+    };
+}
+//# sourceMappingURL=auditBounding.js.map

package/dist/esm/adapters/observability/auditBounding.js.map

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

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

@@ -0,0 +1,65 @@
+/**
+ * auditKeptByContract — what a BOUNDED audit record keeps although its value
+ * may come from the run: the named exceptions to "structure is kept, content
+ * is a marker", in one place.
+ *
+ * Pattern: a closed list of named exceptions (`KEPT_BY_CONTRACT`), each a rule
+ *          built from `auditBounding.ts` and wrapped in `byContract`, so a walker
+ *          finds every one by name.
+ * Role:    `auditShapes.ts` places these rules in the event shapes and the meta
+ *          shape; no other rule keeps a value the run composed.
+ * Emits:   N/A.
+ *
+ * An exception is a POSITION, never a pass-through: each one still checks its
+ * value like every other rule — it keeps a value of its declared kind (a
+ * string, or decide() evidence's own shape, field by field), and a value of any
+ * other kind, or a child its type does not declare, is a marker.
+ *
+ * Adding an exception, or placing one somewhere new, changes the pin in
+ * `test/observability-providers/audit-bounded-sweep.test.ts` — a reviewed
+ * change, never a silent one. The module documentation of `audit.ts`, the
+ * observability README and the exporters page state the same list.
+ */
+import type { DecisionEvidence, SelectionEvidence } from 'footprintjs';
+import { type BoundRule } from './auditBounding.js';
+/** The exceptions, by name — what each keeps, and why the record keeps it. */
+export declare const KEPT_BY_CONTRACT: {
+    readonly 'meta-identity': "who a run is for — the session id, principal and tenant the caller named — on each record's meta: the who of an audit record";
+    readonly 'decide-evidence': "decide()/select() evidence an app emits on `composition.route_decided`, as the engine summarized it: rule labels, branches, operators, thresholds and verdicts, each field checked";
+    readonly 'decision-summary': "the engine's summary of a value a decision rule read (decide() evidence, a skill guard's condition) — redaction-aware: under an agent's `redact` a selected key is the placeholder; otherwise the summary shows the value";
+    readonly 'policy-reason-tag': "a permission policy's telemetry `reason` tag (`permission.check`, `permission.halt`) — the policy's own word";
+    readonly 'app-reason-word': "the reason word an app attaches to a lifecycle event it emits itself (`skill.deactivated`, `tools.offered`, `permission.gate_closed`) — the app’s own words, as written";
+    readonly 'seen-tool-name': "a `tryInsteadTool` name, once this strategy has seen that tool run";
+};
+/** The name of a kept-by-contract exception. */
+export type KeptByContract = keyof typeof KEPT_BY_CONTRACT;
+/** decide()/select() evidence, as footprintjs declares it. */
+export type DecideEvidence = DecisionEvidence | SelectionEvidence;
+/**
+ * What a decide() filter compares against — a value the app declared, or a
+ * list of them — as this record keeps it. Anything else is a marker.
+ */
+export type DecideThreshold = string | number | boolean | null | readonly (string | number | boolean | null)[];
+/** A value the app declared: a word, a number or a flag — or a declared "none". */
+export declare const declaredValue: BoundRule;
+/** `meta.sessionId`, `meta.principal`, `meta.tenant`: the caller's own names for who. */
+export declare const metaIdentity: BoundRule;
+/** The engine's summary of a value a rule read. */
+export declare const decisionSummary: BoundRule;
+/** A permission policy's telemetry tag. */
+export declare const policyReasonTag: BoundRule;
+/** A reason word an app attaches to a lifecycle event it emits itself. */
+export declare const appReasonWord: BoundRule;
+/**
+ * A `tryInsteadTool` name: kept only once this strategy has seen that tool run —
+ * a tool the agent holds, by construction (`otel.ts` · `coverageAttrs`, the same
+ * rule); otherwise it is the tool author's word for a tool this agent may not
+ * hold.
+ */
+export declare function seenToolName(toolRan: (name: string) => boolean): BoundRule;
+/**
+ * `composition.route_decided.evidence`: decide() evidence is kept by contract,
+ * as its own shape; any other evidence (a router's own `{ reason }`) is a
+ * free-form record — its key names only.
+ */
+export declare const routeEvidence: BoundRule;

package/dist/esm/adapters/observability/auditKeptByContract.js

@@ -0,0 +1,103 @@
+/**
+ * auditKeptByContract — what a BOUNDED audit record keeps although its value
+ * may come from the run: the named exceptions to "structure is kept, content
+ * is a marker", in one place.
+ *
+ * Pattern: a closed list of named exceptions (`KEPT_BY_CONTRACT`), each a rule
+ *          built from `auditBounding.ts` and wrapped in `byContract`, so a walker
+ *          finds every one by name.
+ * Role:    `auditShapes.ts` places these rules in the event shapes and the meta
+ *          shape; no other rule keeps a value the run composed.
+ * Emits:   N/A.
+ *
+ * An exception is a POSITION, never a pass-through: each one still checks its
+ * value like every other rule — it keeps a value of its declared kind (a
+ * string, or decide() evidence's own shape, field by field), and a value of any
+ * other kind, or a child its type does not declare, is a marker.
+ *
+ * Adding an exception, or placing one somewhere new, changes the pin in
+ * `test/observability-providers/audit-bounded-sweep.test.ts` — a reviewed
+ * change, never a silent one. The module documentation of `audit.ts`, the
+ * observability README and the exporters page state the same list.
+ */
+import { bool, byContract, charsMarker, either, keysMarker, listOf, nullOr, num, oneOf, orList, shapeOf, str, when, } from './auditBounding.js';
+/** The exceptions, by name — what each keeps, and why the record keeps it. */
+export const KEPT_BY_CONTRACT = {
+    'meta-identity': "who a run is for — the session id, principal and tenant the caller named — on each record's meta: the who of an audit record",
+    'decide-evidence': 'decide()/select() evidence an app emits on `composition.route_decided`, as the engine summarized it: rule labels, branches, operators, thresholds and verdicts, each field checked',
+    'decision-summary': "the engine's summary of a value a decision rule read (decide() evidence, a skill guard's condition) — redaction-aware: under an agent's `redact` a selected key is the placeholder; otherwise the summary shows the value",
+    'policy-reason-tag': "a permission policy's telemetry `reason` tag (`permission.check`, `permission.halt`) — the policy's own word",
+    'app-reason-word': 'the reason word an app attaches to a lifecycle event it emits itself (`skill.deactivated`, `tools.offered`, `permission.gate_closed`) — the app’s own words, as written',
+    'seen-tool-name': 'a `tryInsteadTool` name, once this strategy has seen that tool run',
+};
+const exception = (name, rule) => byContract(name, rule);
+/** A value the app declared: a word, a number or a flag — or a declared "none". */
+export const declaredValue = nullOr(either(str, num, bool));
+// ─── The exceptions ──────────────────────────────────────────────────
+/** `meta.sessionId`, `meta.principal`, `meta.tenant`: the caller's own names for who. */
+export const metaIdentity = exception('meta-identity', str);
+/** The engine's summary of a value a rule read. */
+export const decisionSummary = exception('decision-summary', str);
+/** A permission policy's telemetry tag. */
+export const policyReasonTag = exception('policy-reason-tag', str);
+/** A reason word an app attaches to a lifecycle event it emits itself. */
+export const appReasonWord = exception('app-reason-word', str);
+/**
+ * A `tryInsteadTool` name: kept only once this strategy has seen that tool run —
+ * a tool the agent holds, by construction (`otel.ts` · `coverageAttrs`, the same
+ * rule); otherwise it is the tool author's word for a tool this agent may not
+ * hold.
+ */
+export function seenToolName(toolRan) {
+    return when('a name this strategy has seen run is a tool the agent holds', (value) => typeof value === 'string' && toolRan(value), exception('seen-tool-name', str), charsMarker);
+}
+/** One rule's evidence: what it read or compared, its verdict; a rule's thrown message is a marker. */
+const boundRuleEvidence = shapeOf({
+    type: oneOf('filter', 'function'),
+    ruleIndex: num,
+    branch: str,
+    matched: bool,
+    label: str,
+    inputs: listOf(shapeOf({ key: str, valueSummary: decisionSummary, redacted: bool })),
+    conditions: listOf(shapeOf({
+        key: str,
+        op: str,
+        threshold: orList(declaredValue),
+        actualSummary: decisionSummary,
+        result: bool,
+        redacted: bool,
+    })),
+    // A `when` that threw: its message can echo the value it read.
+    matchError: charsMarker,
+});
+/** decide()/select() evidence: every field footprintjs declares, each checked. */
+const boundDecideEvidence = shapeOf({
+    retryLoop: shapeOf({
+        id: str,
+        series: str,
+        attempt: num,
+        of: num,
+        effect: oneOf('applied', 'none', 'unknown'),
+        reconciled: bool,
+        next: oneOf('done', 'retry', 'stop'),
+        reason: str,
+    }),
+    rules: listOf(boundRuleEvidence),
+    chosen: str,
+    default: str,
+    defaultLabel: str,
+    selected: listOf(str),
+});
+/** decide() evidence carries its own `rules` list — `otel.ts`'s test too. */
+const isDecideEvidence = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.hasOwn(value, 'rules') &&
+    Array.isArray(value.rules);
+/**
+ * `composition.route_decided.evidence`: decide() evidence is kept by contract,
+ * as its own shape; any other evidence (a router's own `{ reason }`) is a
+ * free-form record — its key names only.
+ */
+export const routeEvidence = when("decide() evidence is the engine's, kept by contract; any other is a record", isDecideEvidence, exception('decide-evidence', boundDecideEvidence), keysMarker);
+//# sourceMappingURL=auditKeptByContract.js.map

package/dist/esm/adapters/observability/auditKeptByContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auditKeptByContract.js","sourceRoot":"","sources":["../../../../src/adapters/observability/auditKeptByContract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EACL,IAAI,EACJ,UAAU,EACV,WAAW,EACX,MAAM,EACN,UAAU,EACV,MAAM,EACN,MAAM,EACN,GAAG,EACH,KAAK,EACL,MAAM,EACN,OAAO,EACP,GAAG,EACH,IAAI,GAEL,MAAM,oBAAoB,CAAC;AAE5B,8EAA8E;AAC9E,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,eAAe,EACb,8HAA8H;IAChI,iBAAiB,EACf,oLAAoL;IACtL,kBAAkB,EAChB,2NAA2N;IAC7N,mBAAmB,EACjB,8GAA8G;IAChH,iBAAiB,EACf,yKAAyK;IAC3K,gBAAgB,EAAE,oEAAoE;CAC9E,CAAC;AAKX,MAAM,SAAS,GAAG,CAAC,IAAoB,EAAE,IAAe,EAAa,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAoB/F,mFAAmF;AACnF,MAAM,CAAC,MAAM,aAAa,GAAc,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AAEvE,wEAAwE;AAExE,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAc,SAAS,CAAC,eAAe,EAAE,GAAG,CAAC,CAAC;AAEvE,mDAAmD;AACnD,MAAM,CAAC,MAAM,eAAe,GAAc,SAAS,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;AAE7E,2CAA2C;AAC3C,MAAM,CAAC,MAAM,eAAe,GAAc,SAAS,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAE9E,0EAA0E;AAC1E,MAAM,CAAC,MAAM,aAAa,GAAc,SAAS,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAkC;IAC7D,OAAO,IAAI,CACT,6DAA6D,EAC7D,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,EACtD,SAAS,CAAC,gBAAgB,EAAE,GAAG,CAAC,EAChC,WAAW,CACZ,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,MAAM,iBAAiB,GAAG,OAAO,CAAe;IAC9C,IAAI,EAAE,KAAK,CAAC,QAAQ,EAAE,UAAU,CAAC;IACjC,SAAS,EAAE,GAAG;IACd,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,IAAI;IACb,KAAK,EAAE,GAAG;IACV,MAAM,EAAE,MAAM,CAAC,OAAO,CAAY,EAAE,GAAG,EAAE,GAAG,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/F,UAAU,EAAE,MAAM,CAChB,OAAO,CAAkB;QACvB,GAAG,EAAE,GAAG;QACR,EAAE,EAAE,GAAG;QACP,SAAS,EAAE,MAAM,CAAC,aAAa,CAAC;QAChC,aAAa,EAAE,eAAe;QAC9B,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;KACf,CAAC,CACH;IACD,+DAA+D;IAC/D,UAAU,EAAE,WAAW;CACxB,CAAC,CAAC;AAEH,kFAAkF;AAClF,MAAM,mBAAmB,GAAG,OAAO,CAAiB;IAClD,SAAS,EAAE,OAAO,CAA6C;QAC7D,EAAE,EAAE,GAAG;QACP,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,GAAG;QACZ,EAAE,EAAE,GAAG;QACP,MAAM,EAAE,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC;QAC3C,UAAU,EAAE,IAAI;QAChB,IAAI,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC;QACpC,MAAM,EAAE,GAAG;KACZ,CAAC;IACF,KAAK,EAAE,MAAM,CAAC,iBAAiB,CAAC;IAChC,MAAM,EAAE,GAAG;IACX,OAAO,EAAE,GAAG;IACZ,YAAY,EAAE,GAAG;IACjB,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC;CACtB,CAAC,CAAC;AAEH,6EAA6E;AAC7E,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAW,EAAE,CACnD,OAAO,KAAK,KAAK,QAAQ;IACzB,KAAK,KAAK,IAAI;IACd,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;IACrB,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;IAC7B,KAAK,CAAC,OAAO,CAAE,KAA6B,CAAC,KAAK,CAAC,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAc,IAAI,CAC1C,4EAA4E,EAC5E,gBAAgB,EAChB,SAAS,CAAC,iBAAiB,EAAE,mBAAmB,CAAC,EACjD,UAAU,CACX,CAAC"}