dsh-data-quality 0.1.0

package/lib/types/dataset.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Dataset loading for `dsh-data-quality`: workspace-confined path resolution,
+ * size/row guards, and deterministic parsers for CSV/TSV/JSON/JSONL. All
+ * parsing is hand-rolled (no external runtime dependencies) and bounded by
+ * the resolved config; oversized inputs reject loudly with actionable hints.
+ * @module dsh-data-quality/dataset
+ */
+import type { JsonValue } from '@deepseek-ai/dsh-session';
+import type { ResolvedConfig } from './config.js';
+/** One cell of a tabular dataset: a JSON scalar, `null` for missing, or a nested JSON value (document rows). */
+export type Cell = JsonValue;
+/** One dataset row keyed by column name. */
+export type Row = Record<string, Cell>;
+/** A tabular dataset: ordered columns plus rows. */
+export interface Table {
+    /** Column names in file order. */
+    readonly columns: string[];
+    /** Rows, each carrying every declared column (missing cells are `null`). */
+    readonly rows: Row[];
+}
+/** The root form a document load returns (citation checking walks this). */
+export type DocumentRoot = {
+    readonly kind: 'table';
+    readonly columns: string[];
+    readonly rows: Row[];
+} | {
+    readonly kind: 'json';
+    readonly value: unknown;
+};
+/** Raised for every user-facing dataset failure; `code` is stable for tests and tooling. */
+export declare class DatasetError extends Error {
+    readonly code: 'path-escape' | 'extension-denied' | 'not-found' | 'too-large' | 'too-many-rows' | 'malformed' | 'not-tabular';
+    /**
+     * @param code - stable machine-readable reason.
+     * @param message - actionable human-readable detail.
+     */
+    constructor(code: 'path-escape' | 'extension-denied' | 'not-found' | 'too-large' | 'too-many-rows' | 'malformed' | 'not-tabular', message: string);
+}
+/**
+ * Resolve `requested` inside `root`, rejecting escapes and disallowed
+ * extensions. Both sides go through `path.resolve` before comparison so
+ * Windows backslash/forward-slash mixes never defeat the containment check.
+ * @param root - absolute workspace root.
+ * @param requested - the caller-supplied path (relative to root, or absolute inside root).
+ * @param config - resolved config (extension allowlist).
+ * @returns the normalized absolute path inside `root`.
+ */
+export declare function resolveWorkspacePath(root: string, requested: string, config: ResolvedConfig): string;
+/**
+ * Short deterministic fingerprint of a dataset path, used in storage keys.
+ * @param datasetPath - the workspace-relative dataset path as callers gave it.
+ * @returns an 8-hex-char fingerprint.
+ */
+export declare function pathFingerprint(datasetPath: string): string;
+/** Assert the abort signal has not fired; throws the signal reason otherwise. */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;
+/**
+ * Read a dataset file under the size cap.
+ * @param absolutePath - normalized absolute path (from {@link resolveWorkspacePath}).
+ * @param config - resolved config (size cap).
+ * @param signal - optional abort signal honored around the read.
+ * @returns the UTF-8 text.
+ */
+export declare function readDatasetText(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<string>;
+/**
+ * Parse CSV/TSV text (RFC-4180-style: quoted fields, `""` escapes, CRLF/LF).
+ * The first record is the header; short records pad with `null`, long records
+ * fail loud. An empty field parses as `null` (missing).
+ * @param text - file text.
+ * @param delimiter - field delimiter (`,` or tab).
+ * @param config - resolved config (row cap).
+ * @param signal - optional abort signal, checked per 1024-record stride.
+ * @returns the parsed table.
+ */
+export declare function parseDelimited(text: string, delimiter: string, config: ResolvedConfig, signal?: AbortSignal): Table;
+/**
+ * Parse a JSON or JSONL text into a tabular dataset. JSON must be an array of
+ * flat objects; JSONL is one object per line. Non-scalar cell values are kept
+ * as-is (engines treat them as non-scalar).
+ * @param text - file text.
+ * @param extension - `.json` or `.jsonl`.
+ * @param config - resolved config (row cap).
+ * @param signal - optional abort signal.
+ * @returns the parsed table.
+ */
+export declare function parseJsonTable(text: string, extension: string, config: ResolvedConfig, signal?: AbortSignal): Table;
+/**
+ * Load a tabular dataset from a file already resolved inside the workspace.
+ * @param absolutePath - normalized absolute dataset path.
+ * @param config - resolved config.
+ * @param signal - optional abort signal.
+ * @returns the parsed table.
+ */
+export declare function loadTable(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<Table>;
+/**
+ * Load a dataset as a citation-checkable document root: CSV/TSV become
+ * `{ columns, rows }` (so `rows[3].nav` resolves), JSON is the parsed value,
+ * JSONL is the array of parsed lines.
+ * @param absolutePath - normalized absolute dataset path.
+ * @param config - resolved config.
+ * @param signal - optional abort signal.
+ * @returns the document root.
+ */
+export declare function loadDocument(absolutePath: string, config: ResolvedConfig, signal?: AbortSignal): Promise<DocumentRoot>;
+/**
+ * Deterministic systematic sample: every `ceil(total / count)`-th row from
+ * index 0. No clock, no RNG — the same input always yields the same sample.
+ * @param rows - full row list.
+ * @param count - requested sample size.
+ * @returns the sampled rows (identity when `count >= rows.length`).
+ */
+export declare function sampleRows(rows: Row[], count: number): Row[];
+/**
+ * Missingness: `null`, `undefined`, or a string empty after trimming. A
+ * whitespace-only cell counts as missing even before any `trim` clean rule.
+ * @param cell - the cell to test (`undefined` when the column is absent).
+ * @returns whether the cell is missing.
+ */
+export declare function isMissing(cell: Cell | undefined): boolean;
+/** Strict full-string numeric parse (no thousands separators, no unit suffixes). */
+export declare function parseNumeric(cell: Cell | undefined): number | undefined;
+/**
+ * Deterministic date parse to epoch milliseconds. Accepts `YYYY-MM-DD`,
+ * `YYYY/MM/DD`, and ISO-like datetimes (date-only forms read as UTC midnight).
+ * Calendar-invalid dates (e.g. 2025-13-40) reject. Returns `undefined` when
+ * the cell is not a recognized date.
+ * @param cell - the cell to parse (`undefined` when the column is absent).
+ * @returns epoch milliseconds, or `undefined`.
+ */
+export declare function parseDate(cell: Cell | undefined): number | undefined;
+/** Boolean parse: true/false/yes/no/1/0, case-insensitive. */
+export declare function parseBoolean(cell: Cell | undefined): boolean | undefined;
+//# sourceMappingURL=dataset.d.ts.map

package/lib/types/dataset.d.ts.map

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

package/lib/types/dataset.js

@@ -0,0 +1,404 @@
+/**
+ * Dataset loading for `dsh-data-quality`: workspace-confined path resolution,
+ * size/row guards, and deterministic parsers for CSV/TSV/JSON/JSONL. All
+ * parsing is hand-rolled (no external runtime dependencies) and bounded by
+ * the resolved config; oversized inputs reject loudly with actionable hints.
+ * @module dsh-data-quality/dataset
+ */
+import { open, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+/** Raised for every user-facing dataset failure; `code` is stable for tests and tooling. */
+export class DatasetError extends Error {
+    code;
+    /**
+     * @param code - stable machine-readable reason.
+     * @param message - actionable human-readable detail.
+     */
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'DatasetError';
+    }
+}
+/**
+ * Resolve `requested` inside `root`, rejecting escapes and disallowed
+ * extensions. Both sides go through `path.resolve` before comparison so
+ * Windows backslash/forward-slash mixes never defeat the containment check.
+ * @param root - absolute workspace root.
+ * @param requested - the caller-supplied path (relative to root, or absolute inside root).
+ * @param config - resolved config (extension allowlist).
+ * @returns the normalized absolute path inside `root`.
+ */
+export function resolveWorkspacePath(root, requested, config) {
+    if (requested.trim() === '') {
+        throw new DatasetError('path-escape', 'dataset path must not be empty');
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(resolvedRoot, requested);
+    if (resolved !== resolvedRoot && !resolved.startsWith(resolvedRoot + path.sep)) {
+        throw new DatasetError('path-escape', `path ${JSON.stringify(requested)} resolves outside the workspace root ${JSON.stringify(resolvedRoot)}`);
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    if (!config.allowedExtensions.includes(ext)) {
+        throw new DatasetError('extension-denied', `extension ${JSON.stringify(ext)} is not in allowedExtensions (${config.allowedExtensions.join(', ')})`);
+    }
+    return resolved;
+}
+/**
+ * Short deterministic fingerprint of a dataset path, used in storage keys.
+ * @param datasetPath - the workspace-relative dataset path as callers gave it.
+ * @returns an 8-hex-char fingerprint.
+ */
+export function pathFingerprint(datasetPath) {
+    return createHash('sha256').update(datasetPath).digest('hex').slice(0, 8);
+}
+/** Assert the abort signal has not fired; throws the signal reason otherwise. */
+export function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw signal.reason instanceof Error ? signal.reason : new Error('operation aborted');
+    }
+}
+/**
+ * Read a dataset file under the size cap.
+ * @param absolutePath - normalized absolute path (from {@link resolveWorkspacePath}).
+ * @param config - resolved config (size cap).
+ * @param signal - optional abort signal honored around the read.
+ * @returns the UTF-8 text.
+ */
+export async function readDatasetText(absolutePath, config, signal) {
+    throwIfAborted(signal);
+    let info;
+    try {
+        info = await stat(absolutePath);
+    }
+    catch {
+        throw new DatasetError('not-found', `dataset file not found: ${absolutePath}`);
+    }
+    if (!info.isFile()) {
+        throw new DatasetError('not-found', `dataset path is not a file: ${absolutePath}`);
+    }
+    const capBytes = config.maxFileSizeMB * 1024 * 1024;
+    if (info.size > capBytes) {
+        throw new DatasetError('too-large', `dataset is ${(info.size / 1024 / 1024).toFixed(1)} MiB, above the ${config.maxFileSizeMB} MiB cap; split the file or raise maxFileSizeMB`);
+    }
+    const handle = await open(absolutePath, 'r');
+    try {
+        throwIfAborted(signal);
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Parse CSV/TSV text (RFC-4180-style: quoted fields, `""` escapes, CRLF/LF).
+ * The first record is the header; short records pad with `null`, long records
+ * fail loud. An empty field parses as `null` (missing).
+ * @param text - file text.
+ * @param delimiter - field delimiter (`,` or tab).
+ * @param config - resolved config (row cap).
+ * @param signal - optional abort signal, checked per 1024-record stride.
+ * @returns the parsed table.
+ */
+export function parseDelimited(text, delimiter, config, signal) {
+    const records = [];
+    let field = '';
+    let record = [];
+    let inQuotes = false;
+    const pushField = () => {
+        record.push(field);
+        field = '';
+    };
+    const pushRecord = () => {
+        pushField();
+        // Skip truly blank lines (a record of one empty field), as RFC-4180
+        // writers commonly emit a trailing empty line.
+        if (record.length === 1 && record[0] === '') {
+            record = [];
+            field = '';
+            return;
+        }
+        records.push(record);
+        record = [];
+        if (records.length % 1024 === 0)
+            throwIfAborted(signal);
+        if (records.length - 1 > config.maxRows) {
+            throw new DatasetError('too-many-rows', `dataset exceeds the ${config.maxRows} row cap; use the sample parameter or raise maxRows`);
+        }
+    };
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (inQuotes) {
+            if (char === '"') {
+                if (text[index + 1] === '"') {
+                    field += '"';
+                    index += 2;
+                    continue;
+                }
+                inQuotes = false;
+                index += 1;
+                continue;
+            }
+            field += char;
+            index += 1;
+            continue;
+        }
+        if (char === '"') {
+            inQuotes = true;
+            index += 1;
+            continue;
+        }
+        if (char === delimiter) {
+            pushField();
+            index += 1;
+            continue;
+        }
+        if (char === '\r') {
+            index += 1;
+            continue;
+        }
+        if (char === '\n') {
+            pushRecord();
+            index += 1;
+            continue;
+        }
+        field += char;
+        index += 1;
+    }
+    if (field !== '' || record.length > 0)
+        pushRecord();
+    const header = records[0];
+    if (header === undefined || (header.length === 1 && header[0] === '')) {
+        throw new DatasetError('malformed', 'dataset has no header row');
+    }
+    const columns = header.map((name) => name.trim());
+    if (columns.some((name) => name === '')) {
+        throw new DatasetError('malformed', 'header contains an empty column name');
+    }
+    if (new Set(columns).size !== columns.length) {
+        throw new DatasetError('malformed', 'header contains duplicate column names');
+    }
+    const rows = [];
+    for (let i = 1; i < records.length; i++) {
+        const cells = records[i];
+        if (cells.length > columns.length) {
+            throw new DatasetError('malformed', `row ${i + 1} has ${cells.length} fields but the header has ${columns.length}`);
+        }
+        const out = {};
+        for (let c = 0; c < columns.length; c++) {
+            const raw = cells[c];
+            out[columns[c]] = raw === undefined || raw === '' ? null : raw;
+        }
+        rows.push(out);
+    }
+    return { columns, rows };
+}
+/**
+ * Parse a JSON or JSONL text into a tabular dataset. JSON must be an array of
+ * flat objects; JSONL is one object per line. Non-scalar cell values are kept
+ * as-is (engines treat them as non-scalar).
+ * @param text - file text.
+ * @param extension - `.json` or `.jsonl`.
+ * @param config - resolved config (row cap).
+ * @param signal - optional abort signal.
+ * @returns the parsed table.
+ */
+export function parseJsonTable(text, extension, config, signal) {
+    const values = extension === '.jsonl' ? parseJsonLines(text) : parseJsonDocument(text);
+    const items = Array.isArray(values) ? values : [values];
+    if (items.length > config.maxRows) {
+        throw new DatasetError('too-many-rows', `dataset exceeds the ${config.maxRows} row cap; use the sample parameter or raise maxRows`);
+    }
+    const rows = [];
+    const columns = [];
+    const seen = new Set();
+    for (const [index, item] of items.entries()) {
+        if (index % 1024 === 0)
+            throwIfAborted(signal);
+        if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+            throw new DatasetError('not-tabular', `row ${index + 1} is not a flat object; profiling/cleaning/verification need a tabular dataset (array of objects)`);
+        }
+        const row = item;
+        for (const key of Object.keys(row)) {
+            if (!seen.has(key)) {
+                seen.add(key);
+                columns.push(key);
+            }
+        }
+        rows.push(row);
+    }
+    return { columns, rows: rows.map((row) => normalizeRow(row, columns)) };
+}
+/** Fill absent columns with `null` so every row carries every column. */
+function normalizeRow(row, columns) {
+    const out = {};
+    for (const column of columns) {
+        const value = row[column];
+        out[column] = value === undefined ? null : value;
+    }
+    return out;
+}
+/** Parse one JSON document; failures become a loud malformed error. */
+function parseJsonDocument(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new DatasetError('malformed', `invalid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Parse JSONL (one JSON value per non-empty line); failures name the line. */
+function parseJsonLines(text) {
+    const out = [];
+    const lines = text.split(/\r?\n/u);
+    for (const [index, line] of lines.entries()) {
+        if (line.trim() === '')
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            throw new DatasetError('malformed', `invalid JSON on line ${index + 1}`);
+        }
+    }
+    return out;
+}
+/**
+ * Load a tabular dataset from a file already resolved inside the workspace.
+ * @param absolutePath - normalized absolute dataset path.
+ * @param config - resolved config.
+ * @param signal - optional abort signal.
+ * @returns the parsed table.
+ */
+export async function loadTable(absolutePath, config, signal) {
+    const text = await readDatasetText(absolutePath, config, signal);
+    const ext = path.extname(absolutePath).toLowerCase();
+    throwIfAborted(signal);
+    if (ext === '.csv')
+        return parseDelimited(text, ',', config, signal);
+    if (ext === '.tsv')
+        return parseDelimited(text, '\t', config, signal);
+    return parseJsonTable(text, ext, config, signal);
+}
+/**
+ * Load a dataset as a citation-checkable document root: CSV/TSV become
+ * `{ columns, rows }` (so `rows[3].nav` resolves), JSON is the parsed value,
+ * JSONL is the array of parsed lines.
+ * @param absolutePath - normalized absolute dataset path.
+ * @param config - resolved config.
+ * @param signal - optional abort signal.
+ * @returns the document root.
+ */
+export async function loadDocument(absolutePath, config, signal) {
+    const ext = path.extname(absolutePath).toLowerCase();
+    if (ext === '.json') {
+        const text = await readDatasetText(absolutePath, config, signal);
+        return { kind: 'json', value: parseJsonDocument(text) };
+    }
+    if (ext === '.jsonl') {
+        const text = await readDatasetText(absolutePath, config, signal);
+        return { kind: 'json', value: parseJsonLines(text) };
+    }
+    const table = await loadTable(absolutePath, config, signal);
+    return { kind: 'table', columns: table.columns, rows: table.rows };
+}
+/**
+ * Deterministic systematic sample: every `ceil(total / count)`-th row from
+ * index 0. No clock, no RNG — the same input always yields the same sample.
+ * @param rows - full row list.
+ * @param count - requested sample size.
+ * @returns the sampled rows (identity when `count >= rows.length`).
+ */
+export function sampleRows(rows, count) {
+    if (!Number.isSafeInteger(count) || count <= 0) {
+        throw new DatasetError('malformed', `sample must be a positive integer, got ${String(count)}`);
+    }
+    if (count >= rows.length)
+        return rows;
+    const stride = Math.ceil(rows.length / count);
+    const out = [];
+    for (let i = 0; i < rows.length; i += stride) {
+        out.push(rows[i]);
+    }
+    return out;
+}
+/**
+ * Missingness: `null`, `undefined`, or a string empty after trimming. A
+ * whitespace-only cell counts as missing even before any `trim` clean rule.
+ * @param cell - the cell to test (`undefined` when the column is absent).
+ * @returns whether the cell is missing.
+ */
+export function isMissing(cell) {
+    if (cell === null || cell === undefined)
+        return true;
+    if (typeof cell === 'string')
+        return cell.trim() === '';
+    return false;
+}
+/** Strict full-string numeric parse (no thousands separators, no unit suffixes). */
+export function parseNumeric(cell) {
+    if (typeof cell === 'number')
+        return Number.isFinite(cell) ? cell : undefined;
+    if (typeof cell !== 'string')
+        return undefined;
+    const text = cell.trim();
+    if (text === '')
+        return undefined;
+    if (!/^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/u.test(text))
+        return undefined;
+    const value = Number(text);
+    return Number.isFinite(value) ? value : undefined;
+}
+const DATE_PATTERNS = [
+    /^(\d{4})-(\d{1,2})-(\d{1,2})$/u,
+    /^(\d{4})\/(\d{1,2})\/(\d{1,2})$/u,
+    /^(\d{4})-(\d{1,2})-(\d{1,2})[ T](\d{1,2}):(\d{2})(?::(\d{2}))?(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?$/u,
+];
+/**
+ * Deterministic date parse to epoch milliseconds. Accepts `YYYY-MM-DD`,
+ * `YYYY/MM/DD`, and ISO-like datetimes (date-only forms read as UTC midnight).
+ * Calendar-invalid dates (e.g. 2025-13-40) reject. Returns `undefined` when
+ * the cell is not a recognized date.
+ * @param cell - the cell to parse (`undefined` when the column is absent).
+ * @returns epoch milliseconds, or `undefined`.
+ */
+export function parseDate(cell) {
+    if (typeof cell !== 'string')
+        return undefined;
+    const text = cell.trim();
+    for (const pattern of DATE_PATTERNS) {
+        const match = pattern.exec(text);
+        if (match === null)
+            continue;
+        const year = Number(match[1]);
+        const month = Number(match[2]);
+        const day = Number(match[3]);
+        const hour = Number(match[4] ?? 0);
+        const minute = Number(match[5] ?? 0);
+        const second = Number(match[6] ?? 0);
+        if (month < 1 || month > 12 || day < 1 || day > 31 || hour > 23 || minute > 59 || second > 59)
+            return undefined;
+        const epoch = Date.UTC(year, month - 1, day, hour, minute, second);
+        const check = new Date(epoch);
+        if (check.getUTCMonth() !== month - 1 || check.getUTCDate() !== day)
+            return undefined;
+        return epoch;
+    }
+    return undefined;
+}
+/** Boolean parse: true/false/yes/no/1/0, case-insensitive. */
+export function parseBoolean(cell) {
+    if (typeof cell === 'boolean')
+        return cell;
+    if (typeof cell !== 'string')
+        return undefined;
+    const text = cell.trim().toLowerCase();
+    if (text === 'true' || text === 'yes' || text === '1')
+        return true;
+    if (text === 'false' || text === 'no' || text === '0')
+        return false;
+    return undefined;
+}
+//# sourceMappingURL=dataset.js.map

package/lib/types/dataset.js.map

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

package/lib/types/events.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The `data-quality/*` session-event vocabulary and its adaptive append gate.
+ * The vocabulary is declared on `SessionEventMap` for type-checked payloads;
+ * the runtime gate decides per host whether appending is safe:
+ *
+ * - Hosts whose known-type set already covers the vocabulary (a future harness
+ *   that adopts these events) append plainly.
+ * - Hosts with an `ignorable` append option (the master-build
+ *   `Session.append(type, data, { ignorable: true })` contract) append with the
+ *   marker, so builds that do not know the type skip the event on restore.
+ * - 0.1.0-rc.6 hosts have neither a registration surface nor the `ignorable`
+ *   append flag; appending an unknown type there would make the persistence
+ *   coordinator refuse the session log on restore, so the append is skipped
+ *   and the storage-domain report remains the durable copy.
+ * @module dsh-data-quality/events
+ */
+import { type Session } from '@deepseek-ai/dsh-session';
+/** Payload shared by every `data-quality/*` session event. */
+export interface DataQualityEventData {
+    /** Which run produced the event. */
+    readonly kind: 'profile' | 'clean' | 'verify';
+    /** Workspace-relative dataset path as the caller gave it. */
+    readonly dataset: string;
+    /** Storage-domain key of the full persisted report, when persistence is on. */
+    readonly reportKey?: string;
+    /** Compact run summary (small integers/booleans only). */
+    readonly summary: {
+        readonly rows: number;
+        readonly columns?: number;
+        readonly rules?: number;
+        readonly failedRules?: number;
+        readonly passed?: boolean;
+    };
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * A `data_profile` run completed.
+         * @mode emit
+         * @param data - run kind, dataset, optional report key, and compact summary.
+         */
+        'data-quality/profile': DataQualityEventData;
+        /**
+         * A `data_clean` run completed.
+         * @mode emit
+         * @param data - run kind, dataset, optional report key, and compact summary.
+         */
+        'data-quality/clean': DataQualityEventData;
+        /**
+         * A `data_verify` run completed.
+         * @mode emit
+         * @param data - run kind, dataset, optional report key, and compact summary.
+         */
+        'data-quality/verify': DataQualityEventData;
+    }
+}
+/** The event type vocabulary this plugin appends. */
+export declare const DATA_QUALITY_EVENT_TYPES: readonly ["data-quality/profile", "data-quality/clean", "data-quality/verify"];
+/** Union of the event types this plugin appends. */
+export type DataQualityEventType = (typeof DATA_QUALITY_EVENT_TYPES)[number];
+/**
+ * Append one `data-quality/*` event when the host can carry it safely; skip
+ * silently otherwise (the storage-domain report is always the durable copy).
+ * The `ignorable` probe reads the UNBOUND method's source (a `.bind()` result
+ * reports `[native code]`): the rc.6 build contains no `ignorable` handling
+ * while the master build references the flag by name; property names survive
+ * minification, so the probe fails safe (skips) rather than corrupting a log.
+ * @param session - the calling session.
+ * @param type - the event type.
+ * @param data - the payload.
+ */
+export declare function appendDataQualityEvent(session: Session, type: DataQualityEventType, data: DataQualityEventData): void;
+//# sourceMappingURL=events.d.ts.map

package/lib/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/events.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAA6B,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAElF,8DAA8D;AAC9D,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAA;IAC7C,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;QACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;QAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAC1B,CAAA;CACF;AAED,OAAO,QAAQ,gCAAgC,CAAC;IAC9C,UAAU,eAAe;QACvB;;;;WAIG;QACH,sBAAsB,EAAE,oBAAoB,CAAA;QAC5C;;;;WAIG;QACH,oBAAoB,EAAE,oBAAoB,CAAA;QAC1C;;;;WAIG;QACH,qBAAqB,EAAE,oBAAoB,CAAA;KAC5C;CACF;AAED,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,gFAAiF,CAAA;AAEtH,oDAAoD;AACpD,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAA;AAK5E;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,oBAAoB,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CASrH"}