agentfootprint 9.51.0 → 9.53.0

package/dist/esm/lib/semantics/check.js

@@ -0,0 +1,154 @@
+/**
+ * semantics/check — the `check:semantics` gate core (9.53.0).
+ *
+ * Pattern: humble shell (the tool-lint precedent) — ALL behavior lives here,
+ *          unit-tested; `bin/agentfootprint-check-semantics.mjs` only resolves
+ *          the built module and maps the exit code. Consumers wire the bin
+ *          into their own `check:` scripts beside `check:tools`.
+ * Role:    lib/ layer, pure. Judges SAMPLE RESULTS against the semantic
+ *          vocabulary and the per-class rules; never executes a tool, never
+ *          touches a network — the samples come from the consumer's own mock
+ *          tools or fixtures, the same way `check:tools` receives a dumped
+ *          catalog.
+ * Emits:   N/A.
+ *
+ * ## Severity follows provability (the skillGraph check-up law)
+ *
+ * Only what the declaration PROVES wrong is an error:
+ *
+ *   • a `'triage'` / `'inventory'` tool whose sample result declares no
+ *     coverage — the CLASS declared the requirement, the sample violates it;
+ *   • a marker-bearing envelope with faults (series without grain, data
+ *     without provenance, a counter-looking aggregation with `is_counter`
+ *     unstated, malformed shapes) — the marker declared the vocabulary, the
+ *     shape violates it.
+ *
+ * Everything else warns: a classed tool with NO samples (the gate cannot
+ * check what it cannot see — but silence must not read as a pass), and an
+ * inventory whose facts carry no render hint (useful, not provably harmful).
+ */
+import { readCoverageResult } from '../../core/agent/coverage/read.js';
+import { explainSemantics, readSemantics } from './envelope.js';
+import { RESULT_CLASSES } from './types.js';
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** True when a result states its boundary through ANY recognized door: a
+ *  semantic envelope with `coverage`, a `coverage()` ledger, or an
+ *  `absent()` (whose `checked` IS its coverage). */
+function declaresCoverage(result) {
+    const sem = readSemantics(result);
+    if (sem !== undefined)
+        return sem.coverage !== undefined;
+    return readCoverageResult(result) !== undefined;
+}
+function classCoverageFinding(entry, resultIndex) {
+    const cls = entry.resultClass;
+    return {
+        tool: entry.name,
+        code: cls === 'triage' ? 'triage-without-coverage' : 'inventory-without-coverage',
+        severity: 'error',
+        field: 'coverage',
+        resultIndex,
+        message: `tool '${entry.name}' is declared '${cls}' but sample result ${resultIndex + 1} ` +
+            `declares no coverage — field \`coverage\` is required on every ${cls} result. ` +
+            (cls === 'triage'
+                ? `A triage that cannot say what it did NOT check turns "everything looks fine" into ` +
+                    `a claim about ground it never stood on. `
+                : `An inventory that cannot say which population it covered ("4 of 5 clusters") reads ` +
+                    `as the whole fleet. `) +
+            `Return semantic({ …, coverage: { checked, notChecked, cannotCover } }), or coverage(result, …), ` +
+            `or absent({ … }) when nothing was found.`,
+    };
+}
+/**
+ * Judge a semantics catalog. Pure; throws only on a malformed CATALOG (a
+ * definition-side mistake — the CLI maps it to exit code 2), never on a
+ * malformed RESULT (that is a finding, the thing this gate exists to report).
+ */
+export function checkSemantics(entries) {
+    if (!Array.isArray(entries)) {
+        throw new Error('checkSemantics: takes an array of { name, resultClass?, results } entries.');
+    }
+    const findings = [];
+    let checkedResults = 0;
+    entries.forEach((raw, entryIndex) => {
+        if (!isPlainObject(raw)) {
+            throw new Error(`checkSemantics: entries[${entryIndex}] is not an object.`);
+        }
+        const entry = raw;
+        if (typeof entry.name !== 'string' || entry.name.trim().length === 0) {
+            throw new Error(`checkSemantics: entries[${entryIndex}] has no tool name.`);
+        }
+        const cls = entry.resultClass;
+        if (cls !== undefined && !RESULT_CLASSES.includes(cls)) {
+            throw new Error(`checkSemantics: tool '${entry.name}' declares resultClass '${String(cls)}', which is ` +
+                `not a class this library has. The classes are: ${RESULT_CLASSES.join(', ')}. ` +
+                `Omit the field for a tool with no class rules.`);
+        }
+        const results = entry.results;
+        if (!Array.isArray(results)) {
+            throw new Error(`checkSemantics: tool '${entry.name}' has no \`results\` array — the gate judges ` +
+                `sample results; give it at least one (your mock tool's return is the natural sample).`);
+        }
+        if (cls !== undefined && results.length === 0) {
+            findings.push({
+                tool: entry.name,
+                code: 'unsampled-tool-class',
+                severity: 'warning',
+                field: 'results',
+                message: `tool '${entry.name}' is declared '${cls}' but no sample results were given — the ` +
+                    `gate cannot check what it cannot see, and a class rule with no samples is a promise ` +
+                    `nobody is keeping. Add one sample result (a mock return is enough).`,
+            });
+        }
+        results.forEach((result, resultIndex) => {
+            checkedResults += 1;
+            // A marker-bearing value with faults: every fault becomes a finding
+            // under the recognizer's own code, naming the field.
+            const issues = explainSemantics(result);
+            if (issues !== undefined) {
+                for (const issue of issues) {
+                    findings.push({
+                        tool: entry.name,
+                        code: issue.code,
+                        severity: 'error',
+                        field: issue.field,
+                        resultIndex,
+                        message: `tool '${entry.name}', sample result ${resultIndex + 1}: ${issue.message}`,
+                    });
+                }
+                // An unrecognizable envelope cannot be judged for class rules — the
+                // faults above are already errors, and guessing at a broken shape
+                // would report the same problem twice under two names.
+                return;
+            }
+            const sem = readSemantics(result);
+            // ── The class rules ──
+            if ((cls === 'triage' || cls === 'inventory') && !declaresCoverage(result)) {
+                findings.push(classCoverageFinding(entry, resultIndex));
+            }
+            if (cls === 'inventory' &&
+                sem !== undefined &&
+                sem.facts !== undefined &&
+                sem.render === undefined) {
+                findings.push({
+                    tool: entry.name,
+                    code: 'inventory-without-render',
+                    severity: 'warning',
+                    field: 'render',
+                    resultIndex,
+                    message: `tool '${entry.name}', sample result ${resultIndex + 1}: an inventory with ` +
+                        `\`facts\` and no \`render\` hint — a UI can still draw the rows, but the tool ` +
+                        `author knows the right columns and sort better than any consumer. Consider ` +
+                        `render: { default: 'table', columns: […] }.`,
+                });
+            }
+        });
+    });
+    return {
+        ok: !findings.some((f) => f.severity === 'error'),
+        findings,
+        checkedTools: entries.length,
+        checkedResults,
+    };
+}
+//# sourceMappingURL=check.js.map

