@smart-data-engines/sde 0.1.0-dev.0

package/dist/model.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Declaring a model, and turning it into canonical bytes plus a version.
+ *
+ * The declaration is explicit because it has to be - see `types.ts`. What that buys, unexpectedly, is
+ * that this file is shorter and clearer than its Python counterpart: there is no annotation
+ * resolution, no forward references, no scope in which a name might or might not be visible. The
+ * whole class of bugs Python needed `localns` for does not exist here.
+ *
+ * Two rules from the contract run through everything below:
+ *
+ * - Arrays are sorted wherever order carries no meaning, **by code point**, not with `.sort()`.
+ * - Where order does carry meaning it is an explicit `position` inside each element. Composite keys
+ *   are the case that matters: `(tenant, id)` and `(id, tenant)` are different keys, and a reader
+ *   should not have to know which arrays here are load-bearing.
+ */
+import type { FieldType, NeutralType } from './types.js';
+/**
+ * The **IR's** format version, and the one the conformance vectors are pinned to.
+ *
+ * Separate from `MAP_CONTRACT` since the placement map gained a key the IR did not. One counter for
+ * two artefacts means every artefact's version moves when any one of them changes - and `contract`
+ * is *inside* the IR, whose digest is `model_version`, so bumping it for a change to the map format
+ * would give every client a new model version and invalidate every issued map. For a key in a
+ * different document.
+ */
+export declare const CONTRACT = 1;
+export interface FieldSpec {
+    readonly name: string;
+    readonly type: NeutralType;
+    readonly nullable: boolean;
+}
+export interface RelationSpec {
+    readonly name: string;
+    readonly source: string;
+    readonly target: string;
+}
+export interface EntitySpec {
+    readonly name: string;
+    readonly fields: readonly FieldSpec[];
+    readonly key: readonly string[];
+    readonly pii: readonly string[];
+    readonly residency: string | null;
+}
+export interface CostCeiling {
+    readonly amount: string;
+    readonly currency: string;
+}
+export interface LogicalModel {
+    readonly entities: readonly EntitySpec[];
+    readonly relations: readonly RelationSpec[];
+    readonly atomic: readonly (readonly string[])[];
+    readonly costCeiling: CostCeiling | null;
+    readonly ir: Record<string, unknown>;
+    readonly version: string;
+}
+/** What `entity()` takes. Everything except `fields` is optional, and absence means no constraint. */
+export interface EntityDeclaration {
+    readonly fields: Readonly<Record<string, FieldType>>;
+    readonly relations?: Readonly<Record<string, {
+        readonly to: string;
+    }>>;
+    readonly key?: readonly string[];
+    readonly pii?: readonly string[];
+    readonly residency?: string;
+    readonly atomicWith?: readonly string[];
+}
+export interface Entity extends EntityDeclaration {
+    readonly name: string;
+}
+/** Declare an entity. */
+export declare function entity(name: string, declaration: EntityDeclaration): Entity;
+/** Declare a relation target. `relations: { user: ref('User') }`. */
+export declare function ref(to: string): {
+    readonly to: string;
+};
+export declare function assemble(entities: readonly EntitySpec[], relations: readonly RelationSpec[], atomic: readonly (readonly string[])[], costCeiling: CostCeiling | null): LogicalModel;
+/** Build a model from declared entities. */
+export declare function buildModel(entities: readonly Entity[], options?: {
+    readonly costCeiling?: CostCeiling;
+}): LogicalModel;
+/**
+ * The model as the neutral form of format-contract §4a: the inverse of `modelFromNeutral`.
+ *
+ * It exists because the control plane takes a client's model as *that* document while a client
+ * declares it in whichever way their language is comfortable with. Without this, a client has to
+ * write their model a second time by hand, and the two copies then drift.
+ *
+ * **The IR is not this document.** They differ exactly where a key is written; see `checkShape` in
+ * the neutral loader.
+ */
+export declare function neutralDeclaration(model: LogicalModel): Record<string, unknown>;
+export declare function irBytes(model: LogicalModel): Buffer;
+export declare function entityOf(model: LogicalModel, name: string): EntitySpec;

package/dist/model.js

