agentfootprint 9.52.0 → 9.53.0

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

@@ -0,0 +1,592 @@
+/**
+ * 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 { normalizeCoverageList } from '../../core/agent/coverage/items.js';
+import { COUNTER_AGGREGATION_WORDS, SEMANTICS_MARKER, SEMANTICS_NOTE, } from './types.js';
+const isNonEmptyString = (v) => typeof v === 'string' && v.trim().length > 0;
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** Whole-token match against {@link COUNTER_AGGREGATION_WORDS}, singular or
+ *  plural, case-insensitive — 'sum' and 'Counts' look like counters,
+ *  'summary' does not. */
+export function isCounterLookingAggregation(aggregation) {
+    const tokens = aggregation.toLowerCase().split(/[^a-z]+/);
+    return tokens.some((t) => COUNTER_AGGREGATION_WORDS.includes(t) ||
+        (t.endsWith('s') && COUNTER_AGGREGATION_WORDS.includes(t.slice(0, -1))));
+}
+const ENVELOPE_KEYS = new Set([
+    SEMANTICS_MARKER,
+    'series',
+    'facts',
+    'edges',
+    'grain',
+    'provenance',
+    'coverage',
+    'not_covered',
+    'clarify',
+    'render',
+    'note',
+]);
+const GRAIN_KEYS = new Set(['interval', 'aggregation', 'is_counter', 'collapsed']);
+const PROVENANCE_KEYS = new Set(['measured_at', 'age_seconds', 'source', 'source_export_date']);
+const COVERAGE_KEYS = new Set(['checked', 'not_checked', 'cannot_cover']);
+const CLARIFY_KEYS = new Set(['question', 'candidates']);
+const RENDER_KEYS = new Set(['default', 'columns', 'sort', 'filter_note', 'chart_hint']);
+/** 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 function composeNotCovered(coverage) {
+    const items = [...(coverage.not_checked ?? []), ...(coverage.cannot_cover ?? [])];
+    return items.map((i) => (i.why !== undefined ? `${i.what} — ${i.why}` : i.what));
+}
+function malformed(field, message) {
+    return { code: 'malformed-semantics', field, message };
+}
+/** Detach one clarify declaration for the candidate envelope. A non-object
+ *  passes through untouched so the validator can name it. */
+function copyClarify(clarify) {
+    if (!isPlainObject(clarify))
+        return clarify;
+    return {
+        question: clarify.question,
+        candidates: Array.isArray(clarify.candidates)
+            ? [...clarify.candidates]
+            : clarify.candidates ?? [],
+    };
+}
+function checkItemList(issues, field, list, requireWhy) {
+    if (list === undefined)
+        return [];
+    if (!Array.isArray(list)) {
+        issues.push(malformed(field, `\`${field}\` must be an array of { what, why? } items.`));
+        return [];
+    }
+    const items = [];
+    list.forEach((raw, i) => {
+        if (!isPlainObject(raw) || !isNonEmptyString(raw.what)) {
+            issues.push(malformed(`${field}[${i}]`, `\`${field}[${i}]\` names no ground — each item is { what, why? }.`));
+            return;
+        }
+        if (raw.why !== undefined && !isNonEmptyString(raw.why)) {
+            issues.push(malformed(`${field}[${i}].why`, `\`${field}[${i}]\` has a \`why\` that says nothing.`));
+            return;
+        }
+        if (requireWhy && raw.why === undefined) {
+            issues.push(malformed(`${field}[${i}].why`, `\`${field}[${i}]\` ('${raw.what.trim()}') has no \`why\` — a permanent blind spot is a ` +
+                `claim about capability, and a claim with no reason cannot be acted on or disproved.`));
+            return;
+        }
+        items.push({
+            what: raw.what,
+            ...(raw.why !== undefined && { why: raw.why }),
+        });
+    });
+    return items;
+}
+/**
+ * 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 function semanticIssues(value) {
+    if (!isPlainObject(value)) {
+        return [malformed(SEMANTICS_MARKER, 'a semantic envelope is a plain object.')];
+    }
+    if (value[SEMANTICS_MARKER] !== true) {
+        return [
+            malformed(SEMANTICS_MARKER, `\`${SEMANTICS_MARKER}\` must be exactly \`true\` — the marker is the vocabulary.`),
+        ];
+    }
+    const issues = [];
+    for (const key of Object.keys(value)) {
+        if (!ENVELOPE_KEYS.has(key)) {
+            issues.push(malformed(key, `carries '${key}', which is not a field this vocabulary has. The fields are: series, ` +
+                `facts, edges, grain, provenance, coverage, clarify, render (not_covered and note ` +
+                `are derived).`));
+        }
+    }
+    // ── series ──
+    const series = value.series;
+    if (series !== undefined) {
+        if (!Array.isArray(series) || series.length === 0) {
+            issues.push(malformed('series', '`series` must be a non-empty array of { t, entity, metric, value } points — omit the field to say nothing.'));
+        }
+        else {
+            series.forEach((p, i) => {
+                if (!isPlainObject(p)) {
+                    issues.push(malformed(`series[${i}]`, `\`series[${i}]\` is not a point object.`));
+                    return;
+                }
+                if (typeof p.t !== 'string' && typeof p.t !== 'number') {
+                    issues.push(malformed(`series[${i}].t`, `\`series[${i}].t\` must be the measurement time (an ISO string or an epoch number).`));
+                }
+                if (!isNonEmptyString(p.entity)) {
+                    issues.push(malformed(`series[${i}].entity`, `\`series[${i}].entity\` must name what was measured.`));
+                }
+                if (!isNonEmptyString(p.metric)) {
+                    issues.push(malformed(`series[${i}].metric`, `\`series[${i}].metric\` must name the measurement.`));
+                }
+                if (!('value' in p)) {
+                    issues.push(malformed(`series[${i}].value`, `\`series[${i}]\` has no \`value\` — a point with no reading is not a point.`));
+                }
+            });
+        }
+    }
+    // ── facts ──
+    const facts = value.facts;
+    if (facts !== undefined) {
+        if (!Array.isArray(facts) || facts.length === 0) {
+            issues.push(malformed('facts', '`facts` must be a non-empty array of rows — omit the field to say nothing.'));
+        }
+        else {
+            facts.forEach((f, i) => {
+                if (!isPlainObject(f) || !isNonEmptyString(f.entity)) {
+                    issues.push(malformed(`facts[${i}].entity`, `\`facts[${i}]\` must say WHAT it is about — every row needs a non-empty \`entity\`.`));
+                }
+            });
+        }
+    }
+    // ── edges ──
+    const edges = value.edges;
+    if (edges !== undefined) {
+        if (!Array.isArray(edges) || edges.length === 0) {
+            issues.push(malformed('edges', '`edges` must be a non-empty array of { from, to, kind } — omit the field to say nothing.'));
+        }
+        else {
+            edges.forEach((e, i) => {
+                if (!isPlainObject(e) ||
+                    !isNonEmptyString(e.from) ||
+                    !isNonEmptyString(e.to) ||
+                    !isNonEmptyString(e.kind)) {
+                    issues.push(malformed(`edges[${i}]`, `\`edges[${i}]\` must carry non-empty \`from\`, \`to\` and \`kind\`.`));
+                }
+            });
+        }
+    }
+    // ── grain ──
+    const grain = value.grain;
+    if (grain !== undefined) {
+        if (!isPlainObject(grain)) {
+            issues.push(malformed('grain', '`grain` must be an object ({ interval?, aggregation?, is_counter?, collapsed? }).'));
+        }
+        else {
+            for (const key of Object.keys(grain)) {
+                if (!GRAIN_KEYS.has(key))
+                    issues.push(malformed(`grain.${key}`, `\`grain.${key}\` is not a grain field.`));
+            }
+            let says = false;
+            for (const key of ['interval', 'aggregation', 'collapsed']) {
+                if (grain[key] !== undefined) {
+                    if (!isNonEmptyString(grain[key])) {
+                        issues.push(malformed(`grain.${key}`, `\`grain.${key}\` must be a non-empty string or omitted.`));
+                    }
+                    else
+                        says = true;
+                }
+            }
+            if (grain.is_counter !== undefined) {
+                if (typeof grain.is_counter !== 'boolean') {
+                    issues.push(malformed('grain.is_counter', '`grain.is_counter` must be a boolean — "stated" means true or false, never prose.'));
+                }
+                else
+                    says = true;
+            }
+            if (!says && issues.every((i) => !i.field.startsWith('grain'))) {
+                issues.push(malformed('grain', '`grain` says nothing — state at least one of interval, aggregation, is_counter, collapsed, or omit the field.'));
+            }
+            if (isNonEmptyString(grain.aggregation) &&
+                isCounterLookingAggregation(grain.aggregation) &&
+                typeof grain.is_counter !== 'boolean') {
+                issues.push({
+                    code: 'counter-aggregation-unstated',
+                    field: 'grain.is_counter',
+                    message: `grain.aggregation is '${grain.aggregation.trim()}', which is counter-looking, and ` +
+                        `\`is_counter\` is not stated. Summing counters double-counts, and a reader cannot ` +
+                        `tell a counter from a gauge by looking at a number — state \`is_counter: true\` or ` +
+                        `\`is_counter: false\`.`,
+                });
+            }
+        }
+    }
+    // ── provenance ──
+    const provenance = value.provenance;
+    const hasData = series !== undefined || facts !== undefined;
+    if (provenance !== undefined) {
+        if (!isPlainObject(provenance)) {
+            issues.push(malformed('provenance', '`provenance` must be an object ({ measured_at, source, age_seconds?, source_export_date? }).'));
+        }
+        else {
+            for (const key of Object.keys(provenance)) {
+                if (!PROVENANCE_KEYS.has(key))
+                    issues.push(malformed(`provenance.${key}`, `\`provenance.${key}\` is not a provenance field.`));
+            }
+            if (!isNonEmptyString(provenance.measured_at)) {
+                issues.push({
+                    code: 'data-without-provenance',
+                    field: 'provenance.measured_at',
+                    message: '`provenance.measured_at` must say when the WORLD was measured — a tool reading a ' +
+                        'nightly export and answering in 4ms is serving yesterday, and only this field says so.',
+                });
+            }
+            if (!isNonEmptyString(provenance.source)) {
+                issues.push({
+                    code: 'data-without-provenance',
+                    field: 'provenance.source',
+                    message: '`provenance.source` must name the system of record the values were read from.',
+                });
+            }
+            if (provenance.age_seconds !== undefined &&
+                (typeof provenance.age_seconds !== 'number' ||
+                    !Number.isFinite(provenance.age_seconds) ||
+                    provenance.age_seconds < 0)) {
+                issues.push(malformed('provenance.age_seconds', '`provenance.age_seconds` must be a finite number ≥ 0 or omitted.'));
+            }
+            if (provenance.source_export_date !== undefined &&
+                !isNonEmptyString(provenance.source_export_date)) {
+                issues.push(malformed('provenance.source_export_date', '`provenance.source_export_date` must be a non-empty string or omitted.'));
+            }
+        }
+    }
+    else if (hasData) {
+        issues.push({
+            code: 'data-without-provenance',
+            field: 'provenance',
+            message: 'carries series/facts with no `provenance` — `provenance.measured_at` and ' +
+                '`provenance.source` are required whenever the envelope carries data: a number with ' +
+                'no age and no source cannot be trusted or audited.',
+        });
+    }
+    // ── series ⇒ grain ──
+    if (series !== undefined && grain === undefined) {
+        issues.push({
+            code: 'series-without-grain',
+            field: 'grain',
+            message: 'carries `series` with no `grain` — a time-series with no stated interval/aggregation ' +
+                'reads as whatever the reader assumes, which is how counters get summed and windows get ' +
+                'compared across different intervals.',
+        });
+    }
+    // ── coverage (rendered) + not_covered derivation ──
+    const coverage = value.coverage;
+    let renderedCoverage;
+    if (coverage !== undefined) {
+        if (!isPlainObject(coverage)) {
+            issues.push(malformed('coverage', '`coverage` must be an object of { checked?, not_checked?, cannot_cover? } item lists.'));
+        }
+        else {
+            for (const key of Object.keys(coverage)) {
+                if (!COVERAGE_KEYS.has(key)) {
+                    issues.push(malformed(`coverage.${key}`, `\`coverage.${key}\` is not a coverage list — the three are checked, not_checked, cannot_cover.`));
+                }
+            }
+            const checked = checkItemList(issues, 'coverage.checked', coverage.checked, false);
+            const notChecked = checkItemList(issues, 'coverage.not_checked', coverage.not_checked, false);
+            const cannotCover = checkItemList(issues, 'coverage.cannot_cover', coverage.cannot_cover, true);
+            if (checked.length + notChecked.length + cannotCover.length === 0) {
+                issues.push(malformed('coverage', '`coverage` names no ground at all — declare at least one item, or omit the field.'));
+            }
+            else {
+                renderedCoverage = {
+                    ...(checked.length > 0 && { checked }),
+                    ...(notChecked.length > 0 && { not_checked: notChecked }),
+                    ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
+                };
+            }
+        }
+    }
+    const notCovered = value.not_covered;
+    if (notCovered !== undefined) {
+        if (coverage === undefined) {
+            issues.push(malformed('not_covered', '`not_covered` is DERIVED from `coverage` (not checked + cannot cover) — declare `coverage` instead of writing the prose by hand, so the two cannot disagree.'));
+        }
+        else if (!Array.isArray(notCovered) || !notCovered.every(isNonEmptyString)) {
+            issues.push(malformed('not_covered', '`not_covered` must be an array of non-empty strings.'));
+        }
+        else if (renderedCoverage !== undefined) {
+            const derived = composeNotCovered(renderedCoverage);
+            const same = derived.length === notCovered.length && derived.every((l, i) => l === notCovered[i]);
+            if (!same) {
+                issues.push(malformed('not_covered', '`not_covered` disagrees with what `coverage` derives — it is a derived field; drop it (the mint composes it) or fix the coverage lists.'));
+            }
+        }
+    }
+    // ── clarify ──
+    const clarify = value.clarify;
+    if (clarify !== undefined && clarify !== null) {
+        if (!isPlainObject(clarify)) {
+            issues.push(malformed('clarify', '`clarify` must be { question, candidates } or null (null states "ambiguity was considered; there is none").'));
+        }
+        else {
+            for (const key of Object.keys(clarify)) {
+                if (!CLARIFY_KEYS.has(key))
+                    issues.push(malformed(`clarify.${key}`, `\`clarify.${key}\` is not a clarify field.`));
+            }
+            if (!isNonEmptyString(clarify.question)) {
+                issues.push(malformed('clarify.question', '`clarify.question` must ask something.'));
+            }
+            if (!Array.isArray(clarify.candidates)) {
+                issues.push(malformed('clarify.candidates', '`clarify.candidates` must be an array (empty is fine — an open question is still a question).'));
+            }
+        }
+    }
+    // ── render ──
+    const render = value.render;
+    if (render !== undefined) {
+        if (!isPlainObject(render)) {
+            issues.push(malformed('render', '`render` must be an object ({ default, columns?, sort?, filter_note?, chart_hint? }).'));
+        }
+        else {
+            for (const key of Object.keys(render)) {
+                if (!RENDER_KEYS.has(key))
+                    issues.push(malformed(`render.${key}`, `\`render.${key}\` is not a render hint.`));
+            }
+            if (!isNonEmptyString(render.default)) {
+                issues.push(malformed('render.default', "`render.default` must name the default presentation ('table', 'chart', 'prose', …)."));
+            }
+            if (render.columns !== undefined &&
+                (!Array.isArray(render.columns) ||
+                    render.columns.length === 0 ||
+                    !render.columns.every(isNonEmptyString))) {
+                issues.push(malformed('render.columns', '`render.columns` must be a non-empty array of column names or omitted.'));
+            }
+            for (const key of ['sort', 'filter_note', 'chart_hint']) {
+                if (render[key] !== undefined && !isNonEmptyString(render[key])) {
+                    issues.push(malformed(`render.${key}`, `\`render.${key}\` must be a non-empty string or omitted.`));
+                }
+            }
+        }
+    }
+    // ── note ──
+    if (value.note !== undefined && typeof value.note !== 'string') {
+        issues.push(malformed('note', "`note` is the library's static sentence — a string, or omitted."));
+    }
+    // ── the envelope must declare SOMETHING ──
+    if (series === undefined &&
+        facts === undefined &&
+        edges === undefined &&
+        (clarify === undefined || clarify === null)) {
+        issues.push(malformed(SEMANTICS_MARKER, 'declares nothing — an envelope needs data (series, facts or edges) or a question ' +
+            '(clarify). Caveats with nothing to caveat are not a result.'));
+    }
+    return issues;
+}
+/**
+ * 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 function semantic(decl) {
+    const fn = 'semantic';
+    // Deliberately not the isPlainObject guard: its predicate would REPLACE
+    // the declared field types with an index signature for the rest of the
+    // function (SemanticDeclaration is all-optional, hence assignable).
+    if (typeof decl !== 'object' || decl === null || Array.isArray(decl)) {
+        throw new Error(`${fn}: takes a declaration — { series?, facts?, edges?, grain?, provenance?, coverage?, ` +
+            `clarify?, render? } with at least one of series/facts/edges/clarify.`);
+    }
+    const DECL_KEYS = new Set([
+        'series',
+        'facts',
+        'edges',
+        'grain',
+        'provenance',
+        'coverage',
+        'clarify',
+        'render',
+    ]);
+    for (const key of Object.keys(decl)) {
+        if (DECL_KEYS.has(key))
+            continue;
+        if (key === 'not_covered') {
+            throw new Error(`${fn}: \`not_covered\` is derived, never declared — declare \`coverage\` ` +
+                `({ notChecked, cannotCover }) and the prose list is composed from it, so the two ` +
+                `can never disagree.`);
+        }
+        throw new Error(`${fn}: '${key}' is not a field this vocabulary has. The fields are: series, facts, ` +
+            `edges, grain, provenance, coverage, clarify, render.`);
+    }
+    // Coverage first — the coverage() vocabulary, normalized by the SAME
+    // validator the coverage()/absent() primitives use (one validator, three
+    // doors), then respelled snake_case for the rendered envelope.
+    let coverage;
+    if (decl.coverage !== undefined) {
+        if (!isPlainObject(decl.coverage)) {
+            throw new Error(`${fn}: \`coverage\` must be a { checked?, notChecked?, cannotCover? } declaration.`);
+        }
+        const cov = decl.coverage;
+        const checked = normalizeCoverageList(fn, 'checked', cov.checked, false);
+        const notChecked = normalizeCoverageList(fn, 'notChecked', cov.notChecked, false);
+        const cannotCover = normalizeCoverageList(fn, 'cannotCover', cov.cannotCover, true);
+        if (checked.length + notChecked.length + cannotCover.length === 0) {
+            throw new Error(`${fn}: \`coverage\` names no ground at all — declare at least one item across ` +
+                `checked/notChecked/cannotCover, or omit the field (absent means "not declared", ` +
+                `never "nothing there").`);
+        }
+        coverage = {
+            ...(checked.length > 0 && { checked }),
+            ...(notChecked.length > 0 && { not_checked: notChecked }),
+            ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
+        };
+    }
+    const notCovered = coverage !== undefined ? composeNotCovered(coverage) : [];
+    const candidate = {
+        [SEMANTICS_MARKER]: true,
+        ...(decl.series !== undefined && { series: [...decl.series] }),
+        ...(decl.facts !== undefined && { facts: [...decl.facts] }),
+        ...(decl.edges !== undefined && { edges: [...decl.edges] }),
+        ...(decl.grain !== undefined && { grain: { ...decl.grain } }),
+        ...(decl.provenance !== undefined && { provenance: { ...decl.provenance } }),
+        ...(coverage !== undefined && { coverage }),
+        ...(notCovered.length > 0 && { not_covered: notCovered }),
+        ...('clarify' in decl &&
+            decl.clarify !== undefined && {
+            clarify: decl.clarify === null ? null : copyClarify(decl.clarify),
+        }),
+        ...(decl.render !== undefined && { render: { ...decl.render } }),
+        note: SEMANTICS_NOTE,
+    };
+    // One rule set, one implementation: the mint judges its own candidate with
+    // the exact validator recognition and the gate use, and refuses the first
+    // fault at the call site.
+    const issues = semanticIssues(candidate);
+    if (issues.length > 0) {
+        const first = issues[0];
+        throw new Error(`${fn}: ${first.message} (field: ${first.field})`);
+    }
+    return candidate;
+}
+/**
+ * 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 function readSemantics(value) {
+    if (!isPlainObject(value) || value[SEMANTICS_MARKER] !== true)
+        return undefined;
+    if (semanticIssues(value).length > 0)
+        return undefined;
+    return value;
+}
+/**
+ * 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 function explainSemantics(value) {
+    if (!isPlainObject(value) || value[SEMANTICS_MARKER] !== true)
+        return undefined;
+    const issues = semanticIssues(value);
+    return issues.length > 0 ? issues : 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 function semanticsForModel(sem) {
+    return {
+        ...(sem.series !== undefined && { series: sem.series.map((p) => ({ ...p })) }),
+        ...(sem.facts !== undefined && { facts: sem.facts.map((f) => ({ ...f })) }),
+        ...(sem.edges !== undefined && { edges: sem.edges.map((e) => ({ ...e })) }),
+        ...(sem.grain !== undefined && { grain: { ...sem.grain } }),
+        ...(sem.provenance !== undefined && { provenance: { ...sem.provenance } }),
+        ...(sem.not_covered !== undefined &&
+            sem.not_covered.length > 0 && { not_covered: [...sem.not_covered] }),
+        ...(sem.clarify !== undefined &&
+            sem.clarify !== null && {
+            clarify: { question: sem.clarify.question, candidates: [...sem.clarify.candidates] },
+        }),
+        note: typeof sem.note === 'string' ? sem.note : SEMANTICS_NOTE,
+    };
+}
+/** 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 function coverageOfSemantics(sem) {
+    return {
+        checked: sem.coverage?.checked ?? [],
+        notChecked: sem.coverage?.not_checked ?? [],
+        cannotCover: sem.coverage?.cannot_cover ?? [],
+    };
+}
+//# sourceMappingURL=envelope.js.map

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

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

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

@@ -0,0 +1,11 @@
+/**
+ * semantics/format — rendering one {@link SemanticsReport} for a terminal.
+ *
+ * Pattern: the tool-lint `format.ts` sibling — pure string building, no IO.
+ * Role:    lib/ layer, pure.
+ * Emits:   N/A.
+ */
+import type { SemanticsReport } from './check.js';
+/** Render the report. Every finding names its tool and its field — the two
+ *  facts a build log must carry for the fix to be a one-line edit. */
+export declare function formatSemanticsReport(report: SemanticsReport): string;