package/dist/esm/lib/semantics/check.js.map

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

package/dist/esm/lib/semantics/cli.d.ts

@@ -0,0 +1,40 @@
+/**
+ * check:semantics CLI core (9.53.0 — the build gate).
+ *
+ * Pattern: humble shell (the tool-lint `cli.ts` precedent) —
+ *          `bin/agentfootprint-check-semantics.mjs` is a 2-line wrapper;
+ *          ALL behavior (arg parsing, catalog coercion, report, exit code)
+ *          lives here so it is unit-testable without spawning a process.
+ * Role:    `src/lib/semantics/`. Reads ONE JSON file of tools + sample
+ *          results, prints a report, returns the process exit code:
+ *            0 — report.ok (and, under --strict, zero warnings)
+ *            1 — findings failed the gate
+ *            2 — usage / input error (bad flags, unreadable file,
+ *                unrecognized JSON shape, unknown resultClass)
+ *
+ * Consumers wire it beside their other gates (the `check:tools` convention):
+ *
+ *   "check:semantics": "node scripts/dump-semantics-catalog.mjs && agentfootprint-check-semantics semantics-catalog.json"
+ *
+ * The catalog is sample results — what your MOCK tools return — because the
+ * gate judges result shapes, and a build must never run tools that touch
+ * live systems. A mock catalog is something this ecosystem already has
+ * everywhere the check matters.
+ */
+import { type SemanticsCatalogEntry } from './check.js';
+export interface SemanticsCliIO {
+    readonly stdout: (line: string) => void;
+    readonly stderr: (line: string) => void;
+}
+/**
+ * Normalize the accepted JSON shapes to the checker's catalog. Throws (with
+ * a shape description) on unrecognized input — the CLI maps that to exit
+ * code 2. `resultClass` values are passed through untouched; the checker is
+ * the one owner of the closed-set refusal.
+ */
+export declare function coerceSemanticsCatalog(json: unknown): readonly SemanticsCatalogEntry[];
+/**
+ * Run the gate CLI. Returns the exit code (never calls `process.exit` — the
+ * bin wrapper assigns it to `process.exitCode`).
+ */
+export declare function runCheckSemanticsCli(argv: readonly string[], io?: SemanticsCliIO): Promise<number>;