@@ -0,0 +1,313 @@
+/**
+ * Declaring a model, and turning it into canonical bytes plus a version.
+ *
+ * The declaration is explicit because it has to be - see `types.ts`. What that buys, unexpectedly, is
+ * that this file is shorter and clearer than its Python counterpart: there is no annotation
+ * resolution, no forward references, no scope in which a name might or might not be visible. The
+ * whole class of bugs Python needed `localns` for does not exist here.
+ *
+ * Two rules from the contract run through everything below:
+ *
+ * - Arrays are sorted wherever order carries no meaning, **by code point**, not with `.sort()`.
+ * - Where order does carry meaning it is an explicit `position` inside each element. Composite keys
+ *   are the case that matters: `(tenant, id)` and `(id, tenant)` are different keys, and a reader
+ *   should not have to know which arrays here are load-bearing.
+ */
+import { canonicalBytes, compareCodePoints, digest16 } from './canonical.js';
+import { DeclarationError } from './errors.js';
+import { checkType } from './types.js';
+/**
+ * The **IR's** format version, and the one the conformance vectors are pinned to.
+ *
+ * Separate from `MAP_CONTRACT` since the placement map gained a key the IR did not. One counter for
+ * two artefacts means every artefact's version moves when any one of them changes - and `contract`
+ * is *inside* the IR, whose digest is `model_version`, so bumping it for a change to the map format
+ * would give every client a new model version and invalidate every issued map. For a key in a
+ * different document.
+ */
+export const CONTRACT = 1;
+/** Declare an entity. */
+export function entity(name, declaration) {
+    if (!name)
+        throw new DeclarationError('an entity needs a name');
+    if (Object.keys(declaration.fields).length === 0) {
+        throw new DeclarationError(`${name} has no fields. An entity that stores nothing cannot be placed, and a relation-only ` +
+            'entity is usually a join table that wants to be one.');
+    }
+    return { name, ...declaration };
+}
+/** Declare a relation target. `relations: { user: ref('User') }`. */
+export function ref(to) {
+    return { to };
+}
+function resolveKey(ent, fieldNames) {
+    if (ent.key !== undefined) {
+        if (ent.key.length === 0)
+            throw new DeclarationError(`${ent.name}: key is empty`);
+        const missing = ent.key.filter((k) => !fieldNames.has(k));
+        if (missing.length > 0) {
+            throw new DeclarationError(`${ent.name}: key names ${JSON.stringify(missing)}, which are not fields of ${ent.name}. A ` +
+                'relation cannot be part of a key: the key has to be storable in the entity itself.');
+        }
+        return ent.key;
+    }
+    if (fieldNames.has('id'))
+        return ['id'];
+    throw new DeclarationError(`${ent.name} has no 'id' field and no key. Every entity needs a key: without one there is no ` +
+        'way to address a row, no way to migrate it and no way to verify a migration moved it.');
+}
+/**
+ * Merge pairwise `atomicWith` declarations into sorted groups.
+ *
+ * Symmetric even when declared on one side, and transitive: if A is atomic with B and B with C then
+ * all three commit together, because nothing else is implementable on one engine's transaction.
+ */
+function normaliseAtomic(entities) {
+    const parent = new Map();
+    for (const ent of entities)
+        parent.set(ent.name, ent.name);
+    const find = (x) => {
+        let cur = x;
+        while (parent.get(cur) !== cur) {
+            const next = parent.get(cur);
+            parent.set(cur, parent.get(next));
+            cur = parent.get(cur);
+        }
+        return cur;
+    };
+    const union = (a, b) => {
+        const ra = find(a);
+        const rb = find(b);
+        if (ra === rb)
+            return;
+        // Attach to the smaller root so the representative never depends on visit order.
+        const [small, large] = compareCodePoints(ra, rb) <= 0 ? [ra, rb] : [rb, ra];
+        parent.set(large, small);
+    };
+    const known = new Set(entities.map((e) => e.name));
+    const touched = new Set();
+    for (const ent of entities) {
+        for (const other of ent.atomicWith ?? []) {
+            if (!known.has(other)) {
+                throw new DeclarationError(`${ent.name}: atomicWith names ${JSON.stringify(other)}, which is not a declared entity`);
+            }
+            if (other === ent.name) {
+                throw new DeclarationError(`${ent.name}: atomicWith names itself, which says nothing`);
+            }
+            union(ent.name, other);
+            touched.add(ent.name);
+            touched.add(other);
+        }
+    }
+    const buckets = new Map();
+    for (const name of [...touched].sort(compareCodePoints)) {
+        const root = find(name);
+        const bucket = buckets.get(root);
+        if (bucket)
+            bucket.push(name);
+        else
+            buckets.set(root, [name]);
+    }
+    return [...buckets.values()]
+        .map((members) => [...members].sort(compareCodePoints))
+        .sort((a, b) => compareCodePoints(a[0], b[0]));
+}
+/** Assemble already-resolved specs into a model. Shared by `buildModel` and the vector loader. */
+/**
+ * The seven refusals of format-contract §4a, in the order that section writes them.
+ *
+ * Here rather than at each front door, because there are two - `buildModel` and the neutral-JSON
+ * loader the conformance vectors use - and each of them enforced a different subset. The vectors
+ * therefore ran a weaker validator than any application does, which is the suite's own failure
+ * mode: a vector that passes without reaching the code it describes takes the place of one that
+ * would have.
+ */
+function refuseADeclarationThatIsNotAModel(entities, relations) {
+    if (entities.length === 0) {
+        throw new DeclarationError('no entities declared, so there is no model to build');
+    }
+    const known = new Set();
+    for (const spec of entities) {
+        if (spec.fields.length === 0) {
+            throw new DeclarationError(`${spec.name} has no fields. An entity that stores nothing cannot be placed, so there is ` +
+                'nothing for a map to say about it.');
+        }
+        if (known.has(spec.name)) {
+            throw new DeclarationError(`two entities are called ${JSON.stringify(spec.name)}. Entity names reach the canonical ` +
+                "IR and the colocation graph, so a duplicate makes 'which entity is this' unanswerable " +
+                'in the document whose job is to answer it.');
+        }
+        known.add(spec.name);
+    }
+    const relationsOf = new Map();
+    for (const rel of relations) {
+        for (const side of [rel.source, rel.target]) {
+            if (!known.has(side)) {
+                throw new DeclarationError(`relation '${rel.name}' names unknown entity '${side}'`);
+            }
+        }
+        const named = relationsOf.get(rel.source) ?? new Set();
+        if (named.has(rel.name)) {
+            throw new DeclarationError(`${rel.source}.${rel.name} is declared twice. Two relations of one name on one entity are ` +
+                'two edges the colocation graph cannot tell apart.');
+        }
+        named.add(rel.name);
+        relationsOf.set(rel.source, named);
+    }
+    for (const spec of entities) {
+        const names = spec.fields.map((f) => f.name);
+        const duplicates = [...new Set(names.filter((n, i) => names.indexOf(n) !== i))].sort(compareCodePoints);
+        if (duplicates.length > 0) {
+            throw new DeclarationError(`${spec.name} declares the fields ${JSON.stringify(duplicates)} more than once. The ` +
+                "layout would have two columns of one name, and the refusal would arrive from the " +
+                'client\'s engine at CREATE TABLE.');
+        }
+        const known_fields = new Set(names);
+        if (spec.key.length === 0) {
+            throw new DeclarationError(`${spec.name} declares no key. A key is what makes a row addressable, migratable and ` +
+                'verifiable - a backfill compares rows by it - so an entity without one is a group that ' +
+                'cannot be moved, and that is worth knowing when the model is declared rather than in ' +
+                'the middle of a migration. No key is invented for you.');
+        }
+        const missing = spec.key.filter((k) => !known_fields.has(k));
+        if (missing.length > 0) {
+            throw new DeclarationError(`${spec.name}: key names ${JSON.stringify(missing)}, which are not fields of ${spec.name}`);
+        }
+        const repeated = [
+            ...new Set(spec.key.filter((k, i) => spec.key.indexOf(k) !== i)),
+        ].sort(compareCodePoints);
+        if (repeated.length > 0) {
+            throw new DeclarationError(`${spec.name}: key names ${JSON.stringify(repeated)} more than once, which is a ` +
+                'composite key with one column in two positions.');
+        }
+        const badPii = spec.pii.filter((f) => !known_fields.has(f));
+        if (badPii.length > 0) {
+            throw new DeclarationError(`${spec.name}: pii names ${JSON.stringify(badPii)}, which are not fields of ` +
+                `${spec.name}. A pii entry that is not a field silently protects nothing, and the ` +
+                'exclusion of personal data from a derived copy is meant to be readable rather than ' +
+                'trusted.');
+        }
+    }
+}
+export function assemble(entities, relations, atomic, costCeiling) {
+    refuseADeclarationThatIsNotAModel(entities, relations);
+    const specs = [...entities].sort((a, b) => compareCodePoints(a.name, b.name));
+    const rels = [...relations].sort((a, b) => compareCodePoints(a.source, b.source) ||
+        compareCodePoints(a.name, b.name) ||
+        compareCodePoints(a.target, b.target));
+    const ir = {
+        contract: CONTRACT,
+        entities: specs.map((s) => ({
+            name: s.name,
+            fields: [...s.fields]
+                .sort((a, b) => compareCodePoints(a.name, b.name))
+                .map((f) => ({ name: f.name, type: f.type, nullable: f.nullable })),
+            key: s.key.map((field, position) => ({ field, position })),
+            pii: [...s.pii].sort(compareCodePoints),
+            residency: s.residency,
+        })),
+        relations: rels.map((r) => ({ name: r.name, from: r.source, to: r.target })),
+        atomic: atomic.map((group) => [...group]),
+        cost_ceiling: costCeiling === null ? null : { ...costCeiling },
+    };
+    return {
+        entities: specs,
+        relations: rels,
+        atomic,
+        costCeiling,
+        ir,
+        version: digest16(ir),
+    };
+}
+/** Build a model from declared entities. */
+export function buildModel(entities, options = {}) {
+    if (entities.length === 0) {
+        throw new DeclarationError('no entities declared, so there is no model to build');
+    }
+    // Uniqueness, pii and the key are checked in `assemble` now, which both front doors go through.
+    // A guarantee that holds at one of two doors holds for one of two callers, and the conformance
+    // vectors come through the other one.
+    const names = new Set(entities.map((e) => e.name));
+    const specs = [];
+    const relations = [];
+    for (const ent of entities) {
+        const fieldNames = new Set(Object.keys(ent.fields));
+        const fields = Object.entries(ent.fields).map(([name, ft]) => ({
+            name,
+            type: checkType(ft.type, `${ent.name}.${name}`),
+            nullable: ft.nullable,
+        }));
+        for (const [name, relation] of Object.entries(ent.relations ?? {})) {
+            if (!names.has(relation.to)) {
+                throw new DeclarationError(`${ent.name}.${name} points at ${relation.to}, which is not a declared entity. Include ` +
+                    'it in the model you are building.');
+            }
+            // No refusal for a field and a relation sharing a name. This check used to be here and it
+            // contradicted the contract: §2a says the digest collision between the two is intended, and
+            // `hashing/003-reserved-object-keys` declares exactly that shape - so this library refused a
+            // model its own conformance vector pins. It is legal because a relation reaches a layout as
+            // `<relation>_<target key field>` and never under its own name, so there is no column for it
+            // to collide with.
+            relations.push({ name, source: ent.name, target: relation.to });
+        }
+        specs.push({
+            name: ent.name,
+            fields,
+            key: resolveKey(ent, fieldNames),
+            pii: ent.pii ?? [],
+            residency: ent.residency ?? null,
+        });
+    }
+    return assemble(specs, relations, normaliseAtomic(entities), options.costCeiling ?? null);
+}
+/**
+ * The model as the neutral form of format-contract §4a: the inverse of `modelFromNeutral`.
+ *
+ * It exists because the control plane takes a client's model as *that* document while a client
+ * declares it in whichever way their language is comfortable with. Without this, a client has to
+ * write their model a second time by hand, and the two copies then drift.
+ *
+ * **The IR is not this document.** They differ exactly where a key is written; see `checkShape` in
+ * the neutral loader.
+ */
+export function neutralDeclaration(model) {
+    const entities = model.entities.map((spec) => {
+        const entity = {
+            name: spec.name,
+            fields: spec.fields.map((f) => ({
+                name: f.name,
+                type: f.type,
+                ...(f.nullable ? { nullable: true } : {}),
+            })),
+            key: [...spec.key],
+        };
+        if (spec.pii.length > 0)
+            entity['pii'] = [...spec.pii];
+        if (spec.residency !== null)
+            entity['residency'] = spec.residency;
+        return entity;
+    });
+    const document = { entities };
+    if (model.relations.length > 0) {
+        document['relations'] = model.relations.map((r) => ({
+            name: r.name,
+            from: r.source,
+            to: r.target,
+        }));
+    }
+    if (model.atomic.length > 0)
+        document['atomic'] = model.atomic.map((g) => [...g]);
+    if (model.costCeiling !== null)
+        document['cost_ceiling'] = { ...model.costCeiling };
+    return document;
+}
+export function irBytes(model) {
+    return canonicalBytes(model.ir);
+}
+export function entityOf(model, name) {
+    const found = model.entities.find((e) => e.name === name);
+    if (!found)
+        throw new DeclarationError(`${name} is not in this model`);
+    return found;
+}
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

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

