agentfootprint 9.52.0 → 9.53.0

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;