package/dist/esm/lib/semantics/cli.js

@@ -0,0 +1,148 @@
+/**
+ * check:semantics CLI core (9.53.0 — the build gate).
+ *
+ * Pattern: humble shell (the tool-lint `cli.ts` precedent) —
+ *          `bin/agentfootprint-check-semantics.mjs` is a 2-line wrapper;
+ *          ALL behavior (arg parsing, catalog coercion, report, exit code)
+ *          lives here so it is unit-testable without spawning a process.
+ * Role:    `src/lib/semantics/`. Reads ONE JSON file of tools + sample
+ *          results, prints a report, returns the process exit code:
+ *            0 — report.ok (and, under --strict, zero warnings)
+ *            1 — findings failed the gate
+ *            2 — usage / input error (bad flags, unreadable file,
+ *                unrecognized JSON shape, unknown resultClass)
+ *
+ * Consumers wire it beside their other gates (the `check:tools` convention):
+ *
+ *   "check:semantics": "node scripts/dump-semantics-catalog.mjs && agentfootprint-check-semantics semantics-catalog.json"
+ *
+ * The catalog is sample results — what your MOCK tools return — because the
+ * gate judges result shapes, and a build must never run tools that touch
+ * live systems. A mock catalog is something this ecosystem already has
+ * everywhere the check matters.
+ */
+import { checkSemantics } from './check.js';
+import { formatSemanticsReport } from './format.js';
+import { RESULT_CLASSES } from './types.js';
+const USAGE = `usage: agentfootprint-check-semantics <semantics-catalog.json> [options]
+
+  <semantics-catalog.json>  JSON file of tools + sample results. Accepted shapes:
+                              [{ name, resultClass?, results: [...] }]
+                              [{ name, resultClass?, result: ... }]     (single sample)
+                              { tools: [...] }                          (either row shape)
+
+                            resultClass ∈ { ${RESULT_CLASSES.join(', ')} } — the class
+                            declared on defineTool({ resultClass }); omit for tools
+                            with no class rules (envelope rules still apply).
+
+  --strict                  warnings also fail the gate
+  --json                    print the full report as JSON instead of text
+
+exit codes: 0 ok · 1 findings failed the gate · 2 usage/input error`;
+/**
+ * Normalize the accepted JSON shapes to the checker's catalog. Throws (with
+ * a shape description) on unrecognized input — the CLI maps that to exit
+ * code 2. `resultClass` values are passed through untouched; the checker is
+ * the one owner of the closed-set refusal.
+ */
+export function coerceSemanticsCatalog(json) {
+    const list = Array.isArray(json)
+        ? json
+        : json !== null &&
+            typeof json === 'object' &&
+            Array.isArray(json.tools)
+            ? json.tools
+            : undefined;
+    if (list === undefined) {
+        throw new Error('expected a JSON array of { name, resultClass?, results } rows or { tools: [...] }');
+    }
+    return list.map((raw, index) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`tools[${index}] is not an object`);
+        }
+        const entry = raw;
+        const name = entry.name;
+        if (typeof name !== 'string' || name.length === 0) {
+            throw new Error(`tools[${index}] has no string 'name'`);
+        }
+        const results = Array.isArray(entry.results)
+            ? entry.results
+            : 'result' in entry
+                ? [entry.result]
+                : undefined;
+        if (results === undefined) {
+            throw new Error(`tools[${index}] ('${name}') has neither 'results' (an array of sample results) nor ` +
+                `'result' (one sample) — the gate judges sample results; a mock tool's return is ` +
+                `the natural sample.`);
+        }
+        return {
+            name,
+            ...(entry.resultClass !== undefined
+                ? { resultClass: entry.resultClass }
+                : {}),
+            results,
+        };
+    });
+}
+/**
+ * Run the gate CLI. Returns the exit code (never calls `process.exit` — the
+ * bin wrapper assigns it to `process.exitCode`).
+ */
+export async function runCheckSemanticsCli(argv, io = {
+    // eslint-disable-next-line no-console
+    stdout: (line) => console.log(line),
+    // eslint-disable-next-line no-console
+    stderr: (line) => console.error(line),
+}) {
+    let file;
+    let strict = false;
+    let json = false;
+    for (const arg of argv) {
+        if (arg === '--strict')
+            strict = true;
+        else if (arg === '--json')
+            json = true;
+        else if (arg === '--help' || arg === '-h') {
+            io.stderr(USAGE);
+            return 2;
+        }
+        else if (arg.startsWith('-')) {
+            io.stderr(`unknown flag '${arg}'\n\n${USAGE}`);
+            return 2;
+        }
+        else if (file === undefined)
+            file = arg;
+        else {
+            io.stderr(`unexpected extra argument '${arg}'\n\n${USAGE}`);
+            return 2;
+        }
+    }
+    if (file === undefined) {
+        io.stderr(USAGE);
+        return 2;
+    }
+    let report;
+    try {
+        // Lazy node:fs import (browser-compat — the tool-lint precedent):
+        // `agentfootprint/observe` re-exports this module, and a top-level
+        // node:fs import detonates a browser bundle at module-eval. The CLI
+        // path is the only consumer that touches the filesystem.
+        const { readFile } = await import('node:fs/promises');
+        const catalog = coerceSemanticsCatalog(JSON.parse(await readFile(file, 'utf8')));
+        report = checkSemantics(catalog);
+    }
+    catch (error) {
+        io.stderr(`agentfootprint-check-semantics: ${file}: ${error.message}`);
+        return 2;
+    }
+    if (json)
+        io.stdout(JSON.stringify(report, null, 2));
+    else
+        io.stdout(formatSemanticsReport(report));
+    if (!report.ok)
+        return 1;
+    if (strict && report.findings.length > 0)
+        return 1;
+    return 0;
+}
+//# sourceMappingURL=cli.js.map

