agentfootprint 10.3.0 → 10.3.1

package/dist/semantics/envelope.js

@@ -0,0 +1,737 @@
+"use strict";
+/**
+ * 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; `describedResult()` 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 for authoring and recognition
+ *
+ * The mint 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.
+ *
+ * ## One authoring door, one unchanged wire
+ *
+ * `describedResult()` declares camelCase names, then `mintSemantics` applies
+ * the same rule set used to recognize stored snake_case envelopes. Validation
+ * and record reading keep one owner; old wire records never need an adapter.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coverageOfSemantics = exports.periodOfSemantics = exports.semanticsForModel = exports.explainSemantics = exports.readSemantics = exports.mintSemantics = exports.semanticIssues = exports.provenanceIssues = exports.composeNotCovered = exports.WIRE_SPELLING = exports.CLARIFY_DECLARATION_KEYS = exports.isCounterLookingAggregation = void 0;
+const items_js_1 = require("./coverage/items.js");
+const period_js_1 = require("./coverage/period.js");
+const refusal_js_1 = require("./coverage/refusal.js");
+const types_js_1 = require("./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. */
+function isCounterLookingAggregation(aggregation) {
+    const tokens = aggregation.toLowerCase().split(/[^a-z]+/);
+    return tokens.some((t) => types_js_1.COUNTER_AGGREGATION_WORDS.includes(t) ||
+        (t.endsWith('s') && types_js_1.COUNTER_AGGREGATION_WORDS.includes(t.slice(0, -1))));
+}
+exports.isCounterLookingAggregation = isCounterLookingAggregation;
+const ENVELOPE_KEYS = new Set([
+    types_js_1.SEMANTICS_MARKER,
+    'series',
+    'facts',
+    'edges',
+    'grain',
+    'provenance',
+    // Honesty step 7b: what the read behind the data covered in time. An OLDER
+    // reader refuses a whole envelope that carries it (this set is its law), so
+    // the changelog names the floor.
+    'period',
+    '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']);
+/**
+ * The keys a {@link SemanticClarify} has — spelled the same in declarations
+ * and recorded envelopes — tied to the type in BOTH directions.
+ */
+exports.CLARIFY_DECLARATION_KEYS = Object.keys({
+    question: true,
+    candidates: true,
+});
+const CLARIFY_KEYS = new Set(exports.CLARIFY_DECLARATION_KEYS);
+const RENDER_KEYS = new Set(['default', 'columns', 'sort', 'filter_note', 'chart_hint']);
+/** The wire's own spelling — what `semanticIssues`, recognition, the gate
+ *  speak. */
+exports.WIRE_SPELLING = {
+    is_counter: 'is_counter',
+    measured_at: 'measured_at',
+    age_seconds: 'age_seconds',
+    source_export_date: 'source_export_date',
+    filter_note: 'filter_note',
+    chart_hint: '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. */
+function composeNotCovered(coverage) {
+    const items = [...(coverage.not_checked ?? []), ...(coverage.cannot_cover ?? [])];
+    return items.map((i) => (i.why !== undefined ? `${i.what} — ${i.why}` : i.what));
+}
+exports.composeNotCovered = composeNotCovered;
+function malformed(field, message) {
+    return { code: 'malformed-semantics', field, message };
+}
+/**
+ * The fault for an EMPTY data list — `series: []`, `facts: []`, `edges: []` —
+ * which names the one door for "nothing matched": `absent()`.
+ *
+ * The rule itself is unchanged (a data list is never empty, so "nothing
+ * matched" has exactly one door). What changed is the advice: it used to say
+ * "omit the field to say nothing", and following it on the found branch's
+ * only data field walked straight into the next refusal ("this result
+ * declares nothing"). And the fault is data-dependent — a tool with no empty
+ * branch passes every test that has rows and refuses on its first empty read
+ * in production, where the MODEL reads this text in place of the data — so it
+ * says the branch to write, in the author's own helper names. One core, so
+ * the declaration door and the `check:semantics` gate say the same.
+ */
+function emptyDataList(field) {
+    return malformed(field, `\`${field}\` is empty — if nothing matched, return absent({ what, checked }) instead.`);
+}
+/**
+ * Detach one declared data list (`series`, `facts`, `edges`) for the candidate
+ * envelope. A list — or any other iterable a plain-JavaScript author handed
+ * over, which always minted — is copied into a fresh array. A value that is
+ * NOT a list passes through untouched so the rule set names it for what it is:
+ * a spread would have thrown a `TypeError` on a plain object or a number (a
+ * crash that does not read as a refusal, in the one place the model reads
+ * it), and turned a string into its characters, refused as a malformed ROW.
+ */
+function copyDataList(value) {
+    if (typeof value === 'string' || typeof value !== 'object' || value === null)
+        return value;
+    const iterate = value[Symbol.iterator];
+    return typeof iterate === 'function' ? [...value] : value;
+}
+/** 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;
+}
+/**
+ * THE provenance rule — one present `provenance` object, in the wire's
+ * spelling, judged; every fault, each naming its field the way `s` spells it.
+ * `issuesIn` asks it for a described result, and `coverage/absent.ts` asks it
+ * for an absence's `provenance` (honesty step 7b), so the two doors cannot
+ * disagree about what a well-formed source and time is: `measured_at` and
+ * `source` required, `age_seconds` a finite number ≥ 0, `source_export_date`
+ * a non-empty string, no other key.
+ */
+function provenanceIssues(provenance, s) {
+    const measuredAt = s.measured_at;
+    const ageSeconds = s.age_seconds;
+    const sourceExportDate = s.source_export_date;
+    if (!isPlainObject(provenance)) {
+        return [
+            malformed('provenance', `\`provenance\` must be an object ({ ${measuredAt}, source, ${ageSeconds}?, ${sourceExportDate}? }).`),
+        ];
+    }
+    const issues = [];
+    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.${measuredAt}`,
+            message: `\`provenance.${measuredAt}\` 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.${ageSeconds}`, `\`provenance.${ageSeconds}\` must be a finite number ≥ 0 or omitted.`));
+    }
+    if (provenance.source_export_date !== undefined &&
+        !isNonEmptyString(provenance.source_export_date)) {
+        issues.push(malformed(`provenance.${sourceExportDate}`, `\`provenance.${sourceExportDate}\` must be a non-empty string or omitted.`));
+    }
+    return issues;
+}
+exports.provenanceIssues = provenanceIssues;
+/**
+ * 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.
+ */
+function semanticIssues(value) {
+    return issuesIn(value, exports.WIRE_SPELLING);
+}
+exports.semanticIssues = semanticIssues;
+/**
+ * The rule set itself, over the wire-spelled `value`, naming each field the
+ * way `s` spells it. Recognition and the gate pass the wire's
+ * own spelling; `describedResult()` passes camelCase, so its author reads
+ * `grain.isCounter` for the field they wrote. Only the six {@link
+ * SpelledField}s differ, and only in the words — never in what is judged.
+ */
+function issuesIn(value, s) {
+    if (!isPlainObject(value)) {
+        return [malformed(types_js_1.SEMANTICS_MARKER, 'a semantic envelope is a plain object.')];
+    }
+    if (value[types_js_1.SEMANTICS_MARKER] !== true) {
+        return [
+            malformed(types_js_1.SEMANTICS_MARKER, `\`${types_js_1.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, `this result carries '${key}', which is not a field this vocabulary has. The ` +
+                `fields are: series, facts, edges, grain, provenance, period, 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(emptyDataList('series'));
+        }
+        else if (!Array.isArray(series)) {
+            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(emptyDataList('facts'));
+        }
+        else if (!Array.isArray(facts)) {
+            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(emptyDataList('edges'));
+        }
+        else if (!Array.isArray(edges)) {
+            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;
+    const isCounter = s.is_counter;
+    if (grain !== undefined) {
+        if (!isPlainObject(grain)) {
+            issues.push(malformed('grain', `\`grain\` must be an object ({ interval?, aggregation?, ${isCounter}?, 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.${isCounter}`, `\`grain.${isCounter}\` 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, ${isCounter}, 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.${isCounter}`,
+                    message: `grain.aggregation is '${grain.aggregation.trim()}', which is counter-looking, and ` +
+                        `\`${isCounter}\` is not stated. Summing counters double-counts, and a reader cannot ` +
+                        `tell a counter from a gauge by looking at a number — state \`${isCounter}: true\` or ` +
+                        `\`${isCounter}: false\`.`,
+                });
+            }
+        }
+    }
+    // ── provenance ── (the ONE rule, `provenanceIssues`, which `absent()` asks too)
+    const provenance = value.provenance;
+    const hasData = series !== undefined || facts !== undefined;
+    if (provenance !== undefined) {
+        issues.push(...provenanceIssues(provenance, s));
+    }
+    else if (hasData) {
+        issues.push({
+            code: 'data-without-provenance',
+            field: 'provenance',
+            message: `this result carries series/facts with no \`provenance\` — \`provenance.${s.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.',
+        });
+    }
+    // ── period ── (honesty step 7b — the ONE rule, `coverage/period.ts` · `periodProblem`).
+    // Judged in the WIRE's spelling whatever the door: the candidate a mint judges
+    // carries a period `mintPeriod` already refused in its author's words, so a
+    // fault here is always one read off an envelope minted elsewhere.
+    if (value.period !== undefined) {
+        const problem = (0, period_js_1.periodProblem)(value.period, 'wire');
+        if (problem !== undefined)
+            issues.push(malformed(problem.field, problem.message));
+    }
+    // ── series ⇒ grain ──
+    if (series !== undefined && grain === undefined) {
+        issues.push({
+            code: 'series-without-grain',
+            field: 'grain',
+            message: 'this result 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?, ${s.filter_note}?, ${s.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, spelled] of [
+                ['sort', 'sort'],
+                ['filter_note', s.filter_note],
+                ['chart_hint', s.chart_hint],
+            ]) {
+                if (render[key] !== undefined && !isNonEmptyString(render[key])) {
+                    issues.push(malformed(`render.${spelled}`, `\`render.${spelled}\` 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(types_js_1.SEMANTICS_MARKER, 'this result 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;
+}
+/**
+ * The declared `coverage`, normalized by the SAME validator the
+ * `coverage()`/`absent()` primitives use (one validator, three doors), then
+ * respelled snake_case for the rendered envelope. `undefined` when none was
+ * declared.
+ */
+function mintedCoverage(declared) {
+    if (declared === undefined)
+        return undefined;
+    if (!isPlainObject(declared)) {
+        throw (0, refusal_js_1.refusal)(`\`coverage\` must be a { checked?, notChecked?, cannotCover? } declaration.`);
+    }
+    const cov = declared;
+    const checked = (0, items_js_1.normalizeCoverageList)('checked', cov.checked, false);
+    const notChecked = (0, items_js_1.normalizeCoverageList)('notChecked', cov.notChecked, false);
+    const cannotCover = (0, items_js_1.normalizeCoverageList)('cannotCover', cov.cannotCover, true);
+    if (checked.length + notChecked.length + cannotCover.length === 0) {
+        throw (0, refusal_js_1.refusal)(`\`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").`);
+    }
+    return {
+        ...(checked.length > 0 && { checked }),
+        ...(notChecked.length > 0 && { not_checked: notChecked }),
+        ...(cannotCover.length > 0 && { cannot_cover: cannotCover }),
+    };
+}
+/**
+ * The ONE mint behind `describedResult()`. Refuses (throws, at the call site — the `absent()` law) any
+ * declaration this vocabulary cannot honor, in the door's own words; returns
+ * the rendered envelope otherwise.
+ *
+ * In order: the declaration must be an object; a hand-written `not_covered`
+ * is refused as derived; every key the declaration and its objects carry must
+ * be one the door reads (a casing slip names the spelling meant); coverage is
+ * normalized; the candidate is built in the WIRE spelling; and the whole rule
+ * set judges it, naming each field as the door's author spelled it.
+ */
+function mintSemantics(decl, door) {
+    // Deliberately not the isPlainObject guard: its predicate would REPLACE
+    // the declared field types with an index signature for the rest of the
+    // function (each declaration type is assignable to it, so it narrows).
+    if (typeof decl !== 'object' || decl === null || Array.isArray(decl)) {
+        // The accepted fields come from the authoring vocabulary itself.
+        const fields = door.declarationKeys.map((key) => `${key}?`).join(', ');
+        throw (0, refusal_js_1.refusal)(`${door.name}() takes a declaration — { ${fields} } with at least one of ` +
+            `series/facts/edges/clarify.`);
+    }
+    const derived = door.derivedKeys.find((key) => Object.prototype.hasOwnProperty.call(decl, key));
+    if (derived !== undefined) {
+        throw (0, refusal_js_1.refusal)(`\`${derived}\` is derived, never declared — declare \`coverage\` ` +
+            `({ notChecked, cannotCover }) and the prose list is composed from it, so the two ` +
+            `can never disagree.`);
+    }
+    (0, refusal_js_1.refuseUnknownKeys)(decl, door.declarationKeys);
+    for (const [field, known] of door.objectKeys) {
+        const nested = decl[field];
+        if (isPlainObject(nested))
+            (0, refusal_js_1.refuseUnknownKeys)(nested, known, field);
+    }
+    const coverage = mintedCoverage(decl.coverage);
+    const notCovered = coverage !== undefined ? composeNotCovered(coverage) : [];
+    // Honesty step 7b: a top-level `period`, minted by the ONE period rule set
+    // (refused in the author's own camelCase words).
+    const period = 'period' in decl ? (0, period_js_1.mintPeriod)(decl.period) : undefined;
+    const candidate = {
+        [types_js_1.SEMANTICS_MARKER]: true,
+        ...(decl.series !== undefined && { series: copyDataList(decl.series) }),
+        ...(decl.facts !== undefined && { facts: copyDataList(decl.facts) }),
+        ...(decl.edges !== undefined && { edges: copyDataList(decl.edges) }),
+        ...(decl.grain !== undefined && { grain: door.toWire('grain', decl.grain) }),
+        ...(decl.provenance !== undefined && {
+            provenance: door.toWire('provenance', decl.provenance),
+        }),
+        ...(period !== undefined && { period }),
+        ...(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: door.toWire('render', decl.render) }),
+        note: types_js_1.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 — in the words the door's author wrote.
+    const issues = issuesIn(candidate, door.spelling);
+    if (issues.length > 0) {
+        const first = issues[0];
+        throw (0, refusal_js_1.refusal)(`${first.message} (field: ${first.field})`);
+    }
+    return candidate;
+}
+exports.mintSemantics = mintSemantics;
+/**
+ * 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.
+ */
+function readSemantics(value) {
+    if (!isPlainObject(value) || value[types_js_1.SEMANTICS_MARKER] !== true)
+        return undefined;
+    if (semanticIssues(value).length > 0)
+        return undefined;
+    return value;
+}
+exports.readSemantics = readSemantics;
+/**
+ * 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.
+ */
+function explainSemantics(value) {
+    if (!isPlainObject(value) || value[types_js_1.SEMANTICS_MARKER] !== true)
+        return undefined;
+    const issues = semanticIssues(value);
+    return issues.length > 0 ? issues : undefined;
+}
+exports.explainSemantics = explainSemantics;
+// LENS · tool-result · persistent-history
+// reads: the declared ToolSemantics envelope only — a compact projection that may not overclaim coverage
+// law: may omit, never deny; every clause anchored to the call it was composed on.
+/**
+ * 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.
+ *
+ * The period is served as the tool declared it — plus, when the store did not
+ * hold all of the time the read asked about, the verdict word inside it and
+ * that word's one clause after the note (`coverage/period.ts` ·
+ * `servedPeriod`; honesty step 7b, bench round 1). A `covered` period and an
+ * envelope with none are served byte for byte as before.
+ */
+function semanticsForModel(sem) {
+    const served = (0, period_js_1.servedPeriod)(sem.period);
+    const note = typeof sem.note === 'string' ? sem.note : types_js_1.SEMANTICS_NOTE;
+    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 } }),
+        // Served as the tool declared it (honesty step 7b), with the verdict word
+        // when the store did not hold all of it.
+        ...(sem.period !== undefined && {
+            period: served?.period ?? periodOnWireCopy(sem.period),
+        }),
+        ...(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: served === undefined ? note : (0, period_js_1.noteWithClause)(note, served.clause),
+    };
+}
+exports.semanticsForModel = semanticsForModel;
+/** A wire period as detached plain data — the projection's copy. */
+function periodOnWireCopy(period) {
+    return {
+        queried: { from: period.queried.from, to: period.queried.to },
+        held: period.held === 'unknown' ? 'unknown' : { from: period.held.from, to: period.held.to },
+        ...(period.read_at !== undefined && { read_at: period.read_at }),
+    };
+}
+/**
+ * The period a RECOGNIZED envelope declared, in the record's camelCase form
+ * (honesty step 7b) — `undefined` when it declared none. Recognition already
+ * held the period to the rule set (a fault keeps the whole envelope data), so
+ * this is a read, never a judgement.
+ */
+function periodOfSemantics(sem) {
+    const read = (0, period_js_1.readPeriod)(sem.period);
+    return read.period === undefined ? undefined : (0, period_js_1.copyPeriod)(read.period);
+}
+exports.periodOfSemantics = periodOfSemantics;
+/** 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. */
+function coverageOfSemantics(sem) {
+    return {
+        checked: sem.coverage?.checked ?? [],
+        notChecked: sem.coverage?.not_checked ?? [],
+        cannotCover: sem.coverage?.cannot_cover ?? [],
+    };
+}
+exports.coverageOfSemantics = coverageOfSemantics;
+//# sourceMappingURL=envelope.js.map