package/dist/physical.d.ts

@@ -0,0 +1,128 @@
+/**
+ * The physical design vocabulary a placement map can carry, and the rules each element obeys.
+ *
+ * Placement map contract 5 lets a layout say three things about storage beyond tables and column
+ * types: the physical order of an entity's key, a time partition, and indexes of a named method.
+ * They are chosen by the control plane and a library only renders them. Every element is a closed
+ * vocabulary rendered by this library; nothing in a map is pasted into DDL.
+ *
+ * This is the port of the reference's `sde/physical.py`, and it is one module for the reason that
+ * one is: the map parser, the DDL renderer and the adapters' verification all read it, because a
+ * second copy of "which index methods ClickHouse has" is how a map gets signed that no library can
+ * apply. The two data rules - a partition follows the key, and `key_order` only reorders the key -
+ * were measured on PostgreSQL 15.19 and ClickHouse 24.8.14.39 before they were written; the
+ * reference module carries the measurements.
+ */
+export declare const PHYSICAL_DESIGN_SINCE = 5;
+/** The placement map contract that introduced `key_order`, `partition_by` and index methods. */
+export declare const GRANULARITIES: readonly ["day", "month", "year"];
+/**
+ * Time partition sizes. No week: ClickHouse's `toStartOfWeek` depends on a mode, and a closed
+ * vocabulary has no modes.
+ */
+export declare const TEMPORAL_TYPES: readonly ["date", "timestamptz"];
+/**
+ * Neutral types a partition may be derived from. `timestamp` is absent on purpose: its ClickHouse
+ * column carries no zone, so the partition a value falls into follows the server's configured
+ * timezone, and a reconfigured server would put one key into two partitions for ever.
+ */
+export declare const POSTGRES_METHODS: readonly ["brin", "btree"];
+export declare const CLICKHOUSE_METHODS: readonly ["bloom_filter", "minmax", "set"];
+/** ClickHouse data-skipping index types. It has no B-tree; its primary index is `ORDER BY`. */
+export declare const INDEX_METHODS: readonly string[];
+export declare const GRANULARITY_RANGE: readonly [1, 1024];
+export declare const SET_ROWS_RANGE: readonly [1, 65536];
+export declare const PARTITION_FUNCTIONS: Readonly<Record<string, string>>;
+/** ClickHouse partition expressions, as its catalogue reports them back. */
+export declare const PARTITIONING_DIALECTS: ReadonlySet<string>;
+/**
+ * Dialects that render `partition_by`. PostgreSQL is absent on purpose: declarative partitioning
+ * there needs every partition created before a row can arrive, a lifecycle this product does not
+ * manage, and an unpartitioned table under a map that says otherwise would be a silent drop.
+ */
+export declare const METHODS_BY_DIALECT: Readonly<Record<string, readonly string[]>>;
+export type PartitionSpec = Readonly<{
+    field: string;
+    granularity: string;
+}>;
+type ErrorClass = new (message: string) => Error;
+/** An index's method. Absent means `btree`, what every map before contract 5 meant. */
+export declare function indexMethod(index: Readonly<Record<string, unknown>>): string;
+/** `key_order`: entity -> the physical order of that entity's key columns. */
+export declare function parseKeyOrder(raw: unknown, where: string, tables: Readonly<Record<string, string>>): Record<string, readonly string[]>;
+/** `partition_by`: entity -> `{"field": ..., "granularity": ...}`, and nothing else. */
+export declare function parsePartitionBy(raw: unknown, where: string, tables: Readonly<Record<string, string>>): Record<string, PartitionSpec>;
+/**
+ * Index definitions, validated where the map arrives rather than when DDL is rendered.
+ *
+ * The structural half applies to every contract and is a tightening; the method, granularity and
+ * `max_rows` keys are contract 5, because an earlier library ignores them and would build a B-tree
+ * where a later one builds BRIN from the same document.
+ */
+export declare function parseIndexes(raw: unknown, where: string, tables: Readonly<Record<string, string>>, columns: Readonly<Record<string, Readonly<Record<string, string>>>>, contract: number): Readonly<Record<string, unknown>>[];
+/**
+ * The two rules that need the model: a permutation of the key, and a partition on a key column.
+ *
+ * A renderer without the model repeats the key half against the keys it is given (`effectiveKey`,
+ * `partitionExpression`), which keeps the data rule true for a caller that skipped the model.
+ */
+export declare function checkAgainstModel(where: string, entity: string, key: readonly string[], fieldTypes: Readonly<Record<string, string>>, keyOrder: readonly string[] | undefined, partition: PartitionSpec | undefined): void;
+/** The key in physical order: `key_order` when present, the declared order otherwise. */
+export declare function effectiveKey(where: string, entity: string, key: readonly string[], keyOrder: Readonly<Record<string, readonly string[]>>, error?: ErrorClass): string[];
+/** `[function, field]` for a ClickHouse partition, after the key rule is checked again. */
+export declare function partitionExpression(where: string, entity: string, key: readonly string[], partition: PartitionSpec | undefined, error?: ErrorClass): readonly [string, string] | null;
+/**
+ * What a dialect renders, for whoever has to propose a physical design for it.
+ *
+ * The control plane hands the reference's version of this to a model; this port exists so that a
+ * TypeScript caller asking the same question gets the same answer, key for key.
+ */
+export declare function capabilities(dialect: string): Record<string, unknown>;
+/** One way an existing table differs from the physical design its layout declares. */
+export interface PhysicalFinding {
+    readonly table: string;
+    readonly aspect: string;
+    readonly declared: string;
+    readonly found: string;
+}
+export declare function describeFinding(finding: PhysicalFinding): string;
+export interface DeclaredIndex {
+    readonly name: string;
+    readonly method: string;
+    readonly columns: readonly string[];
+    readonly granularity: number | null;
+    readonly typeFull: string;
+}
+export interface DeclaredTable {
+    readonly table: string;
+    readonly key: readonly string[];
+    readonly partition: readonly [string, string] | null;
+    readonly indexes: readonly DeclaredIndex[];
+}
+export interface PhysicalDesign {
+    readonly tables: Readonly<Record<string, string>>;
+    readonly indexes: readonly Readonly<Record<string, unknown>>[];
+    readonly partitionBy: Readonly<Record<string, PartitionSpec>>;
+    readonly keyOrder?: Readonly<Record<string, readonly string[]>>;
+}
+/** The physical expectations of every table a layout names, in table order. */
+export declare function declaredTables(layout: PhysicalDesign, keys: Readonly<Record<string, readonly string[]>>): DeclaredTable[];
+/**
+ * ``a, `b c`, d`` -> `["a", "b c", "d"]`: names as ClickHouse's catalogue writes them.
+ *
+ * A name is bare or backtick-quoted with a backslash escaping the next character - the rule this
+ * library writes. Anything else throws: an expression the parser does not understand is not
+ * evidence that the table matches.
+ */
+export declare function parseIdentifierList(text: string): string[];
+/** ``toYYYYMM(`at`)`` -> `["toYYYYMM", "at"]`; an empty key -> `null`. */
+export declare function parsePartitionKey(text: string): readonly [string, string] | null;
+/**
+ * Throw when a table differs physically. Provisioning calls this; sessions do not.
+ *
+ * A session only reports (`session.physical`): the difference is performance, and turning it into
+ * the application's outage is what requirement 3.6 forbids. Provisioning is where a person applying
+ * a map can act on it.
+ */
+export declare function refuseFindings(findings: readonly PhysicalFinding[], error: ErrorClass): void;
+export {};