package/dist/esm/lib/semantics/cli.js.map

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

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

@@ -0,0 +1,139 @@
+/**
+ * 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; `semantic()` 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, two doors
+ *
+ * `semantic()` 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.
+ */
+import type { Coverage } from '../../core/agent/coverage/types.js';
+import { type SemanticCoverage, type SemanticDeclaration, 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;
+/** 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[];
+/**
+ * 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[];
+/**
+ * Say "here is typed data, with the caveats that make it honest" in a shape
+ * the framework recognizes, the record keeps whole, and a build gate can
+ * refuse.
+ *
+ * Returns the value a tool's `execute` should return. The framework
+ * recognizes it at the dispatch boundary: the MODEL reads the compact
+ * projection ({@link semanticsForModel}), the FULL envelope rides the typed
+ * `agentfootprint.tools.semantics_declared` event, and a declared `coverage`
+ * flows through the same channel `coverage()` uses.
+ *
+ * Refuses (throws, at the call site — the `absent()` law) any declaration
+ * this vocabulary cannot honor: series without grain, data without
+ * provenance, a counter-looking aggregation with `is_counter` unstated, and
+ * every malformed shape — each refusal names the field and the fix.
+ *
+ * @example a per-port IOPS tool
+ *   return semantic({
+ *     series: rows.map((r) => ({ t: r.time, entity: r.port, metric: 'avg_iops', value: r.iops })),
+ *     grain: { interval: '30m', aggregation: 'avg', is_counter: false },
+ *     provenance: { measured_at: latestSampleTime, source: 'InfluxDB SwitchPortStats' },
+ *     coverage: {
+ *       checked: ['shq-fab-a: all 48 FC ports'],
+ *       notChecked: [{ what: 'the peer fabric', why: 'this collector is scoped to one fabric' }],
+ *     },
+ *     render: { default: 'table', columns: ['entity', 'value'], sort: 'value desc' },
+ *   });
+ */
+export declare function semantic(decl: SemanticDeclaration): 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.
+ */
+export declare function semanticsForModel(sem: ToolSemantics): Record<string, unknown>;
+/** 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;